.TH CMD 3 hosted.SH NAMEcmd \- interface to host operating system commands.SH SYNOPSIS.B bind -a '#C' /.PP.B /cmd/clone.br.BI /cmd/ n /ctl.br.BI /cmd/ n /data.br.BI /cmd/ n /stderr.br.BI /cmd/ n /status.br.BI /cmd/ n /wait.SH DESCRIPTION.I Cmdprovides a way to run commands in the underlying operating system'scommand interpreter when Inferno is running hosted, in.IR emu (1).It serves a three-level directory that is conventionally boundbehind the root directory.The top of the hierarchy is a directory.BR cmd ,that contains a.B clonefile and zero or more numbered directories.Each directory represents a distinct connection to the host's command interpreter.The directory contains five files:.BR ctl ,.BR data ,.BR stderr ,.B statusand.BR wait ,used as described below.Opening the.B clonefile reserves a connection: it is equivalent to opening the.B ctlfile of an unused connection directory, creating a new one if necessary..PPThe file.B ctlcontrols a connection.When read, it returns the decimal number.I nof its connection directory.Thus, opening and reading.B cloneallocates a connection directory and reveals the number of the allocated directory,allowing the other files to be named (eg,.BI /cmd/ n /data\fR)..PP.B Ctlaccepts the following textual commands, allowing quoting as interpreted by.IR parsecmd (10.2):.TP.BI "dir " wdirRun the host command in directory.IR wdir ,which is a directory.I "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..TP.BI "exec " "command args ..."Spawn a host process to run the.I commandwith arguments as given.The write returns with an error, setting the error string, if anything preventsstarting the command.If write returns successfully, the command has started, and its standard input andoutput may be accessed through.BR data ,and its error output accessed through.B stderr(see below).If arguments containing white space are quoted (following the conventions of.IR sh (1)or.IR parsecmd (10.2)),they are requoted by.I cmdusing the host command interpreter's conventions so that.I commandsees exactly the same arguments as were written to.BR ctl ..TP.B killKill the host command immediately..TP.B killoncloseSet the device to kill the host command when the.B ctlfile is closed (normally all files must be closed, see below)..TP.BI nice " \fR[\fPn\fR]\fP"Run the host command at less than normal scheduling priority.Issue this request before starting the command.The optional value.IR n ,in the range 1 to 3,indicates the degree of `niceness' (default: 1)..PPThe.B datafile provides a connection to the input and output of a previously-startedhost 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 hostequivalent of `write to closed pipe'.When opened for writing, data written to the filecan be read by the command on its standard input; when closed, further reads bythe command will see the host equivalent of `end of file'.(Unfortunately there is no way to know when the command needs input.).PPThe.B stderrfile provides a similar read-only connection to the error output from the command.If the.B stderrfile is not opened, the error output will be discarded..PPOnce started, a host command runs until it terminates or until it is killed,by using the.B killor.B killoncloserequests above, or by closing all.BR ctl ,.B dataand.B waitfiles for a connection..PPThe read-only.B statusfile provides a single line giving the status of the connection (not the command), of the form:.IP.BI cmd/ "n opens state wdir arg0".PPwhere the fields are separated by white space. The meaning of each field is:.TP.I nThe.B cmddirectory number..TP.I opensThe decimal number of open file descriptors for.BR ctl ,.B dataand.BR wait ..TP.I stateThe status of the interface in directory.IR n :.RS.TF Execute.TP.B OpenAllocated for use but not yet running a command..TP.B ExecuteRunning a command..TP.B DoneCommand terminated: status available in the.B statusfile (or via.BR wait )..TP.B CloseCommand completed. Available for reallocation via.BR clone ..RE.PD.TP.I wdirThe command's initial working directory on the host..TP.I arg0The host command name (without arguments)..PPThe read-only.B waitfile must be opened before starting a command via.BR ctl .When read, it blocks until the command terminates.The read then returns with a single status line, to beparsed using.B String->unquote(see.IR 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 stringmeans success, and a non-empty string contains a diagnostic..PP.SS "Command execution"In all cases, the command runs in the host operating system'sown file name spacein which.IR emu (1)was started.All file names will be interpreted in that space, not Inferno's.For example, on Unix and Plan 9,.B /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..PPOn Unix systems,the command is run by the.B execvpsystem call, using the Unix user and group ID ofthe user that started.IR emu (1),unless it was started by the super-user, in which case.I cmdattempts to set the Unix user ID and group ID to those of a Unix user corresponding tothe current Inferno user's name, and failing that, to user and group.BR nobody ..PPOn Plan 9,the command is run with the system call.BR exec ,first trying the.I commandname as-is;if that fails and the name does not start with.BR # ,.BR / ,.B ./or.BR ../ ,.I cmdattempts to exec.BI /bin/ command.The command runs using the Plan 9 identity ofthe user that started.IR emu (1).Each connection has its own name space..PPOn 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.IR emu (1).The arguments given to the.B execrequest are requoted as described above so as to present the samearguments 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 vainattempt to convert file name syntax to Windows conventions.(In fact, most Windows applications will accept.B /as a separate in file names, provided the drive letter precedes the wholename to prevent its interpretation as a command option.).SH SOURCE.B /emu/port/devcmd.c.br.B /emu/*/cmd.c.SH "SEE ALSO".IR emu (1),.IR os (1).SH DIAGNOSTICSA.B writeto.B ctlreturns with an error and sets the error string ifa command cannot be started or killed successfully.