nbd_aio_pread_structured(3)

💅 nbd_aio_pread_structured(3) — LIBNBD 💅

okay bestie, welcome to the manual page for nbd_aio_pread_structured(3) from LIBNBD. This is the async structured-read situation, and yes it’s giving main-character syscall energy. ✨

---

🌸 NAME 🌸

nbd_aio_pread_structured — read from the NBD server

---

🎀 SYNOPSIS 🎀

the C moment is literally this:

#include <libnbd.h>

typedef struct {
  int (*callback) (void *user_data, const void *subbuf,
                   size_t count, uint64_t offset,
                   unsigned status, int *error);
  void *user_data;
  void (*free) (void *user_data);
} nbd_chunk_callback;

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

int64_t nbd_aio_pread_structured (
          struct nbd_handle *h, void *buf, size_t count,
          uint64_t offset,
          nbd_chunk_callback chunk_callback,
          nbd_completion_callback completion_callback,
          uint32_t flags
        );

---

🦋 DESCRIPTION 🦋

okay so this one issues a read command to the NBD server. asynchronous queen behavior — you are not sitting there waiting for it like a sync gremlin. 💅

to check if the command completed, call nbd_aio_command_completed(3). or supply the optional completion_callback, which will be invoked as described in "Completion callbacks" in libnbd(3).

now the serious part, no cap: you must ensure buf is valid until the command has completed. 🫶

furthermore, if the error parameter to completion_callback is set or if nbd_aio_command_completed(3) reports failure, and if nbd_get_pread_initialize(3) returns true, then libnbd sanitized buf, but it is unspecified whether the contents of buf will read as zero or as partial results from the server. if nbd_get_pread_initialize(3) returns false, then libnbd did not sanitize buf, and the contents are undefined on failure. 😭

other parameters behave as documented in nbd_pread_structured(3).

---

💖 RETURN VALUE 💖

this call returns the 64 bit cookie of the command. the cookie is ≥ 1. cookies are unique (per libnbd handle, not globally). 🍓

---

🚨 ERRORS 🚨

on error -1 is returned.

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

the following parameters must not be NULL: h, buf. for more information 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, such as 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 🧚

vibe check: this one is allowed when the handle is in the following state. (spoiler: connected only, bestie.)

┌─────────────────────────────────────┬─────────────────────────┐
│ Handle created, before connecting   │ ❌ error                │
│ Connecting                          │ ❌ error                │
│ Connecting & handshaking (opt_mode) │ ❌ error                │
│ Connected to the server             │ ✅ allowed              │
│ Connection shut down                │ ❌ error                │
│ Handle dead                         │ ❌ error                │
└─────────────────────────────────────┴─────────────────────────┘

---

⭐ VERSION ⭐

this function first appeared in libnbd 1.0.

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_PREAD_STRUCTURED 1

---

🔥 SEE ALSO 🔥

• nbd_aio_command_completed(3)
• nbd_aio_pread(3)
• nbd_create(3)
• nbd_get_pread_initialize(3)
• nbd_pread_structured(3)
• nbd_set_pread_initialize(3)
• nbd_set_strict_mode(3)
• "Issuing asynchronous commands" in libnbd(3)
• libnbd(3)

---

👑 AUTHORS 👑

• Eric Blake
• Richard W.M. Jones

---

🧾 COPYRIGHT 🧾

Copyright Red Hat

---

📜 LICENSE 📜

legal queen behavior — here’s the license text, exactly as it needs to appear:

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 bestie, that’s the whole nbd_aio_pread_structured(3) page. source/version: libnbd-1.25.8; date: 2026-10-13. mwah 💋