nbd_connect_vsock(3)

💖 nbd_connect_vsock(3) — the libnbd girlies' guide 💖

okay so this is a page from the LIBNBD manual, and we're talking about nbd_connect_vsock, bestie. it's giving "connect me to the host machine" energy 🫶

---

✨ NAME ✨

nbd_connect_vsock — connect to an NBD server over the AF_VSOCK protocol 💅

---

🎀 SYNOPSIS 🎀

#include <libnbd.h>

int nbd_connect_vsock (
      struct nbd_handle *h, uint32_t cid, uint32_t port
    );

---

🦋 DESCRIPTION 🦋

so this one connects synchronously over the AF_VSOCK protocol, going from a virtual machine to an NBD server — which is usually running on the host. like, the way that vsock is literally made for this 🧚

the cid and port parameters are the server address, no cap. usually cid should be 2 (that's the "connect to the host" one, iconic), and port might be 10809 or another port number that your host administrator assigned to you.

heads up bestie 💀 — not all systems support AF_VSOCK. to figure out if libnbd was built on a system with vsock support, go look at nbd_supports_vsock(3).

---

⭐ RETURN VALUE ⭐

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

---

🌸 ERRORS 🌸

on error, -1 is returned. 🙈

refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error.

these parameters must not be NULL: h. for more info see "Non-NULL parameters" in libnbd(3). (like, don't pass a null handle, that's not the vibe 😭)

---

🔥 NOTES 🔥

Blocking connect call

this call returns when the connection has been made — it blocks, periodt.

by default it proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can be used if you want manual control over the option negotiation that happens before transmission phase. iykyk 👑

---

👑 HANDLE STATE 👑

nbd_connect_vsock 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: only when the handle is fresh and hasn't started connecting yet. main character timing only 🕐✨

---

💜 VERSION 💜

this function first appeared in libnbd 1.2.

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

---

🌈 SEE ALSO 🌈

nbd_aio_connect_vsock(3), nbd_create(3), nbd_set_opt_mode(3), nbd_supports_vsock(3), libnbd(3), vsock(7).

(the whole friend group, fr fr 🫶)

---

🍓 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

---

okay that's the whole page, bestie — mwah 💋 this was libnbd-1.25.8, dated 2026-10-13, and it's the nbd_connect_vsock(3) page. go connect to something iconic 🦋✨