1nbd_connect_unix(3)                 LIBNBD                 nbd_connect_unix(3)
2
3
4

NAME

6       nbd_connect_unix - connect to NBD server over a Unix domain socket
7

SYNOPSIS

9        #include <libnbd.h>
10
11        int nbd_connect_unix (struct nbd_handle *h,
12                              const char *unixsocket);
13

DESCRIPTION

15       Connect (synchronously) over the named Unix domain socket
16       ("unixsocket") to an NBD server running on the same machine.  This call
17       returns when the connection has been made.
18

RETURN VALUE

20       If the call is successful the function returns 0.
21

ERRORS

23       On error "-1" is returned.
24
25       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
26       of the error.
27

HANDLE STATE

29       The handle must be newly created, otherwise this call will return an
30       error.
31

VERSION

33       This function first appeared in libnbd 1.0.
34
35       If you need to test if this function is available at compile time check
36       if the following macro is defined:
37
38        #define LIBNBD_HAVE_NBD_CONNECT_UNIX 1
39

EXAMPLE

41       This example is also available as examples/fetch-first-sector.c in the
42       libnbd source code.
43
44        /* This example shows how to connect to an NBD server
45         * and fetch and print the first sector (usually the
46         * boot sector or partition table or filesystem
47         * superblock).
48         *
49         * You can test it with nbdkit like this:
50         *
51         * nbdkit -U - floppy . \
52         *   --run './fetch-first-sector $unixsocket'
53         *
54         * The nbdkit floppy plugin creates an MBR disk so the
55         * first sector is the partition table.
56         */
57
58        #include <stdio.h>
59        #include <stdlib.h>
60
61        #include <libnbd.h>
62
63        int
64        main (int argc, char *argv[])
65        {
66          struct nbd_handle *nbd;
67          char buf[512];
68          FILE *pp;
69
70          if (argc != 2) {
71            fprintf (stderr, "%s socket\n", argv[0]);
72            exit (EXIT_FAILURE);
73          }
74
75          /* Create the libnbd handle. */
76          nbd = nbd_create ();
77          if (nbd == NULL) {
78            fprintf (stderr, "%s\n", nbd_get_error ());
79            exit (EXIT_FAILURE);
80          }
81
82          /* Connect to the NBD server over a
83           * Unix domain socket.
84           */
85          if (nbd_connect_unix (nbd, argv[1]) == -1) {
86            fprintf (stderr, "%s\n", nbd_get_error ());
87            exit (EXIT_FAILURE);
88          }
89
90          /* Read the first sector synchronously. */
91          if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
92            fprintf (stderr, "%s\n", nbd_get_error ());
93            exit (EXIT_FAILURE);
94          }
95
96          /* Close the libnbd handle. */
97          nbd_close (nbd);
98
99          /* Print the first sector. */
100          pp = popen ("hexdump -C", "w");
101          if (pp == NULL) {
102            perror ("popen: hexdump");
103            exit (EXIT_FAILURE);
104          }
105          fwrite (buf, sizeof buf, 1, pp);
106          pclose (pp);
107
108          exit (EXIT_SUCCESS);
109        }
110

SEE ALSO

112       nbd_create(3), libnbd(3).
113

AUTHORS

115       Eric Blake
116
117       Richard W.M. Jones
118
120       Copyright (C) 2019-2021 Red Hat Inc.
121

LICENSE

123       This library is free software; you can redistribute it and/or modify it
124       under the terms of the GNU Lesser General Public License as published
125       by the Free Software Foundation; either version 2 of the License, or
126       (at your option) any later version.
127
128       This library is distributed in the hope that it will be useful, but
129       WITHOUT ANY WARRANTY; without even the implied warranty of
130       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
131       Lesser General Public License for more details.
132
133       You should have received a copy of the GNU Lesser General Public
134       License along with this library; if not, write to the Free Software
135       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
136       02110-1301 USA
137
138
139
140libnbd-1.7.12                     2021-05-29               nbd_connect_unix(3)
Impressum