GETPEERNAME(1)

💖 getpeername — bestie edition 💖

okay so real talk, this page lives in section 1 of the manual, and it's all about the netpipes 4.2 fam 🫶. Two programs, one brain cell: getpeername and getsockname. Let's get into it ✨

---

🌸 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 💅

NOT the manual page for the getpeername system call, bestie. That one lives in section 2. You get to it with something like man 2 getpeername or man -s 2 getpeername. Sorry for the confusion, genuinely 😭.

getpeername does a getpeername(2) system call on one of its file descriptors — the one you name with fd — and then prints out the results. The default fd is 0 (stdin). If you hand it the -sock argument, you can make getpeername act like getsockname. 💫

getsockname does a getsockname(2) system call on one of its file descriptors — again, that's fd — and prints the results. Default fd is 0 (stdin). Give it -peer and it'll act like getpeername instead. 🔁

⚠️ There's a severe limitation of getpeername, and I need you to hear me on this. If the remote process has closed the connection, getpeername will fail with a Socket is not connected error. And the way this happens with dismaying frequency when the remote process doesn't depend on the local process for input and it's only sending a lil bit of output before it closes the connection?? Tragic. Hopefully the practical uses of getpeername (if there are any 👀) won't run into this problem.

So here's the vibe: you use getpeername to find out the address of the opposite end of a socket. You use getsockname to find out the address of the local end of a socket. They are in fact the same program with different names. And for the rest of this description, we're gonna refer to both of them as getpeername. Same girl, different outfit 💅

getpeername knows how to display peer info about UNIX and Internet sockets. Try it on any other type of socket and it'll fail with an "unknown address family" error. If you regularly deal with strange sockets and you want getpeername to work with them — send me email, fr fr 📧.

• If the socket is a UNIX domain socket, getpeername prints the name of the file (which is the port) on a single line. And if -verbose was specified? Then you get the detailed report: 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, getpeername prints the port number on the first line and the numeric address on the second line. If -verbose was specified, you get the detailed report: 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. And on the rest of the lines it prints all the host names. 😤 so thorough

---

🥚 EASTER EGG 🥚

If you specify -verbose twice, the program will print a copyright notice. (iykyk 👑)

---

🌈 EXAMPLES 🌈

Okay so lore time: I originally designed getpeername so that a faucet-spawned shell script could find out who was talking to it (and maybe do some access control). I added getsockname for completeness. Now I realize getsockname is useful for multi-homing services. But the thing is — most software you'd want to understand multi-homing (httpd, ftpd) is already capable of doing it, and way 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

slay 💅

---

😭 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/

---

okay that's the whole page bestie, thanks for coming to my ted talk 🫶 this version is from the General Commands Manual, dated March 18, 1998, and it's the GETPEERNAME(1) page, periodt 💅✨