Seth Woolley's Man Viewer

Manual for getpeername - man 1 getpeername

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

GETPEERNAME(1)                                                  GETPEERNAME(1)



NAME
       getpeername(1,2)  -  get  information about this or that end of the socket(2,7,n)'s
       connection

       netpipes 4.2


SYNOPSIS
       getpeername(1,2) [ -verbose ] [ -sock ] [ fd ]

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


DESCRIPTION
       This is not the manual page for the getpeername(1,2) system call.  That man-
       ual  page is in(1,8) section 2.  You can access(2,5) it using a command like "man(1,5,7)
       2 getpeername(1,2)" or "man(1,5,7) -s 2 getpeername(1,2)".  I apologize for  the  confu-
       sion.

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

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

       There is a severe limitation of getpeername(1,2).  If the remote process has
       closed the connection, getpeername(1,2) will fail with a `Socket is not con-
       nected'  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(1,2) (if(3,n) there are any) will not
       exercise this problem.

       You  can use getpeername(1,2) 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(1,8) fact the same program with different
       names.  We will refer to both of them by the name  getpeername(1,2)  in(1,8)  the
       following description.

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

       If the socket(2,7,n) is a UNIX domain socket(2,7,n), then getpeername(1,2) prints the name
       of the file(1,n) (which is the port) on a  single  line.   If  -verbose  was
       specified,  getpeername(1,2) 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(1,n) on the third line.

       If  the  socket(2,7,n) is an Internet socket(2,7,n), then getpeername(1,2) prints the port
       number on the first line and the numeric address on  the  second  line.
       If  -verbose  was  specified, getpeername(1,2) 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(1,5) names.


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


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

       client$ hose mail.cise.ufl.edu smtp --in ./getpeername(1,2)
       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(1,2) -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 getpeer-
       name to fail:

       client$ hose web.cise.ufl.edu 80 -in ./getpeername(1,2)

       The  HTTP  daemon  tries to read(2,n,1 builtins) 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(1,2) can query the file(1,n)
       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(1,2) -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(1,2) -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(2,7,n), or refers to a socket(2,7,n) that has been closed.  This happens  when
       you  run  getpeername(1,2)  by  itself  (it is unlikely that any of the file(1,n)
       descriptors attached to an interactive shell are actually sockets),  or
       if(3,n)  you  goof  up  your faucet/hose command and forgot to dup(2) one of
       your descriptors, or if(3,n) the remote machine manages to close(2,7,n) the connec-
       tion before getpeername(1,2) could run.

       Bad  file(1,n)  number  You  gave  it a bad file(1,n) number for fd.  If you have
       enough skill to actually generate this error(8,n), 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,7,n) (2), shutdown(2,8)
       (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(1,2) 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(1,3,5) 2 of the License, or (at  your
       option) any later version.

       This  program  is  distributed  in(1,8) 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(3,n) not, write(1,2) 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)

References for this manual (incoming links)