GETPEERNAME(1)						      General Commands Manual						    GETPEERNAME(1)

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 con-
       trol).	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 con-
       nection 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 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 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)