cmd - interface to host operating system commands

bind -a '#C' /

/cmd/clone
/cmd/<n>/ctl
/cmd/<n>/data
/cmd/<n>/status

Description

The cmd device provides an interface to commands on the host operating system. By convention, this kernel device (#C) is bound to the root directory (with the -a option). After binding the entry point to this facility, the file /cmd/clone is available. Opening that file provides a handle for launching a command, managing the command's I/O, and checking the command's status.

clone

Opening /cmd/clone creates or allocates a currently unused directory, <n> (where n is a decimal integer), under /cmd. Directory n contains files ctl, data, and status. The file descriptor returned from the open of clone provides access to the /cmd/<n>/ctl file selected by cmd for subsequent operations.

ctl

Reading /cmd/<n>/ctl via the file descriptor returned from opening
/cmd/clone provides n, a value that can be used to construct filenames for the related files. Writes to /cmd/<n>/ctl must be of the format:

	exec oscmd args...

Prior to launching the command cmd prints at the console a line (128 bytes, maximum) of the format:

	devcmd: 'oscmd args...' pid pid

The string between the single quotes matches the command written to
/cmd/<n>/ctl and pid is the number in decimal format of the process running the emulator. Each field is separated by a single blank.

File offset is ignored for both reading and writing.

Note: For Windows systems, the ctl file transforms all slashes to backslashes before the command is executed.

data

Reading /cmd/<n>/data obtains the data that the command is writing to its standard output and standard error.

Writing to /cmd/<n>/data sends the data into the command's standard input.

status (read-only)

Reading /cmd/<n>/status provides a status line (to a maximum of 128 bytes) of the format:

	cmd/n refcnt state cmd args...

where each field separator is a single blank. The meaning of each field is:


n	The directory n where status resides.
refcnt	The number (decimal) of open file descriptors for /cmd/<n>/ctl.
state	The status of the interface in directory /cmd/<n>. States are shown below.
cmd [args]...	The active command. Output only for state Execute.

States

A cmd directory <n> can be in one of the following states


Open	Allocated for use but not yet running a command.
Execute	Running a command
Close	Command completed. Available for reallocation via /cmd/clone.

Directory management

Once closed, a directory <n> created by cmd persists and is reused by cmd in response to later openings of /cmd/clone. The cmd device only creates a new directory when all others, if any, are in use.

Command execution

Unix systems

The command is run via the /bin/sh program as follows

	/bin/sh -c 'cmd args...'

Emulator run by root:

If available, the emulator runs the command with a host user ID (uid) and host group ID (gid) corresponding to Inferno's representation for the user's identity. If not available, the emulator runs the command with uidnobody and gidnobody.

Emulator not run by root:

Commands are run on the host with the same host identity as the emulator

Windows systems

The command must be a binary executable (not built into the command interpreter) in the current path.

The command is always run with the same host identity as the emulator.