getpeername

NAME

       getpeername  -  get  information about this or that end of
       the socket's connection

SYNOPSIS

       getpeername [ -verbose ] [ -sock ] [ fd ]

       getsockname [ -verbose ] [ -peer ] [ fd ]

DESCRIPTION

       getpeername performs a getpeername(2) system call  on  one
       of its file descriptors specified by fd and prints out the
       results.  The default fd is 0 (stdin).  You may cause get-
       peername to behave like getsockname by providing the -sock
       argument.

       getsockname performs a getsockname(2) system call  on  one
       of its file descriptors specified by fd and prints out the
       results. The default fd is 0 (stdin).  You may cause  get-
       sockname to behave like getpeername by providing the -peer
       argument.

       There is a  severe  limitation  of  getpeername.   If  the
       remote process has closed the connection, getpeername will
       fail with a `Socket is not connected'  error.   This  will
       happen with dismaying frequency when the remote process is
       not dependent upon the local process for input and  it  is
       only  sending  small  amounts of output before closing the
       connection.  Hopefully the practical uses  of  getpeername
       (if there are any) will not exercise this problem.

         You  can  use getpeername to find out the address of the
       opposite end of a socket.  You can use getsockname to find
       out the address of the local end of a socket.  They are in
       fact the same program with different names.  We will refer
       to  both  of them by the name getpeername in the following
       description.

       getpeername knows how to display  peer  information  about
       UNIX  and  Internet  sockets.   If  you  try  to use it on
       another type of socket, it  will  fail  with  an  "unknown
       address family" error.  If you regularly deal with strange
       sockets and wish getpeername to work with  them,  send  me
       email.

       If  the  socket  is a UNIX domain socket, then getpeername
       prints the name of the file (which is the port) on a  sin-
       gle line.  If -verbose was specified, getpeername prints a
       more detailed report consisting of the word `Unix' on  the
       first  line,  the  word `Port' on the second line, and the
       name of the file on the third line.

       If the socket is  an  Internet  socket,  then  getpeername
       prints  the  port number on the first line and the numeric
       address on the second line.  If  -verbose  was  specified,
       getpeername  prints  a  more detailed report consisting of
       the word `Internet' on the first line, the word `Port'  on
       the  second  line,  the  port numer on the third line, the
       word `Host' on the fourth line.  On the fifth and  follow-
       ing  lines it prints all of the numeric internet addresses
       followed by all the host names returned  by  the  gethost-
       byaddr(3) library routine.

EASTER EGG

         If  you specify -verbose twice, the program will print a
       copyright notice.

EXAMPLES

         I have a feeling any practical uses of  the  getpeername
       program are fairly complicated.  If you actually do use it
       in a non-trivial way, drop me a line.

              client$ hose mail.cis.ufl.edu smtp -in ./getpeername
              25
              128.227.224.13

         You connected to mail.cis.ufl.edu on the SMTP port (port
       25).  For a verbose report:

               aviator:80 $ ./hose mail.cis.ufl.edu smtp -in ./getpeername -v
              Internet
              Port
              25
              Host
              128.227.224.13
              128.227.100.196
              inlet.cis.ufl.edu

         Now let's give an example of a race condition which will
       cause getpeername to fail:

              client$ hose www.cis.ufl.edu 80 -in ./getpeername

         The HTTP daemon tries to read a request, finds that half
       of  the  full  duplex  connection  closed  (by the special
       behavior of the -in option on hose(1)) and drops the  con-
       nection  before getpeername can query the file descriptor.
       We can cause the HTTP daemon to wait  for  us  by  leaving
       both halves of the duplex connection open.

              client$ hose www.cis.ufl.edu 80 -fd0 ./getpeername -v
              Internet
              Port
              25
              Host
              128.227.224.13
              128.227.100.196
              inlet.cis.ufl.edu

        And,  finally, let's extract some useful information from
       our socket.

              client$ hose www.cis.ufl.edu 80 -fd0 sh -c " ./getpeername -v | \
                   tail +5 | egrep -v '^[0-9.]*$' | head -1"
              sand.cis.ufl.edu

ERRORS

       Socket operation on non-socket
         The fd you specified does not  refer  to  a  socket,  or
       refers  to  a  socket  that has been closed.  This happens
       when you run getpeername 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, or if the remote machine manages to close the
       connection before getpeername could run.

       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), sockdown(1), socket(2),
       shutdown(2),

NOTES

         Just avoid doing anything funky like passing getpeername
       strings and it should serve you well.

         DOH!  3.0 didn't use the ntohs macro on the port numbers
       so the output was bogus on machines with non-network-order
       port numbers (like Linux-i386).  3.1 fixed this.

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/