sys/man/3/cmd

   1 .TH CMD 3
   2 .SH NAME
   3 cmd \- interface to host operating system commands
   4 .SH SYNOPSIS
   5 .B bind -a '#C' /
   6 .PP
   7 .B /cmd/clone
   8 .br
   9 .BI /cmd/ n /ctl
  10 .br
  11 .BI /cmd/ n /data
  12 .br
  13 .BI /cmd/ n /stderr
  14 .br
  15 .BI /cmd/ n /status
  16 .br
  17 .BI /cmd/ n /wait
  18 .SH DESCRIPTION
  19 .I Cmd
  20 provides a way to run commands in the underlying operating system's
  21 command interpreter of drawterm or when Inferno is running hosted.
  22 It serves a three-level directory that is conventionally bound
  23 behind the root directory.
  24 The top of the hierarchy is a directory
  25 .BR cmd ,
  26 that contains a
  27 .B clone
  28 file and zero or more numbered directories.
  29 Each directory represents a distinct connection to the host's command interpreter.
  30 The directory contains five files:
  31 .BR ctl ,
  32 .BR data ,
  33 .BR stderr ,
  34 .B status
  35 and
  36 .BR wait ,
  37 used as described below.
  38 Opening the
  39 .B clone
  40 file reserves a connection: it is equivalent to opening the
  41 .B ctl
  42 file of an unused connection directory, creating a new one if necessary.
  43 .PP
  44 The file
  45 .B ctl
  46 controls a connection.
  47 When read, it returns the decimal number
  48 .I n
  49 of its connection directory.
  50 Thus, opening and reading
  51 .B clone
  52 allocates a connection directory and reveals the number of the allocated directory,
  53 allowing the other files to be named (eg,
  54 .BI /cmd/ n /data\fR).
  55 .PP
  56 .B Ctl
  57 accepts the following textual commands, allowing quoting as interpreted by
  58 .IR parsecmd (2):
  59 .TP
  60 .BI "dir " wdir
  61 Run the host command in directory
  62 .IR wdir ,
  63 which is a directory
  64 .IR "on the host system" .
  65 Issue this request before starting the command.
  66 By default, commands are run in the Inferno root directory on the host system.
  67 .TP
  68 .BI "exec " "command args ..."
  69 Spawn a host process to run the
  70 .I command
  71 with arguments as given.
  72 The write returns with an error, setting the error string, if anything prevents
  73 starting the command.
  74 If write returns successfully, the command has started, and its standard input and
  75 output may be accessed through
  76 .BR data ,
  77 and its error output accessed through
  78 .B stderr
  79 (see below).
  80 If arguments containing white space are quoted (following the conventions of
  81 .IR rc (1)
  82 or
  83 .IR parsecmd (2)),
  84 they are requoted by
  85 .I cmd
  86 using the host command interpreter's conventions so that
  87 .I command
  88 sees exactly the same arguments as were written to
  89 .BR ctl .
  90 .TP
  91 .B kill
  92 Kill the host command immediately.
  93 .TP
  94 .B killonclose
  95 Set the device to kill the host command when the
  96 .B ctl
  97 file is closed (normally all files must be closed, see below).
  98 .TP
  99 .BI nice " \fR[\fPn\fR]\fP"
 100 Run the host command at less than normal scheduling priority.
 101 Issue this request before starting the command.
 102 The optional value
 103 .IR n ,
 104 in the range 1 to 3,
 105 indicates the degree of `niceness' (default: 1).
 106 .PP
 107 The
 108 .B data
 109 file provides a connection to the input and output of a previously-started
 110 host command.
 111 It must be opened separately for reading and for writing.
 112 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
 113 equivalent of `write to closed pipe'.
 114 When opened for writing, data written to the file
 115 can be read by the command on its standard input; when closed, further reads by
 116 the command will see the host equivalent of `end of file'.
 117 (Unfortunately there is no way to know when the command needs input.)
 118 .PP
 119 The
 120 .B stderr
 121 file provides a similar read-only connection to the error output from the command.
 122 If the
 123 .B stderr
 124 file is not opened, the error output will be discarded.
 125 .PP
 126 Once started, a host command runs until it terminates or until it is killed,
 127 by using the
 128 .B kill
 129 or
 130 .B killonclose
 131 requests above, or by closing all
 132 .BR ctl ,
 133 .B data
 134 and
 135 .B wait
 136 files for a connection.
 137 .PP
 138 The read-only
 139 .B status
 140 file provides a single line giving the status of the connection (not the command), of the form:
 141 .IP
 142 .BI cmd/ "n opens state wdir arg0"
 143 .PP
 144 where the fields are separated by white space. The meaning of each field is:
 145 .TP
 146 .I n
 147 The
 148 .B cmd
 149 directory number.
 150 .TP
 151 .I opens
 152 The decimal number of open file descriptors for
 153 .BR ctl ,
 154 .B data
 155 and
 156 .BR wait .
 157 .TP
 158 .I state
 159 The status of the interface in directory
 160 .IR n :
 161 .RS
 162 .TF Execute
 163 .TP
 164 .B Open
 165 Allocated for use but not yet running a command.
 166 .TP
 167 .B Execute
 168 Running a command.
 169 .TP
 170 .B Done
 171 Command terminated: status available in the
 172 .B status
 173 file (or via
 174 .BR wait ).
 175 .TP
 176 .B Closed
 177 Command completed. Available for reallocation via
 178 .BR clone .
 179 .RE
 180 .PD
 181 .TP
 182 .I wdir
 183 The command's initial working directory on the host.
 184 .TP
 185 .I arg0
 186 The host command name (without arguments).
 187 .PP
 188 The read-only
 189 .B wait
 190 file must be opened before starting a command via
 191 .BR ctl .
 192 When read, it blocks until the command terminates.
 193 The read then returns with a single status line, to be
 194 parsed using
 195 .B tokenize
 196 (see
 197 .IR getfields (2)).
 198 There are five fields:
 199 host process ID (or 0 if unknown);
 200 time the command spent in user code in milliseconds (or 0);
 201 time spent in system code in milliseconds (or 0);
 202 real time in milliseconds (or 0);
 203 and a string giving the exit status of the command.
 204 The exit status is host-dependent, except that an empty string
 205 means success, and a non-empty string contains a diagnostic.
 206 .PP
 207 .SS "Command execution"
 208 In all cases, the command runs in the host operating system's
 209 own file name space.
 210 All file names will be interpreted in that space, not Plan 9's.
 211 For example, on Unix
 212 .B /
 213 refers to the host's file system root, not Plan 9's;
 214 the effects of mounts and binds will not be visible.
 215 .SH "SEE ALSO"
 216 .IR os (1)
 217 .SH DIAGNOSTICS
 218 A
 219 .B write
 220 to
 221 .B ctl
 222 returns with an error and sets the error string if
 223 a command cannot be started or killed successfully.