CMD(3)                      (hosted)                       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 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 contains a clone file
          and zero or more numbered directories.  Each directory rep-
          resents 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 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(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 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

     CMD(3)                      (hosted)                       CMD(3)

               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 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,

     CMD(3)                      (hosted)                       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).
               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 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.

        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 interpreted 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 ser-
          vices 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 iden-
          tity of the user that started emu(1). Each connection has
          its own name space.

     CMD(3)                      (hosted)                       CMD(3)

          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 inter-
          preter.  The arguments are otherwise unmodified.  In partic-
          ular, 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.)

     SOURCE
          /emu/port/devcmd.c
          /emu/*/cmd.c

     SEE ALSO
          emu(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 success-
          fully.