sockdown

NAME

       sockdown - shutdown(2) a socket

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
              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 reads or writes allowed in the future
              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 eventu-
       ally 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.

ERRORS

       Socket operation on non-socket
         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 interac-
       tive 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

       ``Hi Mom! Hi Dad!''

COPYRIGHT

       Copyright (C) 1995 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@cis.ufl.edu
        Purple Frog Software
        http://www.purplefrog.com/~thoth/