SOCKET(9)

📦
version 15.1 · 2 versions
, in freebsd 15.1, nixpkgs unstable

💖 SOCKET(9) — Kernel Developer's Manual 💖

okay bestie, welcome to the kernel socket interface page from the Kernel Developer's Manual. This is the part where we get the name and every single synopsis line, and yes, we are keeping all of it. No cap. 🫶

🎀 NAME 🎀

socket — the kernel socket interface. That's the whole name, that's the whole vibe. 💅

✨ SYNOPSIS ✨

First you pull in the socket headers, then you get every function signature in the order the manual lists them. Nothing skipped, nothing merged, nothing invented — literally all the prototypes are right here:

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

void
soabort(struct socket *so);

int
soaccept(struct socket *so, struct sockaddr *nam);

int
socheckuid(struct socket *so, uid_t uid);

int
sobind(struct socket *so, struct sockaddr *nam, struct thread *td);

void
soclose(struct socket *so);

int
soconnect(struct socket *so, struct sockaddr *nam, struct thread *td);

int
socreate(int dom, struct socket **aso, int type, int proto,
    struct ucred *cred, struct thread *td);

int
sodisconnect(struct socket *so);

void
sodtor_set(struct socket *so, void (*func)(struct socket *));

struct sockaddr *
sodupsockaddr(const struct sockaddr *sa, int mflags);

void
sofree(struct socket *so);

void
sohasoutofband(struct socket *so);

int
solisten(struct socket *so, int backlog, struct thread *td);

void
solisten_proto(struct socket *so, int backlog);

int
solisten_proto_check(struct socket *so);

struct socket *
sonewconn(struct socket *head, int connstatus);

int
sopoll(struct socket *so, int events, struct ucred *active_cred,
    struct thread *td);

int
sopoll_generic(struct socket *so, int events, struct ucred *active_cred,
    struct thread *td);

int
soreceive(struct socket *so, struct sockaddr **psa, struct uio *uio,
    struct mbuf **mp0, struct mbuf **controlp, int *flagsp);

int
soreceive_stream(struct socket *so, struct sockaddr **paddr,
    struct uio *uio, struct mbuf **mp0, struct mbuf **controlp,
    int *flagsp);

int
soreceive_dgram(struct socket *so, struct sockaddr **paddr,
    struct uio *uio, struct mbuf **mp0, struct mbuf **controlp,
    int *flagsp);

int
soreceive_generic(struct socket *so, struct sockaddr **paddr,
    struct uio *uio, struct mbuf **mp0, struct mbuf **controlp,
    int *flagsp);

int
soreserve(struct socket *so, u_long sndcc, u_long rcvcc);

void
sorflush(struct socket *so);

int
sosend(struct socket *so, struct sockaddr *addr, struct uio *uio,
    struct mbuf *top, struct mbuf *control, int flags,
    struct thread *td);

int
sosend_dgram(struct socket *so, struct sockaddr *addr, struct uio *uio,
    struct mbuf *top, struct mbuf *control, int flags,
    struct thread *td);

int
sosend_generic(struct socket *so, struct sockaddr *addr,
    struct uio *uio, struct mbuf *top, struct mbuf *control, int flags,
    struct thread *td);

int
soshutdown(struct socket *so, int how);

void
sotoxsocket(struct socket *so, struct xsocket *xso);

void
soupcall_clear(struct socket *so, int which);

void
soupcall_set(struct socket *so, int which,
    int (*func)(struct socket *, void *, int), void *arg);

void
sowakeup(struct socket *so, struct sockbuf *sb);

#include <sys/sockopt.h>

int
sosetopt(struct socket *so, struct sockopt *sopt);

int
sogetopt(struct socket *so, struct sockopt *sopt);

int
sooptcopyin(struct sockopt *sopt, void *buf, size_t len, size_t minlen);

int
sooptcopyout(struct sockopt *sopt, const void *buf, size_t len);

And that's the synopsis, bestie — every include, every return type, every parameter, every punctuation mark, all still exactly where the manual put it. 🌸

