os(1): add c implementation of inferno os command and cmd(3) device manpages

this is a reimplementation of infernos os(1) command, which
allows running commands in the underhying host operating
system when inferno runs in hosted mode (emu). but unlike
inferno, we want to use it to run commands on the client
side of a inferno or drawterm session from the plan9 cpu
server, so it defaults to /mnt/term/cmd for the mountpoint.

1 files changed, 97 insertions, 0 deletions

diff --git a/sys/man/1/os b/sys/man/1/os
new file mode 100644
index 000000000..708db1c67
--- /dev/null
+++ b/sys/man/1/os
@@ -0,0 +1,97 @@
+.TH OS 1
+.SH NAME
+os \- interface to host OS commands (drawterm only)
+.SH SYNOPSIS
+.B os
+[
+.B -b
+] [
+.B -m
+.I mountpoint
+] [
+.BI -d " dir"
+] [
+.B -n
+] [
+.BI -N " level"
+]
+.I cmd
+[
+.IR arg ...
+]
+.SH DESCRIPTION
+.I Os
+uses a
+.IR cmd (3)
+device to execute a command,
+.IR cmd ,
+on a host system.
+If the
+.B -m
+option is given,
+.I os
+uses the device at
+.IR mountpoint ,
+otherwise it is asssumed to be at
+.BR /mnt/term/cmd .
+.PP
+The
+.B -d
+option causes the command to run in directory
+.IR dir ;
+an error results and the command will not run if
+.I dir
+does not exist or is inaccessible.
+The standard output and standard error of the command appear on the standard output
+and standard error streams of the
+.I os
+command itself.
+.I Os
+copies the standard input to the remote command's standard input; redirect
+.IR os 's
+input to
+.B /dev/null
+if there is no input to the command.
+.I Os
+terminates when
+.I cmd
+does, and its exit status reflects the status of
+.I cmd
+(if available).
+.PP
+If the
+.I os
+command is killed or exits (eg, for lack of input and output),
+the host's own process control operations are used to (attempt to) kill
+.IR cmd ,
+if it is still running.
+The
+.B -b
+(background) option suppresses that behaviour.
+.PP
+The
+.B -n
+option causes
+.I cmd
+to run with less than normal priority (`nice').
+The
+.B -N
+option sets low priority to a particular
+.I level
+from 1 to 3.
+.SH FILES
+.B /mnt/term/cmd/clone
+.SH SOURCE
+.B /sys/src/cmd/os.c
+.SH "SEE ALSO"
+.IR rcpu (1),
+.IR cmd (3)
+.SH DIAGNOSTICS
+The exit status of
+.I os
+reflects any error that occurs when starting
+.I cmd
+and, if it starts successfully, the status of
+.I os
+is the exit status of
+.IR cmd .