
\refentry id=plash:

\refmeta~
\refentrytitle- plash
\manvolnum- 1

\refnamediv~
\refname- plash
\refpurpose- Shell for running programs with minimum authority

{\refsynopsisdiv:
\synopsis:
plash {\optional:{\option:--rcfile} {\r:file}}
      {\optional:{\option:-c} {\r:command}}
}


{\refsect1: \title- Description
\ps:

Plash is the Principle of Least Authority shell.  It lets you run
Linux programs with access only to the files and directories they need
to run.  Programs are given access to files which were passed as
command line arguments.
}

{\refsect1: \title- Options

\dl:

\dt\userinput- {\option:--rcfile} {\r:file}
{\dd\ps:
    Executes the given script on startup.  Does not switch off
    interactive mode.

    By default, the shell does not read any scripts on startup.}

\dt\userinput- {\option:-c} {\r:command}
\dd\ps~
    Execute the given command, and then exit.  Disables interactive mode.

}

{\refsect1: \title- Argument lists

\dl:

\dt\userinput- \r+arglist1 => \r+arglist2
\dd\para~
    By default, files and directories are passed as read-only.  The
    "=>" operator lets you pass files and directories with read-write
    access.  Objects to the right of "=>" are passed as read-write
    slots, so the object doesn't have to exist in advance.

\dt\userinput- \r+arglist1 + \r+arglist2
\dd\para~
    Files and directories that appear to the right of the "+" operator
    are not included in the argument list (the one used in execve()),
    but they are attached into the file namespace of the process.

\dt\userinput- '{\r:string}'
\dt\userinput- "{\r:string}"
\dt\userinput- -{\r:string}
\dd\para~
    Arguments that are not filenames should be quoted, unless they
    begin with '-'.

\dt\userinput- {\r:pathname}={\r:expr}
\dd\para~
    You can attach objects to arbitrary points in the file namespace.
    Here, {\r:expr} typically evaluates to a file, directory, or
    executable object.  This will include {\r:pathname} in the argument
    list.

\dt\userinput- \{ \r+arglist \}
\dd\para~
    You can limit the scope of "+" or "=>" using curly brackets.

\dt\userinput- >{\r:pathname}
\dt\userinput- <{\r:pathname}
\dt\userinput- {\r:n}>{\r:pathname}
\dt\userinput- {\r:n}<{\r:pathname}
\dt\userinput- {\r:n}>&{\r:n}
\dt\userinput- {\r:n}<&{\r:n}
\dd\para~
    IO redirection.  You can change the file descriptors that are
    passed to the process.

}

{\refsect1: \title- Example commands

\dl:

\dt\userinput- ls .
\dd\para~
    Arguments that were implicit before must now be made explicit.
    With the Bourne shell or Bash you can write `ls' to list the
    current directory's contents.  With Plash you must add `.' to
    grant access to the current directory.

\dt\userinput- gcc -c foo.c => -o foo.o + .

\dt\userinput- make + => .

\dt\userinput- tar -cvzf { => foo.tar.gz } dir1

\dt\userinput- grep 'pattern' file | less
\dd\para~
    Pipes work as in conventional shells.

\dt\userinput- !!bash
\dd\para~
    If you want to execute a command in the conventional way --
    without running the process with a virtualised filesystem, in a
    chroot jail, etc. -- you can prefix it with "!!".  This can be
    applied to individual command invocations in a pipeline.  The
    syntax for command invocations is the same whether "!!" is used or
    not, but when it is used, files listed after the "+" operator are
    ignored.

}

{\refsect1: \title- Commands

\dl:

\dt\userinput- cd \r+pathname
\dd\para~
    Sets the current directory.

\dt\userinput- fg \r+job-number
\dd\para~
    Puts the given job in the foreground.  (Job numbers are not prefixed
    with `%', unlike in Bash.)

\dt\userinput- bg \r+job-number
\dd\para~
    Puts the given job in the background.

\dt\userinput- def \r+var = \r+expr
\dd\para~
    Binds the object reference returned by the expression to a variable.

}


{\refsect1: \title- Expressions

\dl:

\dt\userinput- \r+var
\dd\para~
    Returns the object reference that is bound to the variable.

\dt\userinput- F \r+pathname
\dd\para~
    Returns the file or directory object at the given path.  Will
    follow symbolic links.

\dt\userinput- mkfs \r+args...
{\dd\ps:

    This expression returns a fabricated directory object containing
    the files listed in {\r:args}.  The object resides in a server
    process started by the shell.

    {\r:args} is processed in the same way as argument lists to
    commands, so read-only access will be given for files that are
    listed unless "=>" is used, and objects can be attached at points
    in the directory tree using {\r:path}={\r:expr}.

}

\dt\userinput- capcmd \r+command \r+args...
{\dd\ps:

    This built-in expression is similar to a normal command
    invocation, except that it expects the resulting process to return
    an object reference as a result.  The shell passes the process a
    return continuation argument ({\varname:return_cont}; see the
    {\envar:PLASH_CAPS} environment variable), which the process
    invokes with the result.

    This expression doesn't wait for the process to exit: the process
    will typically act as a server and stay running in the background
    to handle invocations of the object that it returned.

    If the process drops the return continuation without invoking it
    (which will happen if it exits without passing the reference on),
    the expression results in an error.

}

}


{\refsect1: \title- See also
  \ps:

  {\command:exec-object}, {\command:plash-opts}, {\command:plash-socket-publish}, {\command:plash-socket-connect}

  /usr/share/doc/plash
}

{\refsect1: \title- Author
  \ps:

  Mark Seaborn <mseaborn@onetel.com>
}
