nbd_set_handshake_flags(3)

✨ nbd_set_handshake_flags — control use of handshake flags ✨

okay so this is a page from the libnbd manual, section 3, and it's about nbd_set_handshake_flags(3) — the little function that lets you choose which handshake flags your client brags about during the NBD hello. bestie, it's giving "i control the vibes of the introduction" 💅

---

🌸 SYNOPSIS 🌸

#include <libnbd.h>

int nbd_set_handshake_flags (
      struct nbd_handle *h, uint32_t flags
    );

that's it. one handle, one bitmask, no drama 🎀

---

🦋 DESCRIPTION 🦋

so by default? libnbd is an overachiever 😌 it tries to negotiate all the possible handshake flags that the server also supports. why? because leaving a handshake flag out can literally block you from using other stuff — think TLS encryption or structured replies. so yeah, omitting flags = losing features. not iconic.

but — and this is the fun part — if you're doing integration testing, it's actually super useful to shrink the set of flags your client claims to support. like, you're testing whether a particular server can handle all the various older clients that were compliant to older versions of the NBD spec. it's a whole vibe check for backwards compatibility 👑

the flags argument is a bitmask, and it can include zero or more of these handshake flags:

• "LIBNBD_HANDSHAKE_FLAG_FIXED_NEWSTYLE" = 1 — the server gracefully handles unknown option requests from the client instead of just... disconnecting 😭 rude. without this flag, a client can't safely ask to use extensions like TLS encryption or structured replies, because that request might make an older server drop the connection entirely. so if you want extensions, you want this flag, no cap.
• "LIBNBD_HANDSHAKE_FLAG_NO_ZEROES" = 2 — if the client is forced to use "NBD_OPT_EXPORT_NAME" instead of the preferred "NBD_OPT_GO", this flag lets the server send fewer all-zero padding bytes over the connection. less padding, more efficiency, we love to see it ✨

for convenience, the constant "LIBNBD_HANDSHAKE_FLAG_MASK" exists — it describes all the flags supported by this build of libnbd. and heads up: future NBD extensions may add more flags, which in turn may be enabled by default in newer libnbd. so if you're only trying to turn off one specific bit? be smart about it — first call nbd_get_handshake_flags(3) and modify that value, rather than blindly setting a constant value. otherwise future-you is gonna have a bad time 🙈

---

💖 RETURN VALUE 💖

if the call is successful, the function returns 0. that's the good ending 🫶

---

💀 ERRORS 💀

on error, -1 is returned. yeah. -1. the classic.

refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error — that's where the lore lives.

also! the following parameters must not be NULL: "h". for more info, see "Non-NULL parameters" in libnbd(3). do not pass a null handle, i am begging you 😭

---

👑 HANDLE STATE 👑

nbd_set_handshake_flags can be called when the handle is in the following state:

• Handle created, before connecting — ✅ allowed
• Connecting — ❌ error
• Connecting & handshaking (opt_mode) — ❌ error
• Connected to the server — ❌ error
• Connection shut down — ❌ error
• Handle dead — ❌ error

so basically: call it before you connect, or don't call it at all. the window is one (1) state wide, bestie. timing is everything ⏰

---

⭐ VERSION ⭐

this function first appeared in libnbd 1.2. an elder. a legend.

if you need to test whether this function is available at compile time, check if the following macro is defined:

#define LIBNBD_HAVE_NBD_SET_HANDSHAKE_FLAGS 1

iykyk 🧚

---

🌈 SEE ALSO 🌈

nbd_create(3), nbd_get_handshake_flags(3), nbd_set_request_structured_replies(3), libnbd(3).

go read them. they're all part of the same friend group 🫶

---

🍓 AUTHORS 🍓

Eric Blake

Richard W.M. Jones

icons. both of them. 💅

---

💜 COPYRIGHT 💜

Copyright Red Hat

---

🎀 LICENSE 🎀

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

---

and that's the whole page, bestie 🫶 this lil beauty is from libnbd-1.25.8, dated 2026-10-13, and it lives at nbd_set_handshake_flags(3). go forth and negotiate your flags responsibly ✨💖🎀