CMD(3)CMD(3)NAMEcmd - 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 when Inferno is running hosted, in emu(1). It
serves a three-level directory that is conventionally bound behind the
root directory. The top of the hierarchy is a directory cmd, that con‐
tains a clone file and zero or more numbered directories. Each direc‐
tory represents a distinct connection to the host's command inter‐
preter. 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 con‐
nection 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 allo‐
cated directory, allowing the other files to be named (eg,
/cmd/n/data).
Ctl accepts the following textual commands, allowing quoting as inter‐
preted by parsecmd(10.2):
dir wdir
Run the host command in directory wdir, which is a directory on
the host system . Issue this request before starting the com‐
mand. By default, commands are run in the Inferno root direc‐
tory 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 suc‐
cessfully, 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 sh(1) or
parsecmd(10.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 previ‐
ously-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 com‐
mand 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).
Close 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 String->unquote
(see string(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 mil‐
liseconds (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 in which emu(1) was started. All file names will be inter‐
preted in that space, not Inferno's. For example, on Unix and Plan 9,
/ refers to the host's file system root, not Inferno's; the effects of
mounts and binds will not be visible; nor will Inferno services be
available except by network connection.
On Unix systems, the command is run by the execvp system call, using
the Unix user and group ID of the user that started emu(1), unless it
was started by the super-user, in which case cmd attempts to set the
Unix user ID and group ID to those of a Unix user corresponding to the
current Inferno user's name, and failing that, to user and group
nobody.
On Plan 9, the command is run with the system call exec, first trying
the command name as-is; if that fails and the name does not start with
#, /, ./ or ../, cmd attempts to exec /bin/command. The command runs
using the Plan 9 identity of the user that started emu(1). Each con‐
nection has its own name space.
On Windows systems, the command must be a binary executable (not built
into the command interpreter) in the current path. It is always run
with the same Windows user identity as started emu(1). The arguments
given to the exec request are requoted as described above so as to
present the same arguments to the command via the Windows command
interpreter. The arguments are otherwise unmodified. In particular,
no attempt is made to convert slashes to backslashes in a vain attempt
to convert file name syntax to Windows conventions. (In fact, most
Windows applications will accept / as a separate in file names, pro‐
vided the drive letter precedes the whole name to prevent its interpre‐
tation as a command option.)
SOURCE
/emu/port/devcmd.c
/emu/*/cmd.c
SEE ALSOemu(1), 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.
hosted CMD(3)
