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)