CMD(3)CMD(3)
NAME
cmd – interface to host operating system commands
SYNOPSIS
bind -a ’#C’ /
/cmd/clone
/cmd/n/ctl
/cmd/n/data
/cmd/n/stderr
/cmd/n/status
/cmd/n/wait
DESCRIPTION
Cmd
provides a way to run commands in the underlying operating system’s
command interpreter of drawterm or when Inferno is running hosted.
It serves a three-level directory that is conventionally bound
behind the root directory.
The top of the hierarchy is a directory
cmd,
that contains a
clone
file and zero or more numbered directories.
Each directory represents a distinct connection to the host’s command interpreter.
The directory contains five files:
ctl,
data,
stderr,
status
and
wait,
used as described below.
Opening the
clone
file reserves a connection: it is equivalent to opening the
ctl
file of an unused connection directory, creating a new one if necessary.
The file
ctl
controls a connection.
When read, it returns the decimal number
n
of its connection directory.
Thus, opening and reading
clone
allocates a connection directory and reveals the number of the allocated directory,
allowing the other files to be named (eg,
/cmd/n/data).
Ctl
accepts the following textual commands, allowing quoting as interpreted by
parsecmd(2):
dir wdir
Run the host command in directory
wdir,
which is a directory
on the host system .
Issue this request before starting the command.
By default, commands are run in the Inferno root directory on the host system.
exec command args ...
Spawn a host process to run the
command
with arguments as given.
The write returns with an error, setting the error string, if anything prevents
starting the command.
If write returns successfully, the command has started, and its standard input and
output may be accessed through
data,
and its error output accessed through
stderr
(see below).
If arguments containing white space are quoted (following the conventions of
rc(1)
or
parsecmd(2)),
they are requoted by
cmd
using the host command interpreter’s conventions so that
command
sees exactly the same arguments as were written to
ctl.
kill
Kill the host command immediately.
killonclose
Set the device to kill the host command when the
ctl
file is closed (normally all files must be closed, see below).
nice [n]
Run the host command at less than normal scheduling priority.
Issue this request before starting the command.
The optional value
n,
in the range 1 to 3,
indicates the degree of ‘niceness’ (default: 1).
The
data
file provides a connection to the input and output of a previously-started
host command.
It must be opened separately for reading and for writing.
When opened for reading, it returns data that the command writes to its standard output; when closed, further writes by the command will receive the host
equivalent of ‘write to closed pipe’.
When opened for writing, data written to the file
can be read by the command on its standard input; when closed, further reads by
the command will see the host equivalent of ‘end of file’.
(Unfortunately there is no way to know when the command needs input.)
The
stderr
file provides a similar read-only connection to the error output from the command.
If the
stderr
file is not opened, the error output will be discarded.
Once started, a host command runs until it terminates or until it is killed,
by using the
kill
or
killonclose
requests above, or by closing all
ctl,
data
and
wait
files for a connection.
The read-only
status
file provides a single line giving the status of the connection (not the command), of the form:
cmd/n opens state wdir arg0
where the fields are separated by white space. The meaning of each field is:
n
The
cmd
directory number.
opens
The decimal number of open file descriptors for
ctl,
data
and
wait.
state
The status of the interface in directory
n:
Open
Allocated for use but not yet running a command.
Execute
Running a command.
Done
Command terminated: status available in the
status
file (or via
wait).
Closed
Command completed. Available for reallocation via
clone.
wdir
The command’s initial working directory on the host.
arg0
The host command name (without arguments).
The read-only
wait
file must be opened before starting a command via
ctl.
When read, it blocks until the command terminates.
The read then returns with a single status line, to be
parsed using
tokenize
(see
getfields(2)).
There are five fields:
host process ID (or 0 if unknown);
time the command spent in user code in milliseconds (or 0);
time spent in system code in milliseconds (or 0);
real time in milliseconds (or 0);
and a string giving the exit status of the command.
The exit status is host-dependent, except that an empty string
means success, and a non-empty string contains a diagnostic.
Command execution
In all cases, the command runs in the host operating system’s
own file name space.
All file names will be interpreted in that space, not Plan9’s.
For example, on Unix
/
refers to the host’s file system root, not Plan9’s;
the effects of mounts and binds will not be visible.
SEE ALSO
os(1)
DIAGNOSTICS
A
write
to
ctl
returns with an error and sets the error string if
a command cannot be started or killed successfully.