💖 DESCRIPTION 💖

okay so listen bestie — the kernel socket programming interface lets in-kernel consumers hang out with local and network socket objects basically the same way the socket(2) user API does. it's giving "same vibes, different tax bracket." these interfaces are literally made for distributed file systems and other network-aware kernel services ✨

the big glow-up difference: the user API operates on file descriptors, but the kernel interfaces operate directly on struct socket pointers. no fd middleman, we're going straight to the source 💅

some portions of the kernel API exist only to implement the user API, and are not expected to be used by kernel code. and lowkey the parts used by socket consumers vs. implementations of network protocols differ — some routines are only useful for protocol implementors. know your lane, iykyk 🦋

⚠️ except where otherwise indicated, socket functions may sleep, and are not appropriate for use in an interrupt thread context or while holding non-sleepable kernel locks. like, do not do that. fr fr. 😭

🎀 Creating and Destroying Sockets

a new socket may be created using socreate(). just like with socket(2), arguments specify the requested domain, type, and protocol via dom, type, and proto. the socket comes back through aso on success 🫶

plus: the credential used to authorize operations associated with the socket gets passed via cred (and will be cached for the lifetime of the socket), and the thread performing the operation via td.

🚨 Warning: authorization of the socket creation operation will be performed using the thread credential for some protocols (such as raw sockets). so your cred isn't doing all the heavy lifting in every case, bestie. read the room.

sockets may be closed and freed using soclose(), which has similar semantics to close(2) 👋

in certain circumstances, it's appropriate to destroy a socket without waiting for it to disconnect — that's what soabort() is for. and it is only appropriate for incoming connections which are in a partially connected state. specifics matter here:

  • it must be called on an unreferenced socket
  • it must be called by the thread which removed the socket from its listen queue, to prevent races
  • it will call into protocol code, so no socket locks may be held over the call 🔒💀
  • the caller of soabort() is responsible for setting the VNET context

the normal path to freeing a socket is sofree(), which handles reference counting on the socket. it should be called whenever a reference is released, and also whenever reference flags are cleared in socket or protocol code.

🚫 calls to sofree() should not be made from outside the socket layer — outside callers should use soclose() instead. stay in your lane and use the front door, okay? 🙈

🔌 Connections and Addresses

the sobind() function is equivalent to the bind(2) system call, and binds the socket so to the address nam. the operation would be authorized using the credential on thread td. classic bind behaviour, iconic 🌸

the soconnect() function is equivalent to the connect(2) system call, and initiates a connection on the socket so to the address nam. the operation will be authorized using the credential on thread td.

but here's the plot twist — unlike the user system call, soconnect() returns immediately. so the caller may msleep(9) on so->so_timeo while holding the socket mutex and waiting for the SS_ISCONNECTING flag to clear or so->so_error to become non-zero. and if soconnect() fails? the caller must manually clear the SS_ISCONNECTING flag. yes, by hand. no, the kernel won't do it for you ✨

a call to sodisconnect() disconnects the socket without closing it. just, like, unplugging. not yeeting 🔌

the soshutdown() function is equivalent to the shutdown(2) system call, and causes part or all of a connection on a socket to be closed down 💤

sockets are transitioned from non-listening status to listening with solisten(). and then they're in their listening era 👑

⚙️ Socket Options

the sogetopt() function is equivalent to the getsockopt(2) system call, and retrieves a socket option on socket so. the sosetopt() function is equivalent to the setsockopt(2) system call, and sets a socket option on socket so. get and set, the original duo 💅

the second argument in both sogetopt() and sosetopt() is the sopt pointer to a struct sopt describing the socket option operation. the caller-allocated structure must be zeroed, and then have its fields initialized to specify socket option operation arguments:

  • sopt_dir — set to SOPT_SET or SOPT_GET depending on whether this is a get or set operation. pick one, not both, we're not doing indecision 🎀
  • sopt_level — specify the level in the network stack the operation is targeted at; for example, SOL_SOCKET
  • sopt_name — specify the name of the socket option to set
  • sopt_val — kernel space pointer to the argument value for the socket option
  • sopt_valsize — size of the argument value in bytes

