nbd_can_fast_zero(3)

📦
version 1.25.8 · 18 versions
, in centos-stream 10

💅 nbd_can_fast_zero — ok bestie, does the server support the fast zero flag?

So this is nbd_can_fast_zero(3) from the LIBNBD manual, and it's literally the cutest little boolean you'll ever ask a server about 🎀

✨ SYNOPSIS ✨

#include <libnbd.h>

int nbd_can_fast_zero (
      struct nbd_handle *h
    );

ok so you pull in <libnbd.h>, you hand it your handle h, and it tells you a yes/no. that's the whole vibe 🦋

🌸 DESCRIPTION 🌸

ngl this one is simple and I love her for it. nbd_can_fast_zero returns true if the server supports using the LIBNBD_CMD_FLAG_FAST_ZERO flag with the zero command (go look at nbd_zero(3) and nbd_aio_zero(3), they're right there 🫶). Returns false if the server does not. that's it. that's the function.

Now here's the part everyone gets wrong and I need you to listen 👑 — using the fast zero flag does not speed up a successful write zeroes request. I know, I know. not the glow-up you wanted. it's not for the success case at all.

It exists to speed up the failure case: a server that lacks fast zeroing but supports this flag will fail fast without modifying the disk. which is genuinely iconic behavior, because it lets you decide whether retrying with known-slow zeroing is still worth the effort. like, no wasted writes, no drama, just a quick "nope, not doing that" so you can make an informed choice 💅✨

🔥 RETURN VALUE 🔥

This call returns a boolean value. true or false. that's her whole personality 😌

😭 ERRORS 😭

On error -1 is returned. tragic, but fine.

Refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error — that's where the actual tea is spilled.

The following parameters must not be NULL: h. For more information see "Non-NULL parameters" in libnbd(3). fr fr do not pass a NULL handle, she will not be okay about it 💀

🧚 NOTES 🧚

Non-blocking call

This call does not block, because it returns data that's saved in the handle from the NBD protocol handshake. the data was already collected during handshake, so she's just reading it back to you. zero waiting, zero stress ⭐

🌈 HANDLE STATE 🌈

nbd_can_fast_zero can be called when the handle is in the following states — vibe check time:

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

so like, once you're handshaking or past it, you're golden 🏆

⭐ VERSION ⭐

This function first appeared in libnbd 1.2. a classic, 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_CAN_FAST_ZERO 1

🍓 EXAMPLE 🍓

This example is also available as examples/server-flags.c in the libnbd source code. (fun fact, this whole example file is a little icon — it prints all the flags 🌸)

/* This example shows how to connect to an NBD
 * server and print the export flags.
 *
 * You can test it with nbdkit like this:
 *
 * nbdkit -U - memory 1M \
 *   --run './server-flags $unixsocket'
 */

#include <stdio.h>
#include <stdlib.h>
#include <stdbool.h>

#include <libnbd.h>

int
main (int argc, char *argv[])
{
  struct nbd_handle *nbd;
  char *str;
  int flag;

  if (argc != 2) {
    fprintf (stderr, "%s socket\n", argv[0]);
    exit (EXIT_FAILURE);
  }

  /* Create the libnbd handle. */
  nbd = nbd_create ();
  if (nbd == NULL) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Request full information. */
#if LIBNBD_HAVE_NBD_SET_FULL_INFO /* Added in 1.4 */
  if (nbd_set_full_info (nbd, true) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }
#endif

  /* Connect to the NBD server over a
   * Unix domain socket.
   */
  if (nbd_connect_unix (nbd, argv[1]) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* See if the server provided extra details,
   * using functions added in 1.4
   */
#if LIBNBD_HAVE_NBD_GET_EXPORT_DESCRIPTION
  str = nbd_get_canonical_export_name (nbd);
  if (str)
    printf ("canonical_name = %s\n", str);
  free (str);
  str = nbd_get_export_description (nbd);
  if (str)
    printf ("description = %s\n", str);
  free (str);
#endif

  /* Read and print the flags. */
#define PRINT_FLAG(flag_fn)                     \
  flag = flag_fn (nbd);                         \
  if (flag == -1) {                             \
    fprintf (stderr, "%s\n", nbd_get_error ()); \
    exit (EXIT_FAILURE);                        \
  }                                             \
  printf (#flag_fn " = %s\n",                   \
          flag ? "true" : "false");

  PRINT_FLAG (nbd_can_cache);
  PRINT_FLAG (nbd_can_df);
  PRINT_FLAG (nbd_can_flush);
  PRINT_FLAG (nbd_can_fua);
  PRINT_FLAG (nbd_can_multi_conn);
  PRINT_FLAG (nbd_can_trim);
  PRINT_FLAG (nbd_can_zero);
#if LIBNBD_HAVE_NBD_CAN_FAST_ZERO
  /* Added in 1.2 */
  PRINT_FLAG (nbd_can_fast_zero);
#endif
#if LIBNBD_HAVE_NBD_CAN_BLOCK_STATUS_PAYLOAD
  /* Added in 1.18 */
  PRINT_FLAG (nbd_can_block_status_payload);
#endif
  PRINT_FLAG (nbd_is_read_only);
  PRINT_FLAG (nbd_is_rotational);

  /* Close the libnbd handle. */
  nbd_close (nbd);

  exit (EXIT_SUCCESS);
}

🦋 SEE ALSO 🦋

💜 AUTHORS 💜

  • Eric Blake
  • Richard W.M. Jones

absolute legends, no cap 👑

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

ok that's the legal bit, it's giving very serious but you gotta include it 💅

and that's the page bestie!! this one shipped as part of libnbd-1.25.8, dated 2026-10-13 — screenshot it, cite it, love it 💖✨🌸

📦 where this page comes from