handshake_req_submit(9)

✨ handshake_req_submit(9) ✨

okay so this is a page from the Kernel API Manual — section 9, bestie, we're in kernel-internals territory 💅 — and honestly? it's giving "one function, a LOT of emotional weight." Stay with me.

---

🎀 NAME 🎀

handshake_req_submit — literally just submit a handshake request. that's the whole vibe. 🫶

---

🌸 SYNOPSIS 🌸

int handshake_req_submit (struct socket *sock , struct handshake_req
*req , gfp_t flags );

---

🦋 ARGUMENTS 🦋

• sock — the open socket where the handshake is gonna happen. it has to be open, okay? this is not a "make it work anyway" situation ✨
• req — the handshake arguments 💌 like, the whole point of the call
• flags — memory allocation flags. yes the gfp_t ones. no i will not elaborate, they're flags, they flag 🚩

---

💖 DESCRIPTION 💖

okay so here's the return-value tea, and ngl there is a LOT of it, so buckle up 🍓

Return values:

• 0 — Request queued 🎉
• -EINVAL — Invalid argument 🙈
• -EBUSY — A handshake is already under way for this socket 💀 (it's occupied, respectfully back off)
• -ESRCH — No handshake agent is available 😭 (nobody's home)
• -EAGAIN — Too many pending handshake requests 🫠 (the queue said "no more")
• -ENOMEM — Failed to allocate memory 😵‍💫
• -EMSGSIZE — Failed to construct notification message 📭
• -EOPNOTSUPP — Handshake module not initialized ⚠️ (the module didn't even show up)

the way that a zero return value from handshake_req_submit means that exactly one subsequent completion callback is guaranteed — exactly one, bestie, not zero, not two, ONE 👑 that's the contract, periodt.

and here's the flip side, because the negative path is lowkey the spicy part 🌶️:

A negative return value from handshake_req_submit guarantees that no completion callback will occur and that req is no longer owned by the caller. If cancellation wins the completion race after the request has been published, final destruction is deferred until socket teardown. 💀 so like. don't touch req after a fail, it's not yours anymore, it's the kernel's problem now.

now the reference-counting bit, which is highkey the most important part and also the easiest to fumble 🧚:

The caller must hold a reference on sock->file for the duration of this call. Once the request is published to the accept side, a concurrent completion or cancellation may release the request's pin on sock->file; the caller's reference is what keeps sock->sk valid until handshake_req_submit returns.

read that again fr fr. your reference is the whole safety net. main character energy for your own sock->file pin 🫶

---

🌈 SEE ALSO 🌈

• Kernel file ./net/handshake/request.c
• handshake_req_alloc(9)
• handshake_req_private(9)
• handshake_req_next(9)
• handshake_req_cancel(9)

---

that's the whole page, bestie, you ate it 💅 mwah 💖

signed, sealed, and shipped from ./net/handshake — dated October 2026, syntax handshake_req_submit(9), and yes it's still the Kernel API Manual ✨