SOCKDOWN(1)						      General Commands Manual						       SOCKDOWN(1)

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 fin-
       ished, 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 possi-
       ble that the enscript would fill up its write buffer before the first cat was done causing both processes to block and preventing the  sec-
       ond 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 MER-
       CHANTABILITY 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)