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/