io_uring_prep_cmd_sock(3)

📦
version 2.15 · 2 versions
, in arch rolling, ubuntu stonking

💖 NAME 💖

okay so io_uring_prep_cmd_sock — that's the icon, the moment, and yes bestie she lives in the liburing manual 🌸 What she does? She prepares a command request for a socket. that's it, that's the job, she ate.

✨ SYNOPSIS ✨

#include <liburing.h>

void io_uring_prep_cmd_sock(struct io_uring_sqe *sqe,
                            int cmd_op,
                            int fd,
                            int level,
                            int optname,
                            void *optval,
                            int optlen);

🦋 DESCRIPTION 🦋

So io_uring_prep_cmd_sock(3) gets a cmd request ready for a socket, no cap. The submission queue entry sqe gets set up to use the socket file descriptor that fd points at, so you can kick off the command operation that cmd_op defines. main character setup energy fr fr 💅

This one's a generic function, which means every single command gets to bring its own personal level, optname and optval values. And optlen? That's how big the thing that optval points to is. slay.

🌈 Available commands 🌈

SOCKET_URING_OP_SIOCINQ

Returns how much queued unread data is chillin' in the receive buffer 📥

bestie, the socket must NOT be in LISTEN state, otherwise you get an error -EINVAL handed back in the CQE res field. rude but true.

For this command these arguments just are not used: level, optname, optval and optlen. they're literally just vibing there unused 🙈

A negative return value means an error.

Want the full lore on this command? go check unix(7).

Available since 6.7.

SOCKET_URING_OP_SIOCOUTQ

Returns how much unsent data is sitting in the socket send queue 📤

same warning as before, and it's important: the socket must NOT be in LISTEN state, otherwise an error -EINVAL shows up in the CQE res field.

For this command these arguments are not used: level, optname, optval and optlen. not even acknowledged. 💀

A negative return value means an error.

More info on this command lives in unix(7).

Available since 6.7.

SOCKET_URING_OP_GETSOCKOPT

The command that gets options for the socket that fd refers to. The arguments are basically the same vibe as the getsockopt(2) system call. 🫶

Heads up though: SOCKET_URING_OP_GETSOCKOPT is limited to the SOL_SOCKET level. that's the ceiling, that's the rule.

And here's the plot twist — unlike the getsockopt(2) system call, the updated optlen value comes back in the CQE res field when it works out. When it doesn't work out, the CQE res holds a negative error number. 😭

SOCKET_URING_OP_SETSOCKOPT

The command that sets options for the socket that fd refers to. Arguments are giving setsockopt(2) system call, same energy as that one. ✨

Available since 6.7.

SOCKET_URING_OP_TX_TIMESTAMP

Grabs transmit timestamps from the socket's error queue. This is the alternative route to getting TX timestamps instead of doing the whole traditional recvmsg(2) error queue interface thing. iconic honestly.

The command runs in a polled multishot mode: io_uring will poll the socket and just keep posting timestamps as CQEs until the request gets cancelled or fails. 🔁

okay so the ring HAS to be created with IORING_SETUP_CQE32 or IORING_SETUP_CQE_MIXED, because that's what gives you space for the timestamp data. no room, no timestamps.

First, the socket has to be configured for timestamping via setsockopt(2) with SO_TIMESTAMPING at the SOL_SOCKET level, and you gotta specify the timestamp types you want — like SOF_TIMESTAMPING_TX_SOFTWARE, SOF_TIMESTAMPING_TX_SCHED, SOF_TIMESTAMPING_TX_ACK — along with SOF_TIMESTAMPING_SOFTWARE and SOF_TIMESTAMPING_OPT_TSONLY. yeah that's a whole list, write it down bestie.

For this command these arguments are not used: level, optname, optval and optlen.

Each timestamp arrives as a CQE with IORING_CQE_F_MORE set in cqe->flags, which is the little tell that more timestamps might be coming. The cqe->res field holds the timestamp key (tskey), and that corresponds to the byte offset (for TCP) or the packet count (for UDP). The timestamp type — SCM_TSTAMP_SCHED, SCM_TSTAMP_SND or SCM_TSTAMP_ACK — is stashed in the upper bits of cqe->flags at offset IORING_TIMESTAMP_TYPE_SHIFT. And if the timestamp is a hardware timestamp, the IORING_CQE_F_TSTAMP_HW flag is set. 🤖✨

The actual timestamp value itself lives in the extended CQE area as a struct io_timespec (with 64-bit tv_sec and tv_nsec fields), and you can access it at (cqe + 1). 👑

The final CQE will not have IORING_CQE_F_MORE set, and its cqe->res will hold 0 on success or a negative error code if it failed. that's your signal that the ride is over 🎢

Available since 6.17.

SOCKET_URING_OP_GETSOCKNAME

Returns the current address the socket is bound to. The result gets stored in the buffer that optval points to, which should be a pointer to a struct sockaddr (or whatever the appropriate variant is). The optlen argument says how big that buffer is. On success, the CQE res field contains the actual size of the socket address. If the buffer's too small? the result gets truncated. rip but okay. ✂️

This is the io_uring equivalent of getsockname(2). twins fr.

Available since 6.19.

📌 NOTES 📌

The memory block that optval points to needs to stay valid/live until the CQE comes back. Like, do not free that thing early, I'm begging you. 💀

🎀 RETURN VALUE 🎀

Dependent on the command. it varies bestie, that's just how it is 💁‍♀️

⚠️ ERRORS ⚠️

The CQE res field will contain the result of the operation. that's where you look, always.

👯 SEE ALSO 👯

and that's the whole page, bestie!! 💜 this one's from liburing-2.5, dated July 27, 2023 — so yeah, she's been out here being helpful this whole time. go prep some socket commands, you've got this 🫶✨🌸

📦 where this page comes from