nbd_aio_connect_tcp(3)

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

💅 nbd_aio_connect_tcp(3) — the libnbd girlie's guide

okay so this is a page from the libnbd manual, and today's main character is nbd_aio_connect_tcp(3). yes bestie, we're going networking. 🦋

✨ NAME ✨

nbd_aio_connect_tcp — connect to the NBD server over a TCP port

Like, asynchronously. Non-blocking. She doesn't wait around. 💅

✨ SYNOPSIS ✨

#include <libnbd.h>

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

That's the whole vibe check right there. Three params, one int back. Slay. 🎀

✨ DESCRIPTION ✨

So what she does is: she begins connecting to the NBD server that's listening on hostname:port. 🔥

And the way the parameters behave? Literally identical to how they're documented in nbd_connect_tcp(3). Same energy, different function (this one's the async version, iykyk). ✨

✨ RETURN VALUE ✨

If the call goes well, she returns 0. That's it. That's the win. 🫶

✨ ERRORS ✨

If something goes wrong, she returns -1. 😭 Not the vibe, but okay.

Wanna know more about what went wrong? Peep "ERROR HANDLING" in libnbd(3) for how to get further details of the error. Detective mode: activated. 🔍

⚠️ Also important: the following parameters must not be NULL — "h", "hostname", "port". For more info, see "Non-NULL parameters" in libnbd(3). Don't be the girl who passes NULL. It's not cute. 🙈

✨ NOTES ✨

🌸 Asynchronous connect call 🌸

So like, you might be wondering "is my connection still doing its thing?" and the answer is: check with nbd_aio_is_connecting(3). That's your girl. 💖

And here's the tea ☕ — if nbd_set_opt_mode(3) is enabled, then the connection is ready for manual option negotiation once nbd_aio_is_negotiating(3) returns true.

But if opt_mode is not on? Then the connection attempt just includes the NBD handshake all on its own, and she's ready for use once nbd_aio_is_ready(3) returns true. No cap. 🔥

✨ HANDLE STATE ✨

nbd_aio_connect_tcp can be called when the handle is in the following state — literally a vip list and you gotta be on it:

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

So basically: get in before the connection starts, or don't come at all. periodt.

✨ VERSION ✨

This function first appeared in libnbd 1.0. vintage. iconic. 👑

Wanna test at compile time if this function is even available to you? Check if the following macro is defined:

#define LIBNBD_HAVE_NBD_AIO_CONNECT_TCP 1

Easy. 🌈

✨ SEE ALSO ✨

the whole friend group fr fr:

✨ AUTHORS ✨

  • Eric Blake
  • Richard W.M. Jones

the founding fathers of this whole situation 🫶

Copyright Red Hat

✨ LICENSE ✨

okay so legal moment, but it's actually important so read it:

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

🫶 translation: it's free, it's open, but there's no warranty and you gotta pass the license along. no gatekeeping, but also no free-for-all. 💖

🌸 and that's the whole page bestie! sourced straight from libnbd-1.25.8, dated 2026-10-13, and it's literally nbd_aio_connect_tcp(3) in the flesh. go forth and connect asynchronously — mwah! 💅✨🎀

📦 where this page comes from