man/man1/rget.1

   1 .TH RGET 1
   2 .SH NAME
   3 rget, rput \- network pipe
   4 .SH SYNOPSIS
   5 .B rget
   6 .RB [ \-lcio ]
   7 .RB [ \-h
   8 .IR host ]
   9 .I key
  10 .RI [ command
  11 .RI [ arg " ...]]"
  12 .br
  13 .B rput
  14 .RB [ \-lcio ]
  15 .RB [ \-h
  16 .IR host ]
  17 .I key
  18 .RI [ command
  19 .RI [ arg " ...]]"
  20 .SH DESCRIPTION
  21 .de SP
  22 .if t .sp 0.4
  23 .if n .sp
  24 ..
  25 .de XS  \" Example start
  26 .SP
  27 .in +4m
  28 .nf
  29 ..
  30 .de XE  \" Example end
  31 .fi
  32 .in -4m
  33 .SP
  34 ..
  35 .B Rput
  36 and
  37 .B rget
  38 set up a TCP/IP channel to connect two processes together.  They can looked
  39 upon as a remote pipe.  Consider the well known method of copying a
  40 directory tree with
  41 .BR tar :
  42 .XS
  43 (cd src && tar cf \- .) | (cd dst && tar xfp \-)
  44 .XE
  45 If the directory tree is to be copied to another machine then one can
  46 use the following command on the source machine:
  47 .XS
  48 cd src && rput foo tar cf \- .
  49 .XE
  50 And on the destination machine:
  51 .XS
  52 cd dst && rget \-h \fIsource-machine\fP foo tar xfp \-
  53 .XE
  54 The
  55 .I key
  56 is either a port number in C style decimal, octal or hex, or a random string
  57 that is hashed to a port number.
  58 .B Rput
  59 uses this port number to open a TCP socket that
  60 .B rget
  61 using the same
  62 .I key
  63 can connect to.
  64 It is customary to start
  65 .B rput
  66 first, although
  67 .B rget
  68 will retry for 2 minutes trying to connect to the remote
  69 .BR rput.
  70 .PP
  71 After the connection is established either utility will execute
  72 .I command
  73 with the given arguments with the TCP channel as either standard output
  74 (rput) or standard input (rget).
  75 .B Rput
  76 and
  77 .B rget
  78 do not stay around for the command to finish, they simply overlay themselves
  79 with the command.  If no command is given then they will themselves copy
  80 standard input into the TCP channel (rput), or output from the TCP channel
  81 to standard output (rget).  So these two commands have the same effect:
  82 .XS
  83 rput foo tar cf \- .
  84 tar cf \- . | rput foo
  85 .XE
  86 The second form has two processes copying data instead of just
  87 .B tar
  88 directly writing its output into the TCP channel.  There is a better way to
  89 waste processor cycles, namely to save bandwidth:
  90 .XS
  91 cd src && tar cf \- . | rput foo compress
  92 .SP
  93 cd dst && rget \-h \fIsource-machine\fP foo uncompress | tar xfp \-
  94 .XE
  95 .B Rput
  96 and
  97 .B rget
  98 can be very useful in the windowed environments we use these days.  The
  99 .B rput
 100 can be typed into the window that has a shell running on one machine, and
 101 the
 102 .B rget
 103 is then typed into the window that has a shell running on another machine.
 104 This is easier than one of the two well known forms that use
 105 .BR rsh :
 106 .XS
 107 cd src && tar cf \- . | rsh dest-machine "cd dst && tar xfp \-"
 108 .SP
 109 cd dst && rsh source-machine "cd src && tar cf \- ." | tar xfp \-
 110 .XE
 111 Especially since these forms require that one must be able to use
 112 .B rsh
 113 without a password, which may not always be the case.
 114 .PP
 115 The
 116 .I key
 117 can be any string of characters of any length.  If its a number then it is
 118 used directly as the port number.  Otherwise the characters binary values
 119 are multiplied together, bit 15 is set and the result is truncated to 16
 120 bits to make it a port number in the anonymous port space (32768 \- 65535).
 121 The port may be in-use on the source machine, but there is a small chance
 122 of this happening, and if so simply choose another key.  (So if you use
 123 .B rput
 124 and
 125 .B rget
 126 in an unattended script then you should reserve a port number, otherwise
 127 a connection can't be guaranteed.)
 128 .SH OPTIONS
 129 .TP
 130 .B \-lcio
 131 These flags allow one to reverse the default connect/listen or input/output
 132 direction of
 133 .BR rput
 134 and
 135 .BR rget .
 136 Reversing the connection may be necessary if one of the two systems filters
 137 out connections to unknown ports.  For example:
 138 .XS
 139 rput \-c \-h \fIdestination-machine\fP foo tar cf \- .
 140 .SP
 141 rget \-l foo tar xfp \-
 142 .XE
 143 The
 144 .B \-io
 145 options can be used to choose which of standard input or output should be
 146 tied to the socket.  It's even possible to tie both input and output to the
 147 socket with
 148 .BR \-io,
 149 but only when executing a command.  This is probably the only use for these
 150 options, because one usually chooses the direction with the mnemonic put/get
 151 names.
 152 .TP
 153 .BI \-h " host"
 154 The name of the remote host that a connection must be made to.  It must be
 155 used with the program that is doing the connect, usually
 156 .BR rget .
 157 This option is currently mandatory.  The author is planning to increase
 158 ease of use by letting the programs find each other with UDP broadcasts
 159 or multicasts.
 160 .SH "SEE ALSO"
 161 .BR rsh (1).
 162 .SH DIAGNOSTICS
 163 .TP 5
 164 rput: Address in use
 165 If the port computed out of
 166 .I key
 167 is already in use.
 168 .SH AUTHOR
 169 Kees J. Bot <kjb@cs.vu.nl>