nbd_aio_trim(3)

💅 nbd_aio_trim — girl help, we're sending a trim command to the NBD server

okay so real talk: this page is nbd_aio_trim(3) from the LIBNBD manual, and it's literally the async version of trim. bestie, let's get into it 🎀

---

✨ NAME ✨

nbd_aio_trim — send trim command 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_trim (
          struct nbd_handle *h, uint64_t count,
          uint64_t offset,
          nbd_completion_callback completion_callback,
          uint32_t flags
        );

like, that's the whole vibe right there ✨

---

🦋 DESCRIPTION 🦋

So what this does is issue a trim command to the NBD server. That's it, that's the girl 🫶

Wanna know if the command actually completed? You've got two options, bestie:

• call nbd_aio_command_completed(3) and check for yourself, or
• supply the optional "completion_callback" — it gets invoked exactly as described in "Completion callbacks" in libnbd(3). iconique 💅

The other parameters behave as documented in nbd_trim(3). no cap, go read that one too.

---

⭐ RETURN VALUE ⭐

This call returns the 64 bit cookie 🍪 of the command. The cookie is ≥ 1. Cookies are unique — but heads up, that's unique per libnbd handle, not globally. iykyk 😌

---

💀 ERRORS 💀

On error, -1 is returned. not the vibe, but okay.

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

Also: the following parameters must not be NULL — "h". Fr fr. For more info see "Non-NULL parameters" in libnbd(3).

🚨 not me passing a NULL handle… bestie don't do it, it's literally on the must-not-be-NULL list.

---

🧚 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. main character energy for real.

---

👑 HANDLE STATE 👑

nbd_aio_trim can be called when the handle is in the following state — vibe check time:

• 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 it's a no from her 💅

---

🍓 VERSION 🍓

This function first appeared in libnbd 1.0. a classic, an original, we stan ⭐

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

---

🔥 SEE ALSO 🔥

nbd_aio_command_completed(3), nbd_can_trim(3), nbd_create(3), nbd_set_strict_mode(3), nbd_trim(3), "Issuing asynchronous commands" in libnbd(3), libnbd(3). go read the whole little family, they ate 💖

---

🫶 AUTHORS 🫶

Eric Blake

Richard W.M. Jones

(absolute icons, 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

---

🌷 okay that's the whole page, drink some water, and remember: this one's from libnbd-1.25.8, dated 2026-10-13. catch you on the next manpage, bestie — mwah 💋✨