hose - the client end of a BSD network pipe
hose hostname port
) [ --verbose
] [ --unix
] [ --localhost addr
] [ --delay n
] [ --shutdown
[r|w][a] ] [ --noreuseaddr
[ -p local-port
] [ -h local-host
attempts to provide the functionality of pipes over the network. It
behaves as the client end of a server-client connection. When used with
it can function as a replacement for
tar -cf - . | rsh other "cd destdir; tar -xf -"
are especially useful when you don't have easy
non-interactive access to the destination machine.
creates a BSD socket and, if the --localport
option is used,
binds it to the port number (or service name) specified immediately
afterwards. If --localhost
is also specified then its argument is a
local address to bind to. ( --localhost
is only useful on machines with
multiple IP addresses.)
then tries to connect to the foreign machine hostname
foreign port port.
If successful hose
redirects the socket to stdin, stdout, stderr, and/or
arbitrary file descriptors according to the --in --out --err --fd
n flags. hose also automagically
shuts down the unused half of the connection if only --in
is specified or if only --out and/or --err
are specified. See the --shutdown option for more
then exec(2)s a command
However, the --slave
flag turns hose
into a primitive sort of
telnet. The command
is ignored. Instead, hose
goes into a loop
where it copies bytes from stdin to the socket, and bytes from the socket to
stdout. This is actually more useful than telnet because telnet tries to
perform interpretation on the byte stream and generally gets in your way.
just passes bytes without mucking with them.
options are variants on the --slave
will continue to forward data in one direction even after the
other has encountered EOF, --netslave
variants are more aggressive in
closing the entire socket. Before closing the socket, it attempts to flush any
data already in its own buffer. --slave
performs the shutdown(2) system
call when it encounters EOF on one direction, but the --netslave
variants don't because some network daemons are confused by it.
closes down the connection when it encounters EOF in either
closes down the connection when it encounters EOF while
reading stdin. Any data unread on the socket will be ignored. If it merely
encounters EOF on the socket, it will continue to read from stdin.
closes down the connection when it encounters EOF while
reading from the socket. Any data unread on stdin will be ignored. If it
merely encounters EOF on stdin, it will continue to read from the socket. This
mode can be useful with some web servers.
flag specifies that hose
should print information
about the host it connects to. This information includes the numeric host
address, host names, and foreign port numbers.
flag specifies that the port
is not an internet port
number or service name, but instead it is a filename for a UNIX domain socket.
This option may be simulated by using -unix-
as the host name to
connect to, or by renaming the hose
program to uhose
allows the user to specify that hose
the connect(2) call for n
times (or forever if n
specifies how many seconds to delay between tries.
is used to control two behaviors. The first set is controlled
by the `r' and `w' flags. If the `r' is present, then hose
half the connection to make it a read-only socket. If the child tries to
write, it will fail. If the remote connection tries to read, it will percieve
the socket as closed. If instead the `w' is present, then hose
close the other half of the connection to make it a write-only socket. If the
child tries to read, it will percieve the socket as closed. If the remote
connection tries to write, it will fail. The default behavior is to leave both
halves open, however the shutdown of half of the connection is automagically
done by certain combinations of the --in
flags. To suppress their automagic behavior you can use
(respectively) --fd 0, --fd 1, and --fd 2.
The other behavior is controlled by the `a' flag. If the `a' flag is present
will fork(2) before execcing the command
and when the
child exits it will perform a shutdown(2) with how=2. This closes both halves
of the connection. This option is not necessary for most applications since
the closing of the file descriptors is detected by the remote process, but
some less sophisticated network devices (such as printers) require a
shutdown(2) for proper operation. To make things perfectly clear, the list of
acceptable arguments to the --shutdown
option are `r', `w', `ra', `wa',
By default, hose
which prevents the ``Address in use'' problem that ``plagued'' netpipes versions
4.0 and earlier. --noreuseaddr
to skip that system
call, and revert to pre-4.1 behavior. Without this call, the port is not
always available for immediate reuse after the hose
To reduce the typing requirements for arguments (and to pay homage to the
age-old tradition of UNIX cryptotaxonomy) I have added some short forms of the
flags. Here is a correspondence chart:
See faucet(1) for a more detailed discussion of short flags. Their behavior
should be unsurprising. The flags that require separate arguments follow in
the tradition of tar(1).
This will connect to port 3000 on the machine reef and connect the socket to the
stdin of a tar command.
example$ hose reef 3000 --in tar -xf - .
The command actually exec(2)ed by the hose
tar -xf - .
option means that the input of the child process will have been
redirected into the socket connected to reef.
This connects to a UNIX domain socket in the current directory
example$ hose --unix- u-socket --in sh -c \
"unfunky.perl.script | dd of=sample.pgm"
The socket provides input to the sh command.
netpipes (1), faucet (1), sockdown (1), getpeername (1), socket (2), bind (2),
connect (2), shutdown (2), services (5), gethostbyaddr (3)
Doubtless there are bugs in this program, especially in the unix domain socket
portions. I welcome problem reports and would like to make these programs as
"clean" (no leftover files, sockets) as possible.
4.0 made the full-word arguments use -- like many GNU programs. They are still
available with a single - for backward-compatibility.
3.1 added the single-character flags.
Release 2.3 added support for multi-homed hosts: hosts with multiple internet
numbers (such as gateways). Before this faucet assumed that the first internet
number that gethostbyname returned was the only one. --foreignport
authentication was weakened by this inadequacy so I beefed up the algorithms.
will accept a connection from any of the internet numbers
associated with the host name.
Thanks to Steve Clift <email@example.com> for SGI (SysV) patches.
Many people complained about the old way of specifying the command. Thanks to
whoever gave me the alternative which is now implemented. It is much better.
Thanks to Sten Drescher <firstname.lastname@example.org> for the --retry and
--delay patches and giving me the idea for the --shutdown option. Evidently
some printer doesn't appreciate the socket being close(2)d.
Randy Fischer <email@example.com> finally prodded me into fixing the
old lame non-handling of multi-homed host.
Copyright (C) 1992-98 Robert Forsman
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 675 Mass
Ave, Cambridge, MA 02139, USA.
Purple Frog Software