SOCKETPAIR(2)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 SOCKETPAIR — create a pair of connected sockets 💖

okay bestie, we're in section 2 of the manual, the System Calls Manual, and this one is literally the blueprint for two lil sockets that are sooo obsessed with each other they're basically twins. no cap.

✨ LIBRARY ✨

Standard C Library (libc, -lc) — yeah girl, she's built in, you don't have to go hunting. 🫶

🎀 SYNOPSIS 🎀

#include <sys/types.h>
#include <sys/socket.h>

int
socketpair(int domain, int type, int protocol, int *sv);

🌸 DESCRIPTION 🌸

so the socketpair() system call creates an unnamed pair of connected sockets, right? and you get to pick the communications domain, the type, and — if you're feeling extra — the protocol too.

the descriptors you use to reference these brand new sockets get handed back to you in sv[0] and sv[1]. and here's the iconic part: the two sockets are indistinguishable. like, truly. no main character, no sidekick, just two icons serving the exact same face. 👑

also!! the SOCK_CLOEXEC and SOCK_NONBLOCK flags in the type argument apply to both descriptors. both of them. equal treatment. we love to see it. 💅

⭐ RETURN VALUES ⭐

  • if everything slays? the socketpair() function returns the value 0. ✨
  • if it does NOT slay? the value -1 comes back and the global variable errno gets set to tell you exactly what went wrong. 😭

💀 ERRORS 💀

the call succeeds unless — and bestie, listen, it's giving "here's the list of reasons it said no":

  • [EMFILE] — Too many descriptors are in use by this process. (you hoarded them. you did this. 🙈)
  • [EAFNOSUPPORT] — The specified address family is not supported on this machine. (not on this machine's bingo card.)
  • [EPROTONOSUPPORT] — The specified protocol is not supported on this machine. (same energy, different flag.)
  • [EOPNOTSUPP] — The specified protocol does not support creation of socket pairs. (it's just not that kind of protocol, ok?)
  • [EFAULT] — The address sv does not specify a valid part of the process address space. (that pointer is lost, fr fr. 💀)

🦋 SEE ALSO 🦋

pipe(2), read(2), socket(2), write(2)

go read those too, they're the friend group. iykyk. 🌈

👑 STANDARDS 👑

the socketpair() system call conforms to IEEE Std 1003.1-2001 (“POSIX.1”) and IEEE Std 1003.1-2008 (“POSIX.1”). certified. standards-compliant. periodt. ✨

🧚 HISTORY 🧚

the socketpair() system call appeared in 4.2BSD. she's been around since forever and she's still thriving. legacy icon behavior. 💜

🍓 BUGS 🍓

This call is currently implemented only for the Unix domain.

translation: it's Unix-domain-only right now. don't come at her asking for anything else. 😌

that's the whole page bestie, go make some sockets that are obsessed with each other 💖

this was brought to you by Debian, dated February 10, 2018, from the SOCKETPAIR(2) page — mwah, take care of her 🎀

📦 where this page comes from