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 operat-
ing 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, cre-
ating 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 com-
mand. 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
Page 1 Plan 9 (printed 12/22/24)
CMD(3) CMD(3)
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 com-
mand. The optional value n, in the range 1 to 3, indi-
cates 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, fur-
ther 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,
Page 2 Plan 9 (printed 12/22/24)
CMD(3) CMD(3)
data and wait.
state
The status of the interface in directory n:
Open Allocated for use but not yet running a com-
mand.
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 con-
tains 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 inter-
preted in that space, not Plan 9's. For example, on Unix /
refers to the host's file system root, not Plan 9'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 success-
fully.
Page 3 Plan 9 (printed 12/22/24)