1nbd_connect_unix(3) LIBNBD nbd_connect_unix(3)
2
6 nbd_connect_unix - connect to NBD server over a Unix domain socket
7
9 #include <libnbd.h>
10 int nbd_connect_unix (
12 struct nbd_handle *h, const char *unixsocket
13 );
14
16 Connect (synchronously) over the named Unix domain socket
17 ("unixsocket") to an NBD server running on the same machine.
18 This call returns when the connection has been made. By default, this
20 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
21 be used for manual control over option negotiation performed before
22 transmission phase.
23
25 If the call is successful the function returns 0.
26
28 On error -1 is returned.
29 Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
31 of the error.
32 The following parameters must not be NULL: "h", "unixsocket". For more
34 information see "Non-NULL parameters" in libnbd(3).
35
37 The handle must be newly created, otherwise this call will return an
38 error.
39
41 This function first appeared in libnbd 1.0.
42 If you need to test if this function is available at compile time check
44 if the following macro is defined:
45 #define LIBNBD_HAVE_NBD_CONNECT_UNIX 1
47
49 This example is also available as examples/fetch-first-sector.c in the
50 libnbd source code.
51 /* This example shows how to connect to an NBD server
53 * and fetch and print the first sector (usually the
54 * boot sector or partition table or filesystem
55 * superblock).
56 *
57 * You can test it with nbdkit like this:
58 *
59 * nbdkit -U - floppy . \
60 * --run './fetch-first-sector $unixsocket'
61 *
62 * The nbdkit floppy plugin creates an MBR disk so the
63 * first sector is the partition table.
64 */
65 #include <stdio.h>
67 #include <stdlib.h>
68 #include <libnbd.h>
70 int
72 main (int argc, char *argv[])
73 {
74 struct nbd_handle *nbd;
75 char buf[512];
76 FILE *pp;
77 if (argc != 2) {
79 fprintf (stderr, "%s socket\n", argv[0]);
80 exit (EXIT_FAILURE);
81 }
82 /* Create the libnbd handle. */
84 nbd = nbd_create ();
85 if (nbd == NULL) {
86 fprintf (stderr, "%s\n", nbd_get_error ());
87 exit (EXIT_FAILURE);
88 }
89 /* Connect to the NBD server over a
91 * Unix domain socket.
92 */
93 if (nbd_connect_unix (nbd, argv[1]) == -1) {
94 fprintf (stderr, "%s\n", nbd_get_error ());
95 exit (EXIT_FAILURE);
96 }
97 /* Read the first sector synchronously. */
99 if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
100 fprintf (stderr, "%s\n", nbd_get_error ());
101 exit (EXIT_FAILURE);
102 }
103 /* Close the libnbd handle. */
105 nbd_close (nbd);
106 /* Print the first sector. */
108 pp = popen ("hexdump -C", "w");
109 if (pp == NULL) {
110 perror ("popen: hexdump");
111 exit (EXIT_FAILURE);
112 }
113 fwrite (buf, sizeof buf, 1, pp);
114 pclose (pp);
115 exit (EXIT_SUCCESS);
117 }
118
120 nbd_aio_connect_unix(3), nbd_create(3), nbd_set_opt_mode(3), libnbd(3).
121
123 Eric Blake
124 Richard W.M. Jones
126
128 Copyright Red Hat
129
131 This library is free software; you can redistribute it and/or modify it
132 under the terms of the GNU Lesser General Public License as published
133 by the Free Software Foundation; either version 2 of the License, or
134 (at your option) any later version.
135 This library is distributed in the hope that it will be useful, but
137 WITHOUT ANY WARRANTY; without even the implied warranty of
138 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
139 Lesser General Public License for more details.
140 You should have received a copy of the GNU Lesser General Public
142 License along with this library; if not, write to the Free Software
143 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
144 02110-1301 USA
145libnbd-1.18.1 2023-10-31 nbd_connect_unix(3)