clive man orig - 1

User's manual. Section 1.

XCMD(1): execute commands

USAGE

DESCRIPTION

Xcmd executes command upon user request by watching a run directory. By default, the run directory is /zx/run/sys, where sys is the system name. It contains one directory per command to be run. Each command directory includes some or all of these files:

args:: Command line for the command. The command will not be started until this file is found. This file is usually the last file created (using a single write) to let the command run. It is started by running rc -c with the contents of args as an argument. Use exec before the command line if there is a single command to let signals work as expected.
in:: Standard input for the command (optional). Defaults to an empty file.
out:: Standard output for the command (optional). Created when the command is started.
err:: Standard error for the command (optional). Created when the command is started unless it already exists, in which case it is appended.
sig:: Created by the user to send a signal to the command. Signals are described later.
at:: If this file exists it must contain five fields describing the minute, hour, day, month, weekday when the command must be started (or * for any).
restart:: If this file exists, the command is restarted when it dies. This is done by sending a TERM signal, killing it one second later, and restarting the command as it was done the first time. This file is ignored if at exists.
bin:: If this file exists, the file path it contains is watched and, when changed, causes the command to restart. Used to restart the command when it binary file is updated. This file is ignored if at exists.
exit:: Created when the command exists, to record its exit status.
X:: Any other file corresponds to the name of an environment variable for the command. The value of the variable is set to the file contents.

When a command terminates its directory is left around for inspection. The user may remove it when done with the command.

While a command runs it may be sent the following signals by writing the corresponding string into the sig file in the command directory:

kill:: Kills the command.
quit:: Send a quit signal to the command. For clive commands this dumps the command stacks before exiting.
intr:: Send an interrupt signal to the command.
stack:: Ask the command to dump its stacks for debugging.

The signals may take some time to be delivered. When they are posted, the sig file is removed.

Commands are run by default by the rc shell. Any other shell indicated must understand the -c flag as rc does. Signals are posted to the shell process started by xcmd and thus it is important to use exec in the args file when feasible. Otherwise the signals will be posted to the shell and not to the command it runs.

EXAMPLE

All examples assume xcmd is running and uses /zx/sys/nautilus as its run directory.

Run date:

    > mkdir /zx/sys/nautilus/date
    > echo exec date > /zx/sys/nautilus/date/args
    ... and later...
    > cat /zx/sys/nautilus/date/out

Run the dump each day at 5am:

    > c=/zx/sys/nautilus/dump
    > mkdir $c
    > echo '0 5 * * *' > $c/at
    > echo exec zxdump -1 -d /dump -v lsub!/home/lsub > $c/args

Run zx and restart it when the binary is updated or if it dies.

    > c=/zx/sys/nautilus/zx
    > mkdir $c
    > touch $c/restart
    > echo /zx/bin/darwin_amd64/zx > $c/bin
    > echo exec zx  lsub!/home/lsub!rw dump!/home/dump!ncro >$c/args

Ask zx to dump its stacks:

    > echo stack >/zx/sys/nautilus/zx/sig
    ... and later...
    > cat /zx/sys/nautilus/zx/err

Kill zx:

    > echo kill >/zx/sys/nautilus/zx/sig

Once any of these is done we can remove the command directory.

SOURCE

/zx/sys/src/clive/cmd/xcmd

BUGS

Only clive commands understand the stack signal. For portability, the run directory is polled and thus actions may take some time to be performed.