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(10.2):
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:
where the fields are separated by white space. The meaning of each field is:
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 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.
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 connection 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, provided the drive letter precedes the whole name to prevent its interpretation as a command option.)
|cmd(3)||Rev: Tue Mar 31 02:42:38 GMT 2015|