
=head1 NAME

plash - Shell for running programs with minimum authority

=head1 SYNOPSIS

B<plash> [B<--rcfile> I<file>]

=head1 DESCRIPTION

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.

=head1 OPTIONS

=over

=item
B<--rcfile> I<file>

Executes the given script on startup.  Does not switch off interactive
mode.

=back


=head1 ARGUMENT LISTS

=over

=item I<arglist1> => I<arglist2>

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.

=item I<arglist1> + I<arglist2>

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.

=item 'I<string>'

=item "I<string>"

=item -I<string>

Arguments that are not filenames should be quoted, unless they begin
with '-'.

=item I<pathname>=I<expr>

You can attach objects to arbitrary points in the file namespace.
Here, I<expr> typically evaluates to a file, directory, or executable
object.  This will include I<pathname> in the argument list.

=item { I<arglist> }

You can limit the scope of "+" or "=>" using curly brackets.

=item [I<n>]>I<pathname>

=item [I<n>]<I<pathname>

IO redirection.

=back


=head1 EXAMPLES

=over

=item ls .

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.

=item gcc -c foo.c => -o foo.o + .

=item make + => .

=item tar -cvzf { => foo.tar.gz } dir1

=item grep 'pattern' file | less

Pipes work as in conventional shells.

=item !!bash

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.

=back


=head1 COMMANDS

=over

=item B<cd> I<pathname>

Sets the current directory.

=item B<fg> I<job-number>

Puts the given job in the foreground.

=item B<bg> I<job-number>

Puts the given job in the background.

=item B<def> I<var> = I<expr>

Binds the object reference returned by the expression to a variable.

=back


=head1 EXPRESSIONS

=over

=item I<var>

Returns the object reference that is bound to the variable.

=item B<F> I<pathname>

Returns the file or directory object at the given path.  Will follow
symbolic links.

=item B<mkfs> I<args...>

This expression returns a fabricated directory object containing the
files listed in I<args>.  The object resides in a server process started
by the shell.

I<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 I<path>=I<expr>.

=item B<capcmd> I<command> I<args...>

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 (B<return_cont>; see the 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.

=back


=head1 SEE ALSO

exec-object(1), plash-opts(1)

/usr/share/doc/plash

=head1 AUTHOR

Mark Seaborn <mseaborn@onetel.com>
