Man Linux: Main Page and Category List

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)