nbd_connect_socket(3)

💖 nbd_connect_socket 💖

okay so welcome to the libnbd manual, bestie — this one's all about nbd_connect_socket, and honestly? it's giving "you already did the hard part, hand it over" ✨

🌸 NAME 🌸

nbd_connect_socket — connect directly to a connected socket 🫶

🎀 SYNOPSIS 🎀

#include <libnbd.h>

int nbd_connect_socket (
      struct nbd_handle *h, int sock
    );

✨ DESCRIPTION ✨

So basically you pass in a connected socket sock, right? and from that moment on libnbd is the one talking to the NBD server through it. it's giving "you built the bridge, i'll drive the car" 💅

the way that you, the caller, are responsible for creating and connecting that socket by whatever method you like — before you hand it over. libnbd is not doing that part for you, no cap.

and here's the important bit, so listen up 🔥: if this call returns without error, then socket ownership is passed to libnbd. libnbd will close the socket when the handle is closed. and the caller must not use the socket in any way after that. like, not even a little peek. it's libnbd's socket now, periodt. 💀

🌈 RETURN VALUE 🌈

if the call is successful, the function returns 0. slay. 👑

💀 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 where the lore lives, iykyk.

also: the following parameters must not be NULL: "h". for more info see "Non-NULL parameters" in libnbd(3). 🫶

🦋 NOTES 🦋

🧚 Blocking connect call 🧚

this call returns when the connection has been made. like, it actually waits. bestie is committed. 💖

by default, this proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can be used for manual control over option negotiation performed before transmission phase — so if you're the kind of main character who wants to drive stick, that's your moment. 🔥

👑 HANDLE STATE 👑

nbd_connect_socket 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 yeah, the vibe check is: handle freshly created and nothing else going on. every other state? nope. 🙈

⭐ VERSION ⭐

this function first appeared in libnbd 1.2. vintage, but make it iconic. 💜

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

#define LIBNBD_HAVE_NBD_CONNECT_SOCKET 1

🍓 SEE ALSO 🍓

nbd_aio_connect_socket(3), nbd_connect_command(3), nbd_create(3), nbd_set_opt_mode(3), libnbd(3), socket(7).

go read them, bestie, they're all part of the same little universe 🌸

💜 AUTHORS 💜

Eric Blake

Richard W.M. Jones

🎀 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 thing, bestie 🫶 this page came straight out of libnbd-1.25.8, dated 2026-10-13, and yes it's the nbd_connect_socket(3) page — now go connect that socket, you absolute icon 💅✨