nbd_set_keepalive(3)

💅 nbd_set_keepalive(3) — the libnbd glow-up

okay so bestie, welcome to libnbd, and this little icon right here is nbd_set_keepalive from section 3 of the manual. she's the one who sets keepalive on the socket. let's get into it ✨

---

🌸 NAME 🌸

nbd_set_keepalive — literally just: set keepalive on the socket. that's her whole job. periodt 💅

---

🦋 SYNOPSIS 🦋

first, bestie, you gotta bring in the header:

#include <libnbd.h>

and here's the signature — copy it exactly, no cap:

int nbd_set_keepalive (
      struct nbd_handle *h, bool enable
    );

---

🎀 DESCRIPTION 🎀

so what she does: she sets the keepalive ("SO_KEEPALIVE") flag on the socket, and she does it after the socket gets created. timing matters, iykyk 🫶

on operating systems and protocols that actually support this, it means the OS sends periodic messages to the NBD server so it can detect whether the socket is still connected. like a little "u up? 👀" ping. and if the feature isn't supported? then setting this does nothing. zero. nada. she just vibes 💀

if you're using TCP on Linux, bestie, you can tune the keepalive by calling nbd_set_tcp_option(3) — that's where the fine-tuning lives ✨

⚠️ key caveat incoming: this only works if you call it on the handle before calls like nbd_connect_tcp(3) where libnbd itself creates the socket. it does not apply to nbd_connect_socket(3), because there the socket got created somewhere else and then passed in to libnbd. different origin story, different rules 💅

---

💖 RETURN VALUE 💖

if the call goes well, the function returns 0. slay. that's the success number 🎉

---

🔥 ERRORS 🔥

on error, -1 is returned. not slay 😭

refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error — that's your group chat for debugging info.

also, these parameters must not be NULL: "h". for more info, see "Non-NULL parameters" in libnbd(3). so like, actually pass a handle, bestie 🙈

---

👑 HANDLE STATE 👑

nbd_set_keepalive 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: before you connect, or nothing. she's a "get in early" kind of girl 🌈

---

⭐ VERSION ⭐

this function first appeared in libnbd 1.26. iconic debut, honestly 🎀

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_KEEPALIVE 1

---

🧚 SEE ALSO 🧚

the whole friend group, fr fr:

• nbd_connect_socket(3)
• nbd_connect_tcp(3)
• nbd_create(3)
• nbd_get_keepalive(3)
• nbd_set_tcp_option(3)
• libnbd(3)
• setsockopt(2)
• socket(7)

---

💜 AUTHORS 💜

• Eric Blake
• Richard W.M. Jones

legends, honestly 👑

---

🍓 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

---

okay that's the whole page bestie, go forth and keep those sockets alive 🦋💖

and a lil sign-off for the record: this was libnbd-1.25.8, dated 2026-10-13, and yeah — that's nbd_set_keepalive(3), page closed, mwah 💋