nbd_aio_connect_uri(3)

💅 NAME 💅

nbd_aio_connect_uri — okay so this is the one that connects you to an NBD URI, and yes bestie it's the async version, we love a non-blocking icon 💖

(this whole page lives in section 3 of the manual for libnbd, iykyk)

✨ SYNOPSIS ✨

#include <libnbd.h>

int nbd_aio_connect_uri (
      struct nbd_handle *h, const char *uri
    );

🦋 DESCRIPTION 🦋

Okay so real talk: this kicks off a connection to the NBD URI uri. The parameters do exactly what they do in nbd_connect_uri(3) — same energy, same behavior, no cap. It's just the asynchronous glow-up of that call ✨

🎀 RETURN VALUE 🎀

If the call slays (i.e. succeeds), it returns 0. That's it. That's the whole vibe.

🙈 ERRORS 🙈

On error? -1 comes back and it's giving 💀.

To find out more about what went wrong, go read "ERROR HANDLING" in libnbd(3) — that's where the deets live.

Also important: these parameters are not allowed to be NULL: h, uri. For the full tea, check "Non-NULL parameters" in libnbd(3).

🌸 NOTES 🌸

💫 Asynchronous connect call 💫

So here's how you check on your connection attempt while it's still doing its thing — call nbd_aio_is_connecting(3), periodt.

And if nbd_set_opt_mode(3) is enabled, then the connection is ready for manual option negotiation as soon as nbd_aio_is_negotiating(3) returns true. If it's not enabled, then the connection attempt includes the whole NBD handshake, and it's ready to use once nbd_aio_is_ready(3) returns true. Two different vibes, both valid 🫶

👑 HANDLE STATE 👑

nbd_aio_connect_uri can be called when the handle is in these states, and here's the rundown:

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

So basically: only before you've connected. Catch it early or don't catch it at all 🧚

⭐ VERSION ⭐

This function first appeared in libnbd 1.0 — an OG, honestly.

If you ever need to test at compile time whether this function is available, just check if this macro is defined:

#define LIBNBD_HAVE_NBD_AIO_CONNECT_URI 1

🔥 SEE ALSO 🔥

• nbd_aio_is_connecting(3)
• nbd_aio_is_negotiating(3)
• nbd_aio_is_ready(3)
• nbd_connect_uri(3)
• nbd_create(3)
• nbd_set_opt_mode(3)
• libnbd(3)
• https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md — go read it, it's literally the URI spec 🌈

💜 AUTHORS 💜

Eric Blake

Richard W.M. Jones

(absolute legends, both of them 👑)

🌸 COPYRIGHT 🌸

Copyright Red Hat

🍓 LICENSE 🍓

Bestie this part is all business but it matters, so here it is fully: 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 connect to something 💅✨

This was libnbd-1.25.8, dated 2026-10-13, and the page itself is nbd_aio_connect_uri(3) — mwah, bye 🫶🎀