nbd_set_uri_allow_local_file(3)

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

💅 nbd_set_uri_allow_local_file(3) — libnbd bestie edition

okay so real talk — this is nbd_set_uri_allow_local_file(3), a page from the LIBNBD manual, section 3. it's a tiny function with one job and it does it slayfully. let's get into it 🎀

✨ NAME ✨

nbd_set_uri_allow_local_file — set the allowed transports in NBD URIs

like, the name says "local file" but the description says "allowed transports" — yes bestie, that's the original wording, i'm not making the rules i'm just delivering them 💅

✨ SYNOPSIS ✨

#include <libnbd.h>

int nbd_set_uri_allow_local_file (
      struct nbd_handle *h, bool allow
    );

you pass it a handle h and a bool allow, and it hands you back an int. that's the whole vibe. 🦋

✨ DESCRIPTION ✨

so what does it do? it lets NBD URIs reference local files. iconic of them honestly.

but listen — this is disabled by default. so if you want it, you gotta ask for it, no cap. 🙈

and rn, in the current state of things, this setting has exactly one job: it controls whether the tls-psk-file parameter in NBD URIs is allowed. that's it. that's the whole scope. not me being dramatic, that's literally what the page says. ⭐

✨ RETURN VALUE ✨

if the call succeeds? you get 0. clean. perfect. a little success kiss 😘

✨ ERRORS ✨

if it goes wrong, you get -1 back. 💀

and if you wanna know why, the page is like "girl go read "ERROR HANDLING" in libnbd(3)" — that's where the deets on digging into the error live. highly recommend, it's giving detective energy 🔥

⚠️ also important: the following parameter must not be NULL: "h". for more on that, see "Non-NULL parameters" in libnbd(3). so like... don't hand it a null handle, bestie, that's not the move 🫶

✨ HANDLE STATE ✨

here's the vibe check on when you're allowed to call this — nbd_set_uri_allow_local_file works only if the handle is in these states:

  • 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: set it up before you connect, or don't bother. it's a before-the-party function, not a mid-party function. 🌸

✨ VERSION ✨

this function first showed up in libnbd 1.2. vintage ✨

and if you need to check at compile time whether it exists? see if this macro is defined:

#define LIBNBD_HAVE_NBD_SET_URI_ALLOW_LOCAL_FILE 1

if that's there, you're good. 🧚

✨ SEE ALSO ✨

go give these a read, they're the supporting cast and they ate:

✨ AUTHORS ✨

  • Eric Blake
  • Richard W.M. Jones

legends, honestly. 💜

Copyright Red Hat

✨ LICENSE ✨

okay legal moment, stay with me — this one matters so i'm keeping it exact:

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

like, read it, it's the actual rules, no skipping 🎀

and that's the whole page!! this lil rewrite is chilling at version libnbd-1.25.8, dated 2026-10-13, and it's page 3 of the manual for nbd_set_uri_allow_local_file. bye bestie, go set your URI flags responsibly 💖🌈🦋

📦 where this page comes from