nbd_aio_cache(3)

💅 nbd_aio_cache — the LIBNBD girlie's guide to sending a cache (prefetch) command to the NBD server ✨

okay so bestie, you're looking at nbd_aio_cache(3) from the LIBNBD manual, and honestly? it's a whole vibe. let's get into it 🎀

---

✨ NAME ✨

nbd_aio_cache — send cache (prefetch) command to the NBD server. that's it, that's the function, and she's iconic for it 💖

---

🌸 SYNOPSIS 🌸

like, here's the actual code, copy it exactly or it won't slay:

#include <libnbd.h>

typedef struct {
  int (*callback) (void *user_data, int *error);
  void *user_data;
  void (*free) (void *user_data);
} nbd_completion_callback;

int64_t nbd_aio_cache (
          struct nbd_handle *h, uint64_t count,
          uint64_t offset,
          nbd_completion_callback completion_callback,
          uint32_t flags
        );

no cap, that's the whole shape of her 🦋

---

💫 DESCRIPTION 💫

so what she does: she issues the cache (prefetch) command to the NBD server. periodt. 🔥

now, to check if the command actually completed, you call nbd_aio_command_completed(3). OR — and this is the fun part — you can supply the optional completion_callback, which gets invoked as described in "Completion callbacks" in libnbd(3). cute, right? 🫶

and the other parameters? they behave exactly as documented in nbd_cache(3). go read that one too, bestie, i'm not gonna retype it for you 💅

---

👑 RETURN VALUE 👑

this call returns the 64 bit cookie of the command. the cookie is ≥ 1. and yes, cookies are unique — but only per libnbd handle, not globally. so don't go thinking your cookie is special on a universal level, she's just special to her handle 😭🍓

---

💀 ERRORS 💀

on error, -1 is returned. rough, i know.

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

also: the following parameters must not be NULL: h. for more info see "Non-NULL parameters" in libnbd(3). so like... don't pass a NULL handle, that's not the move 🙈

---

⭐ NOTES ⭐

🧚 Strict call 🧚

by default, libnbd will reject attempts to use this function with parameters that are likely to result in server failure — such as requesting an unknown command flag. like, she's protecting you from yourself, okay?

and if you want to change that energy? the nbd_set_strict_mode(3) function can be used to alter which scenarios should await a server reply rather than failing fast. iykyk 💜

---

🌈 HANDLE STATE 🌈

nbd_aio_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: she only vibes with a handle that's actually connected to the server. everything else? error. the vibe check has been conducted and you did not pass 😭✋

---

🎀 VERSION 🎀

this function first appeared in libnbd 1.0. she's an OG, been here since the beginning, main character energy fr fr 👑

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

#define LIBNBD_HAVE_NBD_AIO_CACHE 1

---

🦋 SEE ALSO 🦋

go be nosy, bestie, these are all linked:

• nbd_aio_command_completed(3)
• nbd_cache(3)
• nbd_can_cache(3)
• nbd_create(3)
• nbd_set_strict_mode(3)
• "Issuing asynchronous commands" in libnbd(3)
• libnbd(3)

the whole friend group, honestly 🫶💖

---

💜 AUTHORS 💜

• Eric Blake
• Richard W.M. Jones

shoutout to the icons who made this happen 🌟

---

🌸 COPYRIGHT 🌸

Copyright Red Hat

---

✨ LICENSE ✨

okay, legal moment, but make it cute — and keep every word, because this part actually matters:

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.

fr fr read the license, bestie, it's giving "responsible queen" 💅

---

and that's the page!! brought to you by libnbd-1.25.8, dated 2026-10-13 — mwah, love u, go prefetch something 🍓💖✨