nbd\_zero(3) LIBNBD nbd\_zero(3) # [NAME](#NAME) nbd\_zero - send write zeroes command to the NBD server # [SYNOPSIS](#SYNOPSIS) ``` #include int nbd_zero ( struct nbd_handle *h, uint64_t count, uint64_t offset, uint32_t flags ); ``` # [DESCRIPTION](#DESCRIPTION) Issue a write zeroes command to the NBD server, which if supported by the server causes a zeroes to be written efficiently starting at "offset" and ending at "offset" + "count" - 1. The call returns when the command has been acknowledged by the server, or there is an error. Note this will generally return an error if [**nbd\_can\_zero**(3)](/man/os/libnbd/nbd_can_zero.3) is false or [**nbd\_is\_read\_only**(3)](/man/os/libnbd/nbd_is_read_only.3) is true. Note that not all servers can support a "count" of 4GiB or larger; [**nbd\_get\_extended\_headers\_negotiated**(3)](/man/os/libnbd/nbd_get_extended_headers_negotiated.3) indicates which servers will parse a request larger than 32 bits. The NBD protocol does not yet have a way for a client to learn if the server will enforce an even smaller maximum zero size, although a future extension may add a constraint visible in [**nbd\_get\_block\_size**(3)](/man/os/libnbd/nbd_get_block_size.3). Also, some servers may permit a larger zero request only when the "LIBNBD\_CMD\_FLAG\_FAST\_ZERO" is in use. The "flags" parameter may be 0 for no flags, or may contain "LIBNBD\_CMD\_FLAG\_FUA" meaning that the server should not return until the data has been committed to permanent storage (if that is supported - some servers cannot do this, see [**nbd\_can\_fua**(3)](/man/os/libnbd/nbd_can_fua.3)), "LIBNBD\_CMD\_FLAG\_NO\_HOLE" meaning that the server should favor writing actual allocated zeroes over punching a hole, and/or "LIBNBD\_CMD\_FLAG\_FAST\_ZERO" meaning that the server must fail quickly if writing zeroes is no faster than a normal write (if that is supported - some servers cannot do this, see [**nbd\_can\_fast\_zero**(3)](/man/os/libnbd/nbd_can_fast_zero.3)). # [RETURN VALUE](#RETURN_VALUE) If the call is successful the function returns 0. # [ERRORS](#ERRORS) On error -1 is returned. Refer to "ERROR HANDLING" in [**libnbd**(3)](/man/os/libnbd/libnbd.3) for how to get further details of the error. The following parameters must not be NULL: "h". For more information see "Non-NULL parameters" in [**libnbd**(3)](/man/os/libnbd/libnbd.3). # [NOTES](#NOTES) ## [Strict call](#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)](/man/os/libnbd/nbd_set_strict_mode.3) function can be used to alter which scenarios should await a server reply rather than failing fast. # [HANDLE STATE](#HANDLE_STATE) nbd\_zero 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 │ └─────────────────────────────────────┴─────────────────────────┘ ``` # [VERSION](#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_ZERO 1 ``` # [SEE ALSO](#SEE_ALSO) [**nbd\_aio\_zero**(3)](/man/os/libnbd/nbd_aio_zero.3), [**nbd\_can\_fast\_zero**(3)](/man/os/libnbd/nbd_can_fast_zero.3), [**nbd\_can\_fua**(3)](/man/os/libnbd/nbd_can_fua.3), [**nbd\_can\_zero**(3)](/man/os/libnbd/nbd_can_zero.3), [**nbd\_create**(3)](/man/os/libnbd/nbd_create.3), [**nbd\_get\_block\_size**(3)](/man/os/libnbd/nbd_get_block_size.3), [**nbd\_get\_extended\_headers\_negotiated**(3)](/man/os/libnbd/nbd_get_extended_headers_negotiated.3), [**nbd\_is\_read\_only**(3)](/man/os/libnbd/nbd_is_read_only.3), [**nbd\_set\_strict\_mode**(3)](/man/os/libnbd/nbd_set_strict_mode.3), [**libnbd**(3)](/man/os/libnbd/libnbd.3). # [AUTHORS](#AUTHORS) Eric Blake Richard W.M. Jones # [COPYRIGHT](#COPYRIGHT) Copyright Red Hat # [LICENSE](#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 2026-10-13 libnbd-1.25.8 --- Document: nbd_zero(3) from libnbd 1.25.8-r0 (Chainguard OS)