zero it first. i said what i said. 🧼

📞 Socket Upcalls

in order for the owner of a socket to be notified when the socket is ready to send or receive data, an upcall may be registered on the socket. the upcall is a function that will be called by the socket framework when a socket buffer associated with the given socket is ready for reading or writing 📬

soupcall_set() is used to register a socket upcall. the function func is registered, and the pointer arg will be passed as its second argument when it is called by the framework. the possible values for which are SO_RCV and SO_SND, which register upcalls for receive and send events, respectively 📥📤

the upcall function func() must return either SU_OK or SU_ISCONNECTED, depending on whether or not a call to soisconnected should be made by the socket framework after the upcall returns.

😤 the upcall func cannot call soisconnected itself — due to lock ordering with the socket buffer lock. that's the whole point of the return value, bestie.

only SO_RCV upcalls should return SU_ISCONNECTED. and when a SO_RCV upcall returns SU_ISCONNECTED, the upcall will be removed from the socket. one and done 💀

upcalls are removed from their socket by soupcall_clear(). the which argument again specifies whether the sending or receiving upcall is to be cleared, with SO_RCV or SO_SND. 🧹

🗑️ Socket Destructor Callback

a kernel system can use the sodtor_set() function to set a destructor for a socket. the destructor is called when the socket is about to be freed. it is called before the protocol detach routine. the destructor can serve as a callback to initiate additional cleanup actions 🫶

so like... your last chance to tidy up before the socket leaves the chat ✨

📤 Socket I/O

the soreceive() function is equivalent to the recvmsg(2) system call, and attempts to receive bytes of data from the socket so, optionally blocking awaiting for data if none is ready to read 😴

data may be retrieved directly to kernel or user memory via the uio argument, or as an mbuf chain returned to the caller via mp0, avoiding a data copy. the deets:

  • the uio must always be non-NULL. non-negotiable 🙅
  • if mp0 is non-NULL, only the uio_resid of uio is used
  • the caller may optionally retrieve a socket address on a protocol with the PR_ADDR capability by providing storage via non-NULL psa argument
  • the caller may optionally retrieve control data mbufs via a non-NULL controlp argument
  • optional flags may be passed to soreceive() via a non-NULL flagsp argument, and use the same flag name space as the recvmsg(2) system call

the sosend() function is equivalent to the sendmsg(2) system call, and attempts to send bytes of data via the socket so, optionally blocking if data cannot be immediately sent 📨

data may be sent directly from kernel or user memory via the uio argument, or as an mbuf chain via top, avoiding a data copy. only one of the uio or top pointers may be non-NULL — pick a lane, babe 🎀

an optional destination address may be specified via a non-NULL addr argument, which may result in an implicit connect if supported by the protocol 👀. the caller may optionally send control data mbufs via a non-NULL control argument. flags may be passed to sosend() using the flags argument, and use the same flag name space as the sendmsg(2) system call.

⚡ kernel callers running in an interrupt thread context, or with a mutex held, will wish to use non-blocking sockets and pass the MSG_DONTWAIT flag in order to prevent these functions from sleeping. protect your sleep schedule fr 💤

a socket can be queried for readability, writability, out-of-band data, or end-of-file using sopoll(). the possible values for events are as for poll(2), with symbolic values POLLIN, POLLPRI, POLLOUT, POLLRDNORM, POLLWRNORM, POLLRDBAND, and POLLINGEOF taken from <sys/poll.h> 🔍

calls to soaccept() pass through to the protocol's accept routine to accept an incoming connection 🤝

🧰 Socket Utility Functions

a whole little toolkit of helpers, obsessed:

  • the uid of a socket's credential may be compared against a uid with socheckuid() 🪪
  • a copy of an existing struct sockaddr may be made using sodupsockaddr() 📋
  • protocol implementations notify the socket layer of the arrival of out-of-band data using sohasoutofband(), so that the socket layer can notify socket consumers of the available data 📣
  • an "external-format" version of a struct socket can be created using sotoxsocket(), suitable for isolating user code from changes in the kernel structure 🛡️

