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 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 installs an exception handler for the duration of the loop Page 1 Plan 9 (printed 10/31/24) SH-STD(1) SH-STD(1) 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 and restored from the environment in a similar way Page 2 Plan 9 (printed 10/31/24) SH-STD(1) SH-STD(1) 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 (128 bytes in utf(6) representation). Con- trol 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 sta- tus. 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 Limbo's exception handling statement. Specifi- cally, the pattern is a string that matches liter- ally, except that a trailing `*' character will match any sequence of characters. If an exception is caught, rescue executes 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 10/31/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. Note that this command is now deprecated in favour of the <{} redirection operator built in to the shell. ${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 particular, the following code, written to print a message a filename ends in .b will not work: it will always print Page 4 Plan 9 (printed 10/31/24) SH-STD(1) SH-STD(1) ``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) Page 5 Plan 9 (printed 10/31/24)