nbd_connect_tcp(3)

📦
version 1.25.8 · 18 versions
, in centos-stream 10

💅 nbd_connect_tcp — like, the libnbd manual page, bestie

okay so this is nbd_connect_tcp(3) from the libnbd manual, and it's genuinely one of the easiest ways to slide into an NBD server's DMs. sit down, grab a strawberry drink 🍓, and let's go.

✨ NAME ✨

nbd_connect_tcp — connect to an NBD server over a TCP port. that's it. that's the whole vibe. 🎀

🌸 SYNOPSIS 🌸

#include <libnbd.h>

int nbd_connect_tcp (
      struct nbd_handle *h, const char *hostname,
      const char *port
    );

three params, one handle, zero drama. iconic signature fr fr.

🦋 DESCRIPTION 🦋

So you wanna connect (synchronously, babe — like, this call waits) to the NBD server that's listening on hostname:port. 💖

the port can be a port name like "nbd" (cute, named, whimsical) or it can be a port number as a string like "10809" (a string, note that — not an int, it's giving string energy). both slay, pick your fave.

⭐ RETURN VALUE ⭐

if the call is successful? it returns 0. that's the good ending. 🫶

😭 ERRORS 😭

on error, -1 is returned. yeah. not the vibe.

for the full rundown on how to get further deets on the error, go read "ERROR HANDLING" in libnbd(3) — it's all there, iykyk.

also 🚨 the following parameters must not be NULL: h, hostname, port. for more info see "Non-NULL parameters" in libnbd(3). do not test this. it will not go well.

👑 NOTES 👑

🔥 Blocking connect call

this call returns when the connection has been made — it blocks, hence the name, no surprises bestie. 💀

by default it proceeds all the way to transmission phase, but heads up: you can use nbd_set_opt_mode(3) if you want manual control over the option negotiation that happens before transmission phase. main character energy: you, driving the negotiation yourself. 🌈

🧚 HANDLE STATE 🧚

nbd_connect_tcp can be called when the handle is in the following state — vibe check time:

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

so basically: fresh handle only. one shot. periodt. 💅

💜 VERSION 💜

this function first appeared in libnbd 1.0. a legend from the start, honestly.

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

#define LIBNBD_HAVE_NBD_CONNECT_TCP 1

🌟 SEE ALSO 🌟

(the async version for when you're multitasking, the handle-maker, the opt-mode-enabler, and the big main manpage itself 🫶)

🎀 AUTHORS 🎀

  • Eric Blake
  • Richard W.M. Jones

absolute icons, no cap.

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!! this lil beauty is from libnbd-1.25.8, dated 2026-10-13 — so yes she's current, she's fresh, she ate. mwah 💋✨ go connect to something bestie 🦋

📦 where this page comes from