CMD(3)                        (emu)                        CMD(3)

     NAME
          cmd - interface to host operating system commands

     SYNOPSIS
          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, when running emu(1). By convention, this
          kernel device (#C) is bound to the root directory (with the
          -a option).

          Opening the clone file provides a handle for starting a com-
          mand, managing the command's I/O, and checking the command's
          status.  It creates or allocates a currently unused direc-
          tory, n under /cmd (where n is a decimal integer).  It con-
          tains the files ctl, data, and status.  The file descriptor
          returned from the open of clone provides access to the ctl
          file of the directory selected by cmd.

          Reading ctl via the file descriptor returned from opening
          clone provides the directory number, n, which can then be
          used to construct filenames for the related files.  Writes
          to ctl must have the format:

               exec oscmd args ...

          File offset is ignored for both reading and writing.

          Reading data obtains the data that the command writes to its
          standard output and standard error.  Writing to data sends
          the data into the command's standard input.

          The read-only status file provides a status line (to a maxi-
          mum of 128 bytes) of the format:

               cmd/n refcnt state cmd arg ...

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

          n    The cmd directory number.

          refcnt
               The number (decimal) of open file descriptors for ctl.

     Page 1                       Plan 9            (printed 12/21/24)

     CMD(3)                        (emu)                        CMD(3)

          state
               The status of the interface in directory n:

               Open     Allocated for use but not yet running a com-
                        mand.
               Execute  Running a command
               Close    Command completed. Available for reallocation
                        via clone.
          cmd arg ...
               The active command. Output only for state Execute.
        Command execution
          On Unix systems, the command is run via /bin/sh as follows:

               /bin/sh -c 'cmdargs...'

          The command will be run 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, as user and
          group nobody.

          On Plan 9, the command is run via /bin/rc as follows:

               /bin/rc -c 'cmdargs...'

          The command will be run using the Plan 9 identity of the
          user that started emu(1).

          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). Furthermore, the ctl file transforms all
          slashes not quoted or escaped by backslashes to backslashes
          in the command string before executing it.

     SOURCE
          /emu/devcmd.c

     SEE ALSO
          emu(1), os(1)

     BUGS
          Standard output and standard error ideally should not be
          mingled.
          Exit status should be available.
          The maximum length of a command string is 128 bytes.

     Page 2                       Plan 9            (printed 12/21/24)