Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 man-
       ual  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	confu-
       sion.

       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 con-
       nected'	error.	This will happen with dismaying	frequency when the re-
       mote 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	Inter-
       net 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  no-
       tice.

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 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 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 getpeer-
       name to fail:

       client$ hose web.cise.ufl.edu 80	-in ./getpeername

       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 de-
       scriptors 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  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)

NAME | SYNOPSIS | DESCRIPTION | EASTER EGG | EXAMPLES | ERRORS | SEE ALSO | BUGS | NOTES | CREDITS | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getpeername&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help