.TH uux "" "" Command
.PC "Execute a command on a remote system"
\fBuux [\-a \fIuser\^\fB] [\-rnpz] \fIcommand-string\fR
.PP
.HS
.SH Options:
.IC "\fB\-a \fIuser\fR"
Name \fIuser\fR as requester
.IC \fB\-C\fR
Copy local files to the spool directory
.IC \fB\-c\fR
Do not copy local files to the spool directory
.IC "\fB\-g \fIl\fR"
Set importance of transmission; \fIl\fR is a single ASCII character
.IC "\fB\-I \fIfile\fR"
Read configuration information from
.I file
.IC \fB\-j\fR
Print job identifiers on standard output
.IC \fB\-l\fR
Link local files into spool directory
.IC "\fB\-n\fR"
Suppress notification of command failure
.IC "\fB\-p\fR"
Input to \fBuux\fR is a pipe or input redirection
.IC "\fB\-r\fR"
Queue \fBuux\fR request; do not invoke \fBuucico\fR
.IC "\fB\-x \fIevent\fR"
Log each
.I event
in the execution of
.B uux
.IC "\fB\-z\fR"
Notify requestor when \fIcommand-line\fR succeeds
.HE
The command
.B uux
spools
.I command-string
for execution on a remote system.
Usually, it is invoked by software systems, in particular the mail system,
to request that work be performed on a remote system.
However, you can also invoke
.B uux
by hand to execute a task on a remote system.
.PP
For security reasons, you can execute on the remote system only the commands
that the remote system permits explicitly.
These commands are named in the entry for your system
in the remote system's copy of
.BR /usr/lib/uucp/sys .
.PP
If all permissions are in order,
.B uux
creates a file with the prefix
.B X.
in the remote system's directory \fB/usr/spool/uucp/\fIyoursystem\fR, where
.I yoursystem
is the name by which the remote system knows your system.
This file is then executed by the remote system's copy of the command
.BR uuxqt .
.PP
.I command-string
consists of a command name followed by zero or more arguments.
Both the command's name and the arguments may be prefixed
by a system name (sitename) and an exclamation mark.
Note that all special characters must be escaped or enclosed in
quotation marks to avoid being processed by your system's shell.
.PP
For example, the simplest form of the
.B uux
command is:
.DM
	uux host!command arg0 ... argN
.DE
.PP
where
.I host
is the name of the remote system being contacted, as defined in file
.BR /usr/lib/uucp/sys ,
.I command
is the name of the command to execute on the remote system, and
.I arg0
through
.I argN
are the arguments to
.IR command .
.PP
If an argument names a file, that file can reside on the remote system,
on your system, or on some third system.
For example, the command
.DM
	uux widget!lp /usr/sally/herfile
.DE
.PP
asks site
.B widget
to print its own file
.BR /usr/sally/herfile .
On the other hand, the command
.DM
	uux widget!lp !$HOME/myfile
.DE
.PP
requests that site
.B widget
print on its line printer the file
.B myfile
from your home directory on your home system.
Note that the `!' that prefixes
.B myfile
is shorthand for the name of your system.
Finally, the command
.DM
	uux widget!lp lepanto!/usr/fred/hisfile
.DE
.PP
requests that system
.B widget
print file
.BR /usr/fred/hisfile ,
which resides on the third site
.BR lepanto .
If
.B widget
does not know how to contact site
.BR lepanto ,
the command fails.
.PP
If you wish, you can embed the shell operators
`<', `>', `;', or `|' within a
.B uux
command.
This lets you construct a more powerful command than you could do otherwise.
Commands that contain these operators must be quoted, to ensure
that your shell does not interpret them.
For example, the command
.DM
	uux "widget!pr /usr/sally/herfile > lepanto!~/fred/hisfile"
