SH-STD(1) SH-STD(1)
NAME
std, if, while, ~, no, !, apply, getlines, status, pctl, fn,
and, or, raise, rescue, hd, tl, index, split, join, pid,
parse, pctl, env - standard shell builtins module.
SYNOPSIS
load std
! command
~ value [ pattern... ]
no [ arg... ]
and command...
apply command [ arg... ]
getlines [ separators ] command
flag f [ +- ]
for var in [ arg... ] command
fn name command
if condition action [ condition action ]... [ elseaction ]
or command...
pctl flag...
raise name
rescue pattern rescueblock command
status value
subfn name command
if [ condition action ]... [ elseaction ]
while condition command
${hd list}
${index number list}
${pid}
${split [ separators ] arg}
${join separator list}
${tl list}
${parse arg]
${pipe ( from | to | fdnum ) command}
${env}
DESCRIPTION
Std is a loadable module for sh(1) that provides the equiva-
lent of a ``standard library'' for the shell, including a
set of control-flow constructs and some other miscellaneous
commands. In the following descriptions, if an argument is
executed, then it should be a braced block suitable for exe-
cuting by sh. A true exit status is defined to be nil; any
non-nil exit status is false. Unless otherwise stated, the
return value of a command is that of the last command that
it executed. If invalid arguments are passed to any com-
mand, a usage exception is raised, and a message printed to
stderr.
Each of the looping commands for, apply, while, and getlines
Page 1 Plan 9 (printed 11/17/24)
SH-STD(1) SH-STD(1)
installs an exception handler for the duration of the loop
to catch the exceptions break and continue. If a break
exception is caught, the loop is terminated; if a continue
exception is caught, the loop will continue executing as
usual. The commands are as follows:
! ! inverts the exit status of a command (non-null
is changed to null, null is changed to non-null).
~ ~ matches value against each pattern in turn,
returning true if any of them match and false oth-
erwise. The patterns are of the same form as
those accepted by the shell for filename pattern
matching except that / is not treated specially.
(see filepat(2)). Patterns must be quoted to stop
the shell from interpreting them.
no True if there are no arguments. Useful for testing
if there are any items in a list without counting
the items with $#.
and And evaluates each command in turn until one
returns false.
apply Apply evaluates command once for each arg, passing
it in the variable $1.
getlines Getlines reads lines from the standard input, exe-
cuting command for each line, setting the environ-
ment variable $line to the line read, with any
terminating character removed. If separators is
given, a line is terminated when any character in
separators is found; the default separator string
is a single newline character.
flag Either set (+), clear (-), or test (neither + or
-) the flag f, where f is a single character, one
of the command line flags to sh (see sh(1)).
fn Fn defines a new builtin command named name; when
run, this command evaluates command. The command
is stored in the environment variable fn-name; any
variables of this form found when when std is
loaded will be defined in this way. If command is
not given, then the builtin will be removed.
subfn Subfn is similar to fn except that it defines a
new substitution builtin name. When name is
invoked, it creates a new local variable result
and executes command. The value of $result when
command has terminated is the value yielded by the
substitution builtin name. Command is stored in
Page 2 Plan 9 (printed 11/17/24)
SH-STD(1) SH-STD(1)
and restored from the environment in a similar way
to fn, except that sfn-name is used as the name of
the environment variable.
if If executes condition; if it returns true, then
action is executed, otherwise each of the next
condition-action pairs is evaluated in the same
way; if no condition is satisfied, then elseaction
will be executed, if present.
for For is similar to apply; it runs command once for
each arg, but it performs a local assignment of
arg to var each time.
or Or evaluates each command in turn until one
returns true.
pctl Pctl is an interface to the Inferno system call
sys-pctl(2); each argument specifies one bit in
the bitmask passed to that function. The possible
flags are newfd, forkfd, newns, forkns, newpgrp
and nodevs. See sys-pctl(2) for details of the
meaning of these flags. Pctl returns true.
raise Raise raises the exception name; name will be
truncated if it is longer than that allowed by
raise (see sys-exception(2)). Control will be
transferred to the innermost rescue block in the
same process that matches name. If there is no
rescue block in place, the current process will
exit, yielding name as its exit status. If no
name is given, the exception named in $exception
is raised; if this is null, a bad raise context
exception is raised. The default command prompt
catches all exceptions.
rescue Rescue executes command with an exception handler
installed for the duration of the call. It will
catch all exceptions with a name matching pattern,
where pattern is of the same form accepted by
rescue (see sys-exception(2)); i.e. an exact
match, or a prefix followed by an asterisk (*)
which will match an exception starting with the
prefix. If an exception is caught, rescue exe-
cutes rescueblock, setting $exception to the name
of the exception raised.
status returns its first argument word as its exit sta-
tus, or nil if none is given.
while While repeatedly executes condition and then
action until condition does not return true.
Page 3 Plan 9 (printed 11/17/24)
SH-STD(1) SH-STD(1)
${env} Env yields a list of the names of all currently
set non-nil environment variables.
${hd} Hd yields the first of its arguments, or nil if
there are no arguments.
${index} Index yields the n'th element in its argument
list, indexed from 1. N must be a decimal inte-
ger.
${join} Join yields a single element which is the concate-
nation of all the elements in list separated by
separator. If there are no elements in list, it
yields an empty string. The shell operator $"var
is exactly equivalent to ${join ' ' $var}.
${parse} Parse parses arg according to the usual syntax
rules, raising a parse error exception if it
fails. Arg must be a well-formed command block
surrounded by braces. Parse yields a functionally
equivalent version of arg.
${pid} Pid yields the process id of the current process.
${pipe} Pipe runs command asynchronously, with one of its
file descriptors connected to a bidirectional
pipe. The first argument to pipe determines which
file descriptor is connected: if the argument is
from, its standard output is connected; if the
argument is to, its standard input is connected;
otherwise file descriptor fdnum is connected.
Pipe yields the name of a file that can be opened
to access the other end of the pipe. This allows
the construction of non-linear pipelines. For
example, the following runs two commands old and
new and uses cmp to compare their outputs
cmp ${pipe from {old}} ${pipe from {new}}
${split} Split splits arg into list elements at every point
where one or more characters in separators appear.
If separators is not given, the value of $ifs is
used.
${tl} Tl yields all but the first of its arguments, or
nil if there are no arguments.
Syntactic considerations
It is worth being aware of a few pitfalls that await the
user of some of these commands. Unlike other shells, the
syntax of sh does not include the syntax of the control flow
commands, so it is important to be aware of the rules that
govern the gathering of the arguments for a command. In
Page 4 Plan 9 (printed 11/17/24)
SH-STD(1) SH-STD(1)
particular, the following code, written to print a message a
filename ends in .b will not work: it will always print
``file is Limbo source''.
and
{~ $filename '*.b'}
{echo file is Limbo source}
This is because newlines separate shell commands, so the
above code first invokes and with no arguments, and then
each of the braced block commands on each subsequent line.
It is usual to use round brackets in order to group together
arguments on separate lines, e.g.
and (
{~ $filename '*.b'}
{echo file is Limbo source}
)
This has the originally intended meaning.
FILES
/tmp/pipe.*d Temporary placeholder directory for named
pipes.
/tmp/pipes/* Mount point for named pipes.
SOURCE
/appl/cmd/sh/std.b
SEE ALSO
sh(1), sh-expr(1), sh-tk(1)
BUGS
As the shell does not know about functions, the whatis com-
mand cannot return information about their value. Use whatis
fn-name to find out the current definition of a function, or
whatis sfn-name to find out the current definition of a sub-
stitution function.
Page 5 Plan 9 (printed 11/17/24)