nbd_get_uri(3)

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

💅 nbd_get_uri — construct an NBD URI for a connection

okay so this is a page from the LIBNBD manual, and honestly? it's a little baddie. it's nbd_get_uri(3) and it's about building you a URI so you can slide back into the same server. let's get into it 🎀

✨ SYNOPSIS ✨

#include <libnbd.h>

char * nbd_get_uri (
         struct nbd_handle *h
       );

that's it. one handle in, one string out. she's simple, she's elegant, she's iconic 💅

🌸 DESCRIPTION 🌸

okay bestie, so what this does is it makes a best effort attempt to construct an NBD URI that you could use to connect back to the same server — and you'd do that with nbd_connect_uri(3). cute, right? 🦋

but here's the tea: sometimes there's just not enough info sitting in the handle to actually pull a URI out of thin air. like, example: if you connected using nbd_connect_socket(3), there's lowkey nothing to work with. in cases like that the call returns NULL — and no cap, you're not left hanging, because the further diagnostic info is available via nbd_get_errno(3) and nbd_get_error(3), as usual. 🫶

also, even if a URI does come back? it's not guaranteed to work, and it may not be optimal. so like... don't @ her if it's mid. 😭

oh and if you're a shell-script girlie, the nbdinfo(1) --uri option is a whole way to access this API from your shell scripts. slay for automation ✨

👑 RETURN VALUE 👑

this call returns a string. but listen — the caller must free the returned string to avoid a memory leak. i'm so serious. free your girl. 🧚

💀 ERRORS 💀

on error, NULL is returned. that's the whole vibe.

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

also: the following parameters must not be NULL: h. for more info, check "Non-NULL parameters" in libnbd(3). don't pass her a NULL handle, it's giving chaos 🙈

🦋 HANDLE STATE 🦋

so there's a whole vibe check on which states you can call nbd_get_uri from. here's the rundown:

  • Handle created, before connecting — ❌ error (sorry babe, too early)
  • Connecting — ✅ allowed
  • Connecting & handshaking (opt_mode) — ✅ allowed
  • Connected to the server — ✅ allowed
  • Connection shut down — ✅ allowed
  • Handle dead — ✅ allowed (yes even then, she's unbothered 💅)

⭐ VERSION ⭐

this function first appeared in libnbd 1.8. periodt.

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

#define LIBNBD_HAVE_NBD_GET_URI 1

🌈 SEE ALSO 🌈

your reading list, bestie, go off:

💖 AUTHORS 💖

  • Eric Blake
  • Richard W.M. Jones

absolute legends, both of them 🫶

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, mwah 💋 this was libnbd-1.25.8, dated 2026-10-13, nbd_get_uri(3) — go build your URIs responsibly, bestie, and remember to free your strings 🔥🌸

📦 where this page comes from