.DE
.PP
tells
.B uux
to use
.B pr
to format its file
.BR /usr/sally/herfile ,
and write the output into file
.B /usr/spool/uucppublic/fred/hisfile
on site
.BR lepanto .
(Note that the tilde `~', as always, is a synonym for the home directory
of the user that is executing the command; and a
.B uux
command is always executed by user
.BR uucp
whose home directory is always
.BR /usr/spool/uucppublic .)
Again, the command fails if you do not have appropriate permissions on
.B widget
or if
.B widget
does not have appropriate permissions on
.BR lepanto .
.PP
The operator `-' lets you use the standard input when constructing a
.B uux
command.
For example, the command
.DM
	who | uux - widget!lp
.DE
.PP
executes the
.B who
command on your system, pipes the output to
.BR uux ,
and tells
.B uux
to invoke the command
.B lp
on remote system
.B widget
to print the list of users on your system.
.PP
.B uux
attempts to transfer any needed input files to the system that will
be executing the requested command.
You must enclose in parentheses any output files generated by
.IR command ,
to distinguish them from the names of input file.
.SH "Command-line Options"
.B uux
recognizes the following options:
.IP "\fB\-a \fIaddress\fR" 0.5i
Report the status of the job to
.IR address .
.IP \fB\-C\fR
Copy local files to the spool directory.
.IP \fB\-c\fR
Do not copy local files to the spool directory.
This is the default.
If the files are removed from their local directory before
.B uucico
processes them, the copy fails.
The files must be readable by the
.B uucico
as well as the by the user who invokes
.BR uux .
.IP "\fB\-g \fIgrade\fR"
Set the grade of the file-transfer command.
.I grade
is a single ASCII character, from `0' to `z';
the lower the ASCII value of
.IR grade ,
the more important the files.
.IP "\fB\-I \fIfile\fR"
Read configuration information from
.I file
instead of from the default file
.BR /usr/lib/uucp/sys .
.IP \fB\-j\fR
Print job identifiers on the standard output.
.B uux
creates a job identifier for each file-copying operation
required to perform the operation.
To cancel the copying of a file, pass the job identifier to the
.B uustat
with its option
.BR \-k .
.IP \fB\-l\fR
Link local files into the spool directory.
If a file cannot be linked because it is on a different device,
it is copied unless the
.B \-c
option also appears (in other words, use of
.B \-l
switches the default from
.B \-c
to
.BR \-C ).
If the files are changed before
.B uucico
processes them, the changed versions will be used.
The files must be readable by the
.B uucico
as well as by the user who invoked
.BR uux .
.IP \fB\-n\fR
Do not send mail about the status of a job, even if it fails.
The default is to send mail to the requester should the command fail.
.IP \fB\-\fR
.IS \fB\-p\fR
Read the standard-input device and pipe what is read into the
command to be executed.
.IP \fB\-r\fR
Queue the
.B uux
request but do not invoke
.B uucico
to perform the transfer.
The default is to initiate
.BR uucico .
.IP "\fB\-x \fIevent\fR"
Log each
.I event
in the execution of
.BR uux ,
where
.I event
is one of the following values:
.BR abnormal ,
.BR config ,
.BR spooldir ,
or
.BR execute .
A
.B \-x
option
can hold multiple events, each separated by commas; and a
.B uux
command line can hold more than
.B \-x
option.
.IP \fB\-z\fR
Notify requester should
.I command-string
fail.
.SH Examples
The following script prints files on a remote system.
The files named on the command line are sent unprocessed to system
.B prnsrvr
to be printed through that system's version of command
.BR lp .
Option
.B \-r
tells
.B uux
not to invoke
.B uucico
immediately, but merely spool the request for execution later.
.DM
	for i in $*
	do
		uux -r prnsrvr!lp !$i
	done
.DE
.PP
Please note that the `!' that prefixes string ``!$i'' indicates that the
file to be printed resides in the current directory on your home system.
.PP
The next example copies file
.B /foo
from system
.B george
and file
.B /bar
from system
.B norm
to your system and then invokes command
.B cmp
to compare their contents.
It writes the results of the comparison into file
.B /tmp/cmp.results
on your local system:
.DM
	uux -z "!cmp -l george!/foo norm!/bar >/tmp/cmp.results"
.DE
.PP
This command assumes that your system can talk to both
.B george
and
.BR norm ,
and that your system has permission to read file
.B /foo
on system
.B george
and file
.B /bar
on system
.BR norm .
Option
.B \-z
tells
.B uux
to send you mail when it has successfully completed the job.
.PP
The last example compiles file
.B mycode.c
on system
.BR cserver .
The command redirects all of the compiler's error messages into file
.B /tmp/errors
on your local system:
.DM
	uux 'cserver!cc -O -o (!mycode) !mycode.c > !/tmp/errors'
.DE
.PP
Note that the name of the output file
.B !mycode
is enclosed within parentheses.
This is to protect the `!' from being interpreted by
.BR uux ;
it will be interpreted by
.B uuxqt
on the remote system.
.SH "See Also"
.Xr "commands," commands
.Xr "UUCP," uucp
.Xr "uuxqt" uuxqt
.SH Notes
You cannot pipe the output from a command on one system into a command on
another.
If
.I command-line
consists of several commands that are connected by pipe characters `|', only
the first can be prefixed by a system name and `!'; every other command
within the pipeline will be executed on the system named by the first command.
For example, consider the command:
.DM
	uux "mwc!wrap -w80 -t4 < !myfile.c | prps | lp"
.DE
.PP
This command passes file
.B myfile.c
from the current directory on your current system to command
.B wrap
on system
.BR mwc
for processing; then pipes the output of
.B wrap
into
.B prps
on system
.B mwc
for transformation into PostScript; and then pipes the output of
.B prps
into
.BR lp ,
again on system
.BR mwc ,
for printing.
If you embed a `!' within the subsequent commands of a pipeline,
.B uux
will expand it into something quite unexpected (and probably unwelcome).
.PP
It is not a good idea to use the metacharacter `*' within
.IR command-line .
The odds that it will be expanded into what you want are very small.
.PP
Every command that you spool with
.B uux
is executed within a special execution directory on the remote system.
.II .Xqtdir
.II /usr/spool/uucp/.Xqtdir
(Under \*(CO, this directory is
.BR /usr/spool/uucp/.Xqtdir ;
it may vary on other systems.)
Before it executes the command, \*(UU copies into that special directory
each file that the command names, unless that file already resides on
the system within which the command is being executed.
For this reason, each file named in a
.B uux
command must be unique, regardless of its full path name.
For example, the following command will not work:
.DM
	uux  "marian!diff fred!/x/testfile ivan!/y/testfile > !xyz.diff"
.DE
.PP
It fails because
.B uux
(or, to be more accurate,
.BR uuxqt )
copies file
.B testfile
from system
.B fred
into its execution directory, then copy
.B testfile
from system
.B ivan
into the test directory.
The second copied
.B testfile
overwrites the first, and thus the command
.B diff
fails.
.PP
.II "Taylor, Ian Lance"
.B uux
was written by Ian Lance Taylor (ian@airs.com).
