Provided by: netpipes_4.2-7_amd64 bug

NAME

       hose - the client end of a BSD network pipe

       netpipes 4.2

SYNOPSIS

       hose  hostname  port  (--in|--out|--err|--fd n|--slave|--netslave|--netslave1|--netslave2)
       [--verbose] [--unix]  [--localport  port]  [--localhost  addr]  [--retry  n]  [--delay  n]
       [--shutdown    [r|w][a]   ]   [--noreuseaddr]   [-[i][o][e][#3[,4[,5...]]][s][v][u]]   [-p
       local-port] [-h local-host] command args

DESCRIPTION

       hose attempts to provide the functionality of pipes over the network.  It behaves  as  the
       client  end  of a server-client connection.  When used with faucet(1) it can function as a
       replacement for

       tar -cf - . | rsh other "cd destdir; tar -xf -"

       faucet and hose are especially useful when you don't have easy non-interactive  access  to
       the destination machine.

OPTIONS

       hose  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.)

       hose then tries to connect to the foreign machine hostname with 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 information.

       hose then exec(2)s a command with args.

       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.
       hose just passes bytes without mucking with them.

       The  --netslave* options are variants on the --slave theme.  Whereas --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.

       --netslave closes down the connection when it encounters EOF in either direction.

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

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

       The --verbose 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.

       The --unix 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.

       --retry n allows the user to specify that hose should retry  the  connect(2)  call  for  n
       times  (or  forever  if  n  is  negative).   --delay n specifies how many seconds to delay
       between tries.

       --shutdown is used to control two behaviors.  The first set is controlled by the  `r'  and
       `w'  flags.   If the `r' is present, then hose will close 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 will 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, --out, and --err 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 then hose
       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', `a'.

       By default, hose performs a

       which  prevents  the ``Address in use'' problem that ``plagued'' netpipes versions 4.0 and
       earlier.  --noreuseaddr tells hose 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 exits.

SHORT FLAGS

       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:

       ┌──────┬──────────────┐
       │Short │ Long         │
       │  iin           │
       │  oout          │
       │  eerr          │
       │ #nfdn          │
       │  sslave        │
       │  vverbose      │
       │  qquiet        │
       │  uunix         │
       │  plocalport    │
       │  hlocalhost    │
       └──────┴──────────────┘
       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).

EXAMPLES

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

       tar -xf - .

       The  --in  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.

SEE ALSO

       netpipes (1), faucet (1), sockdown (1), getpeername (1), socket  (2),  bind  (2),  connect
       (2), shutdown (2), services (5), gethostbyaddr (3)

NOTES

       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.  --foreignport will accept a connection
       from any of the internet numbers associated with the host name.

CREDITS

       Thanks to Steve Clift <clift@ml.csiro.au> 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 <smd@hrt213.brooks.af.mil> 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  <fischer@ucet.ufl.edu>  finally  prodded  me  into  fixing  the  old  lame
       non-handling of multi-homed host.

COPYRIGHT

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

       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.

AUTHOR

       Robert Forsman
        thoth@purplefrog.com
        Purple Frog Software
        http://web.purplefrog.com/~thoth/

                                         October 28, 1998                                 HOSE(1)