NAME

       sockdown - shutdown(2) a socket

       netpipes 4.2

SYNOPSIS

       sockdown [ fd [how] ]

DESCRIPTION

       sockdown  performs  the  shutdown(2)  system  call  on  one of its file descriptors specified by fd.  The
       possible values for how are

       ┌───────────┬─────────────────────────────────────────────────────────┐
       │ writeonly │ convert to write-only file descriptor                   │
       │ 0         │ convert to write-only file descriptor                   │
       │ writeonly │ symbolic for same as above                              │
       │ 1         │ convert to read-only file descriptor                    │
       │ readonly  │ symbolic for same as above                              │
       │ 2         │ complete shutdown.  no more reads or writes are allowed │
       │ totally   │ symbolic for same as above                              │
       └───────────┴─────────────────────────────────────────────────────────┘

       The default fd is 1 (stdout) and the default how is 1.

EXAMPLES

       Imagine you have a machine that can perform a service (in  this  case  conversion  from  ASCII  to  fancy
       postscript) :

       server$ faucet 3000 --in --out enscript -2rGhp -

       You may then connect to it with a hose.  However, the first example enters deadlock :

       client$ hose server 3000 -in -out \
            sh -c " cat blah.txt & cat > blah.ps "

       The  enscript  blocks  waiting  for  input  from  the socket because not all of the client processes have
       exited.  While the cat blah.txt is finished, the cat > blah.ps is not, and will not be finished until the
       remote enscript process finishes writing.  The enscript process will  not  finish  writing  until  it  is
       finished  reading,  but that client->server half of the socket is still open and will not be closed until
       all the client processes are done.  The result is deadlock.

       So, we use sockdown to close half of the pipe

       client$ hose server 3000 -in -out \
            sh -c " ( cat blah.txt ; sockdown ) & cat > blah.ps "

       This way when the cat blah.txt is done, half of the socket is shut down and the remote  enscript  process
       runs  out  of  input,  causing  it  to  flush  its output and exit, so eventually the whole mess finishes
       cleanly.

       Note: the & on the hose is necessary to prevent another deadlock.  If we simply used the ;  to  serialize
       the  two  cat  processes it is possible that the enscript would fill up its write buffer before the first
       cat was done causing both processes to block and preventing the second cat from draining the pipe.

       Of course, that idiomatic usage of hose is so useful that it is a special form:

       client$ hose server 3000 -slave < blah.txt > blah.ps

       Ian Stirling <root@mauve.demon.co.uk> informs me that sockdown  can  be  used  in  Linux's  /proc/pid/fd/
       directories  to tear down hung network connections.  I have since used this myself on a wedged MOMspider.
       To try this, you have to know the PID of the program and the file descriptor of the  wedged  socket  (can
       sometimes  be  found by running strace and see if the program is stuck in a read(2) system call).  If the
       PID is 991 and the socket's descriptor is 5, you do this as root:

       bash# sockdown 1 2 > /proc/991/fd/5

ERRORS

       Socket operation on non-socket

       Invalid argument (seen on Solaris) The fd you specified does not refer to a socket.   This  happens  when
       you  run  sockdown  by itself (it is unlikely that any of the file descriptors attached to an interactive
       shell are actually sockets) or if you goof up your faucet/hose command and forgot to dup(2) one  of  your
       descriptors.

       Bad file number You gave it a bad file number for fd.  If you have enough skill to actually generate this
       error, you probably know what is wrong.

       If you encounter any other errors, clue me in.

SEE ALSO

       netpipes (1) faucet (1), hose (1), getpeername (1), socket (2), shutdown (2),

NOTES

       Any  normal  human  would  assume  a  program  this  simple  has  to be bug free, but I am an experienced
       programmer.

       Just avoid doing anything funky like passing sockdown strings and it should serve you well.   You  should
       not have to pass it any arguments unless you are doing something fairly funky.

       Perhaps I should ditch the shutdown -a semantics on hose since a sockdown 1 2 would do the job.

CREDITS

       Ian Stirling <root@mauve.demon.co.uk>, for the idea of using this program in /proc on a Linux machine.

COPYRIGHT

       Copyright (C) 1995-1998 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/

                                                  July 7, 1998                                       SOCKDOWN(1)