nbd\_pread(3) LIBNBD nbd\_pread(3) # [NAME](#NAME) nbd\_pread - read from the NBD server # [SYNOPSIS](#SYNOPSIS) ``` #include int nbd_pread ( struct nbd_handle *h, void *buf, size_t count, uint64_t offset, uint32_t flags ); ``` # [DESCRIPTION](#DESCRIPTION) Issue a read command to the NBD server for the range starting at "offset" and ending at "offset" + "count" - 1. NBD can only read all or nothing using this call. The call returns when the data has been read fully into "buf" or there is an error. See also [**nbd\_pread\_structured**(3)](/man/os/libnbd/nbd_pread_structured.3), if finer visibility is required into the server's replies, or if you want to use "LIBNBD\_CMD\_FLAG\_DF". Note that libnbd currently enforces a maximum read buffer of 64MiB, even if the server would permit a larger buffer in a single transaction; attempts to exceed this will result in an "ERANGE" error. The server may enforce a smaller limit, which can be learned with [**nbd\_get\_block\_size**(3)](/man/os/libnbd/nbd_get_block_size.3). The "flags" parameter must be 0 for now (it exists for future NBD protocol extensions). Note that if this command fails, and [**nbd\_get\_pread\_initialize**(3)](/man/os/libnbd/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)](/man/os/libnbd/nbd_get_pread_initialize.3) returns false, then libnbd did not sanitize "buf", and the contents are undefined on failure. # [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", "buf". 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\_pread 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_PREAD 1 ``` # [EXAMPLE](#EXAMPLE) This example is also available as *examples/fetch-first-sector.c* in the libnbd source code. ``` /* This example shows how to connect to an NBD server * and fetch and print the first sector (usually the * boot sector or partition table or filesystem * superblock). * * You can test it with nbdkit like this: * * nbdkit -U - floppy . \ * --run './fetch-first-sector $unixsocket' * * The nbdkit floppy plugin creates an MBR disk so the * first sector is the partition table. */ #include #include #include int main (int argc, char *argv[]) { struct nbd_handle *nbd; char buf[512]; FILE *pp; 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); } /* 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); } /* Read the first sector synchronously. */ if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } /* Close the libnbd handle. */ nbd_close (nbd); /* Print the first sector. */ pp = popen ("hexdump -C", "w"); if (pp == NULL) { perror ("popen: hexdump"); exit (EXIT_FAILURE); } fwrite (buf, sizeof buf, 1, pp); pclose (pp); exit (EXIT_SUCCESS); } ``` # [SEE ALSO](#SEE_ALSO) [**nbd\_aio\_pread**(3)](/man/os/libnbd/nbd_aio_pread.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\_pread\_initialize**(3)](/man/os/libnbd/nbd_get_pread_initialize.3), [**nbd\_pread\_structured**(3)](/man/os/libnbd/nbd_pread_structured.3), [**nbd\_set\_pread\_initialize**(3)](/man/os/libnbd/nbd_set_pread_initialize.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_pread(3) from libnbd 1.25.8-r0 (Chainguard OS)