Provided by: netpipes_4.2-7_amd64 bug

NAME

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

       netpipes 4.2

SYNOPSIS

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

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

DESCRIPTION

       This  is  not  the  manual  page  for the getpeername system call.  That manual page is in
       section 2.  You can access it using a command like  "man  2  getpeername"  or  "man  -s  2
       getpeername".  I apologize for the confusion.

       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 getpeername
       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  getsockname
       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  single  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.   Starting  on  the  fifth line it prints all the numeric internet addresses
       returned by the gethostbyaddr(3) library routine.  On the rest of the lines it prints  all
       the host names.

EASTER EGG

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

EXAMPLES

       I originally designed getpeername so that a faucet-spawned shell script could find out who
       was  talking  to  it  (and  maybe  perform  access  control).   I  added  getsockname  for
       completeness.   Now  I  realize  that  getsockname  is  useful  for multi-homing services.
       However, most software that you want to understand multi-homing (httpd, ftpd)  is  already
       capable  of  doing  it,  and much more efficiently than a script wrapper.  Still, it might
       come in handy some day.

       client$ hose mail.cise.ufl.edu smtp --in ./getpeername
       25
       128.227.205.210

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

       client$ hose mail.cise.ufl.edu smtp --in ./getpeername -v
       Internet
       Port
       25
       Host
       128.227.205.210
       fireant.cise.ufl.edu

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

       client$ hose web.cise.ufl.edu 80 -in ./getpeername
       ./getpeername: getpeername failed on descriptor 0: Socket is not connected

       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 connection
       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 web.cise.ufl.edu 80 -fd0 ./getpeername -v
       Internet
       Port
       80
       Host
       128.227.205.206
       flood.cise.ufl.edu

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

       client$ hose web.cise.ufl.edu 80 -fd0 sh -c " ./getpeername -v | \
            tail +5 | egrep -v '^[0-9.]*$' | head -1"
       flood.cise.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),

BUGS

       These  programs  are  vulnerable to reverse DNS lookup spoofing.  You probably want to add
       ``nospoof on'' to your /etc/host.conf.

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-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/

                                          March 18, 1998                           GETPEERNAME(1)