.TH RGET 1
.SH NAME
rget, rput \- network pipe
.SH SYNOPSIS
.B rput
.I keyword
.RI [ command
.RI [ arg " ...]]"
.br
.B rget
.B \-h
.I remote-host
.I keyword
.RI [ command
.RI [ arg " ...]]"
.SH DESCRIPTION
.de SP
.if t .sp 0.4
.if n .sp
..
.de XS	\" Example start
.PP
.RS
.nf
..
.de XE	\" Example end
.fi
.RE
.PP
..
.B Rput
and
.B rget
set up a TCP/IP channel to connect two processes together.  They can looked
upon as a remote pipe.  Consider the well known method of copying a
directory tree with
.BR tar :
.XS
(cd src && tar cf \- .) | (cd dst && tar xfp \-)
.XE
If the directory tree is to be copied to another machine then one can
use the following command on the source machine:
.XS
cd src && rput foo tar cf \- .
.XE
And on the destination machine:
.XS
cd dst && rget \-h \fIsource-machine\fP foo tar xfp \-
.XE
The
.I keyword
is used to cook up a TCP port number for the connection, it must be the same
for both commands to allow
.B rget
to find the remote
.BR rput .
It is customary to start
.B rput
first, although
.B rget
will retry for 2 minutes trying to connect to the remote
.BR rput.
.PP
After the connection is established either utility will execute
.I command
with the given arguments with the TCP channel as either standard output
(rput) or standard input (rget).
.B Rput
and
.B rget
do not stay around for the command to finish, they simply overlay themselves
with the command.  If no command is given then they will themselves copy
standard input into the TCP channel (rput), or output from the TCP channel
to standard output (rget).  So these two commands have the same effect:
.XS
rput foo tar cf \- .
tar cf \- . | rput foo
.XE
The second form has two processes copying data instead of just
.B tar
directly writing its output into the TCP channel.  There is a better way to
waste processor cycles, namely to save bandwidth:
.XS
cd src && tar cf \- . | rput foo compress
.SP
cd dst && rget \-h \fIsource-machine\fP foo uncompress | tar xfp \-
.XE
.B Rput
and
.B rget
can be very useful in the windowed environments we use these days.  The
.B rput
can be typed into the window that has a shell running on one machine, and
the
.B rget
is then typed into the window that has a shell running on another machine.
This is easier than one of the two well known forms that use
.BR rsh :
.XS
cd src && tar cf \- . | rsh dest-machine "cd dst && tar xfp \-"
.SP
cd dst && rsh source-machine "cd src && tar cf \- ." | tar xfp \-
.XE
Especially since these forms require that one must be able to use
.B rsh
without a password, which may not always be the case.
.PP
The
.I keyword
can be any string of characters of any length.  The characters binary values
are multiplied together, bit 15 is set and the result is truncated to 16
bits to make it a port number in the anonymous port space (32768 \- 65535).
The port may be in-use on the source machine, but there is a small chance
of this happening, and if so simply choose another keyword.  (This does
mean that
.B rput
and
.B rget
are only useful interactively, because a connection can't be guaranteed.)
.SH OPTIONS
.TP
.BI \-h " remote-host"
The name of the remote host that
.B rget
must contact to find the
.BR rput .
This option is currently mandatory.  The author is planning on letting
.B rget
find
.B rput
with UDP broadcasts or multicasts.  (This to make the
.B rget
call symmetric with
.BR rput ,
of course, not just to save a few keystrokes.)
.SH "SEE ALSO"
.BR rsh (1).
.SH DIAGNOSTICS
.TP 5
rput: Address in use
If the port computed out of
.I keyword
is already in use.
.SH AUTHOR
Kees J. Bot (kjb@cs.vu.nl)