that last one is genuinely so smart — future-proofing your user code against struct churn? main character energy 👑

🛠️ Protocol Implementations

protocol besties, this one's for you 🌈

protocols must supply an implementation for solisten(); such protocol implementations can call back into the socket layer using solisten_proto_check() and solisten_proto() to check and set the socket-layer listen state. these callbacks are provided so that the protocol implementation can order the socket layer and protocol locks as necessary 🔐

protocols must supply an implementation of soreceive(); the functions soreceive_stream(), soreceive_dgram(), and soreceive_generic() are supplied for use by such implementations.

protocol implementations can use sonewconn() to create a socket and attach protocol state to that socket. this can be used to create new sockets available for soaccept() on a listen socket. the returned socket has a reference count of zero — heads up, that's on you to deal with 🫡

protocols must supply an implementation for sopoll(); sopoll_generic() is provided for the use by protocol implementations.

the functions sosend_dgram() and sosend_generic() are supplied to assist in protocol implementations of sosend().

when a protocol creates a new socket structure, it is necessary to reserve socket buffer space for that socket, by calling soreserve(). the rough inverse of this reservation is performed by sorflush(), which is called automatically by the socket framework. so you don't have to remember that one 💅

when a protocol needs to wake up threads waiting for the socket to become ready to read or write, variants of sowakeup() are used.

🚨 the sowakeup() function should not be called directly by protocol code. instead use the wrappers sorwakeup(), sorwakeup_locked(), sowwakeup(), and sowwakeup_locked() for readers and writers, with the corresponding socket buffer lock not already locked, or already held, respectively. the _locked suffix is literally the whole tell, bestie 🔓🔒

the functions sooptcopyin() and sooptcopyout() are useful for transferring struct sockopt data between user and kernel code 📦✨

🐛 BUGS 🐛

okay bestie, gather round, because this is the part where the kernel devs themselves are like "yeah… it's a little messy in here" 😭 not me reading the source and finding out the vibes are inconsistent 💀

  • The credential situation is a whole mess — lowkey the biggest ick on this page. The way creds get picked is not consistent across all these different paths: explicitly passed credentials, credentials hung from explicitly passed threads, the credential sitting on curthread, and the cached credential from socket creation time. All of them, different rules, no cap. That inconsistency is fr fr asking for unexpected behaviour 🫠 and it's possible that several of the td arguments should actually be cred arguments, or honestly just… not be there at all. Like, the parameter list is having an identity crisis 🙈
  • SS_ISCONNECTING is on you, bestie — if soconnect() returns an error, the caller may need to manually clear SS_ISCONNECTING. It doesn't clean up after itself, so you gotta do it yourself 💅 do not skip this, the flag will just sit there being wrong.
  • MSG_DONTWAIT is giving broken promises — it is not implemented for sosend(), periodt. And it may not always work with soreceive() when zero copy sockets are enabled. So like… sometimes it works, sometimes it doesn't, and that's the vibe check you get 🔥 plan accordingly.
  • This manual page has lore gaps — it does not describe how to register socket upcalls, or how to monitor a socket for readability/writability without using blocking I/O. Those are real things you might want! They're just not on this page 📄✨
  • soref() and sorele() stay un-described, and mostly un-used — they're not documented here, and in most cases you should not use them. Why? Because the interactions are confusing and potentially incorrect when sorele() is the last call after soclose(). That's a giant red flag and I need you to respect it 🚩💀
basically: this page is iconic and you should absolutely use it, but the credential handling is a little chaotic, some flags are lies, and soref()/sorele() are giving "do not perceive me" energy. read the caveats, girlies, they're there for a reason 🫶

and that's a wrap on SOCKET(9), bestie!! 🎀 you made it all the way to the end, I'm so proud of you 🥹 this one came from Debian, dated September 6, 2022 — go forth and slay your socket code, but please, for me, clear that SS_ISCONNECTING flag 💖✨🦋

📦 where this page comes from