nbd_cache(3)

💅 nbd_cache — bestie, this is the libnbd nbd_cache(3) page

okay so quick vibe check: this is the nbd_cache(3) manpage from libnbd, and it's literally about telling your NBD server "hey, go grab this data ahead of time so it's ready when I need it." iconic behavior. let's get into it 🫶

---

✨ SYNOPSIS ✨

like, here's the whole shape of the thing:

#include <libnbd.h>

int nbd_cache (
      struct nbd_handle *h, uint64_t count,
      uint64_t offset, uint32_t flags
    );

---

🦋 DESCRIPTION 🦋

so you're issuing the cache (prefetch) command to the NBD server. and if the server supports it, this makes the server prefetch data into faster storage for you — which speeds up a subsequent nbd_pread(3) call. main character move fr fr. ✨

the server can also just silently ignore this command, like it's leaving you on read 💀. and ngl, this will generally return an error if nbd_can_cache(3) is false.

heads up: not all servers can support a "count" of 4GiB or larger. nbd_get_extended_headers_negotiated(3) tells you which servers will parse a request larger than 32 bits. also, the NBD protocol does not yet have a way for a client to learn if the server will enforce an even smaller maximum cache size — although a future extension may add a constraint visible in nbd_get_block_size(3). so yeah, lowkey a mystery for now 🙈

and the "flags" parameter must be 0 for now (it exists for future NBD protocol extensions — it's giving "placeholder for the future" energy).

---

🌸 RETURN VALUE 🌸

if the call is successful, the function returns 0. slay.

---

🎀 ERRORS 🎀

on error, -1 is returned. 😭

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

and bestie, listen: the following parameters must not be NULL: "h". for more info see "Non-NULL parameters" in libnbd(3).

---

💜 NOTES 💜

Strict call

by default, libnbd will reject attempts to use this function with parameters that are likely to result in server failure — like requesting an unknown command flag. 💀 the nbd_set_strict_mode(3) function can be used to alter which scenarios should await a server reply rather than failing fast.

---

👑 HANDLE STATE 👑

nbd_cache can be called when the handle is in the following state:

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

so basically: connected to the server, or nothing. periodt. 💅

---

⭐ VERSION ⭐

this function first appeared in libnbd 1.0. og behavior.

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

#define LIBNBD_HAVE_NBD_CACHE 1

---

🌈 SEE ALSO 🌈

nbd_aio_cache(3), nbd_can_cache(3), nbd_create(3), nbd_get_block_size(3), nbd_get_extended_headers_negotiated(3), nbd_pread(3), nbd_set_strict_mode(3), libnbd(3).

---

🧚 AUTHORS 🧚

Eric Blake

Richard W.M. Jones

---

🍓 COPYRIGHT 🍓

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, you're literally an nbd_cache expert now 💖 this was libnbd-1.25.8, dated 2026-10-13 — mwah, go prefetch something 🦋✨