| 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>
|
|---|
