Provided by: netpipes_4.2-8build1_amd64 
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)