nbd_aio_pwrite(3)

✨ nbd_aio_pwrite — libnbd(3) ✨

okay so bestie, buckle up 💅 this one's a manual page for nbd_aio_pwrite, and it's literally the "fire and forget" version of writing to your NBD server. asynchronously. iconically. let's get into it 🫶

---

🌸 NAME 🌸

nbd_aio_pwrite — write to the NBD server 🖊️✨

---

🎀 SYNOPSIS 🎀

#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_pwrite (
          struct nbd_handle *h, const void *buf,
          size_t count, uint64_t offset,
          nbd_completion_callback completion_callback,
          uint32_t flags
        );

like, that's the whole vibe right there 👑

---

🦋 DESCRIPTION 🦋

So what does it do? It issues a write command to the NBD server. that's it, that's the tweet. no cap 💖

Wanna know if the command actually completed? two options, bestie:

• call nbd_aio_command_completed(3), or
• supply the optional "completion_callback" — which gets invoked exactly the way it's described in "Completion callbacks" in libnbd(3).

⚠️ real talk: you MUST make sure buf stays valid until the command has completed. like, don't go freeing that buffer while the server's still chewing on it, that's a whole mess 😭

Every other parameter? behaves exactly as documented in nbd_pwrite(3). mwah 💋

---

👑 RETURN VALUE 👑

This call hands you back the 64 bit cookie 🍪 of the command. The cookie is ≥ 1. Cookies are unique — but like, unique per libnbd handle, not globally. so don't go comparing cookies across handles and expecting drama, they're not related, iykyk ✨

---

💀 ERRORS 💀

On error, -1 is returned. tragic, I know.

Wanna know why it errored? Refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error 🔍

Also, these parameters must not be NULL: "h", "buf". For more info see "Non-NULL parameters" in libnbd(3). like, do not come for those with a NULL, they will not survive it 🙈

---

⭐ 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. icon behaviour honestly, it's protecting you from yourself 💅

The nbd_set_strict_mode(3) function can be used to alter which scenarios should await a server reply rather than failing fast. so if you're feeling brave (or reckless), that's your girl 🧚

---

🌈 HANDLE STATE 🌈

nbd_aio_pwrite can be called when the handle is in the following state — vibe check time, 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

so basically: connected or nothing, periodt. 💜

---

🍓 VERSION 🍓

This function first appeared in libnbd 1.0. OG status, honestly 👑

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

---

🧚 SEE ALSO 🧚

nbd_aio_command_completed(3), nbd_create(3), nbd_is_read_only(3), nbd_pwrite(3), nbd_set_strict_mode(3), "Issuing asynchronous commands" in libnbd(3), libnbd(3).

go read them, they're all bangers, fr fr 📚✨

---

💖 AUTHORS 💖

Eric Blake

Richard W.M. Jones

legends, both of them 🫶

---

🌸 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

---

and that's the page!! brought to you by libnbd-1.25.8, dated 2026-10-13, and yes nbd_aio_pwrite(3) is the main character of this particular document 💅✨ slay, go write some bytes bestie, love u bye 🎀💜