1nbd_connect_command(3)              LIBNBD              nbd_connect_command(3)
2
3
4

NAME

6       nbd_connect_command - connect to NBD server command
7

SYNOPSIS

9        #include <libnbd.h>
10
11        int nbd_connect_command (struct nbd_handle *h, char **argv);
12

DESCRIPTION

14       Run the command as a subprocess and connect to it over stdin/stdout.
15       This is for use with NBD servers which can behave like inetd clients,
16       such as nbdkit(1) using the -s/--single flag, and nbd-server(1) with
17       port number set to 0.
18
19       To run qemu-nbd(1), use nbd_connect_systemd_socket_activation(3)
20       instead.
21
22   Subprocess
23       Libnbd will fork the "argv" command and pass the NBD socket to it using
24       file descriptors 0 and 1 (stdin/stdout):
25
26        ┌─────────┬─────────┐    ┌────────────────┐
27        │ program │ libnbd  │    │   NBD server   │
28        │         │         │    │       (argv)   │
29        │         │ socket ╍╍╍╍╍╍╍╍▶ stdin/stdout │
30        └─────────┴─────────┘    └────────────────┘
31
32       When the NBD handle is closed the server subprocess is killed.
33

RETURN VALUE

35       If the call is successful the function returns 0.
36

ERRORS

38       On error "-1" is returned.
39
40       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
41       of the error.
42

HANDLE STATE

44       The handle must be newly created, otherwise this call will return an
45       error.
46

VERSION

48       This function first appeared in libnbd 1.0.
49
50       If you need to test if this function is available at compile time check
51       if the following macro is defined:
52
53        #define LIBNBD_HAVE_NBD_CONNECT_COMMAND 1
54

EXAMPLE

56       This example is also available as examples/connect-command.c in the
57       libnbd source code.
58
59        /* This example shows how to run an NBD server
60         * (nbdkit) as a subprocess of libnbd.
61         */
62
63        #include <stdio.h>
64        #include <stdlib.h>
65        #include <string.h>
66
67        #include <libnbd.h>
68
69        int
70        main (int argc, char *argv[])
71        {
72          struct nbd_handle *nbd;
73          char wbuf[512], rbuf[512];
74          size_t i;
75
76          /* Create the libnbd handle. */
77          nbd = nbd_create ();
78          if (nbd == NULL) {
79            fprintf (stderr, "%s\n", nbd_get_error ());
80            exit (EXIT_FAILURE);
81          }
82
83          /* Run nbdkit as a subprocess. */
84          char *args[] = {
85            "nbdkit",
86
87            /* You must use ‘-s’ (which tells nbdkit to serve
88             * a single connection on stdin/stdout).
89             */
90            "-s",
91
92            /* It is recommended to use ‘--exit-with-parent’
93             * to ensure nbdkit is always cleaned up even
94             * if the main program crashes.
95             */
96            "--exit-with-parent",
97
98            /* Use this to enable nbdkit debugging. */
99            "-v",
100
101            /* The nbdkit plugin name - this is a RAM disk. */
102            "memory", "size=1M",
103
104            /* Use NULL to terminate the arg list. */
105            NULL
106          };
107          if (nbd_connect_command (nbd, args) == -1) {
108            fprintf (stderr, "%s\n", nbd_get_error ());
109            exit (EXIT_FAILURE);
110          }
111
112          /* Write some random data to the first sector. */
113          for (i = 0; i < sizeof wbuf; ++i)
114            wbuf[i] = i % 13;
115          if (nbd_pwrite (nbd, wbuf, sizeof wbuf, 0, 0) == -1) {
116            fprintf (stderr, "%s\n", nbd_get_error ());
117            exit (EXIT_FAILURE);
118          }
119
120          /* Read the first sector back. */
121          if (nbd_pread (nbd, rbuf, sizeof rbuf, 0, 0) == -1) {
122            fprintf (stderr, "%s\n", nbd_get_error ());
123            exit (EXIT_FAILURE);
124          }
125
126          /* Close the libnbd handle. */
127          nbd_close (nbd);
128
129          /* What was read must be exactly the same as what
130           * was written.
131           */
132          if (memcmp (rbuf, wbuf, sizeof rbuf) != 0) {
133            fprintf (stderr, "FAILED: "
134                     "read data did not match written data\n");
135            exit (EXIT_FAILURE);
136          }
137
138          exit (EXIT_SUCCESS);
139        }
140

SEE ALSO

142       nbd_aio_connect_command(3), nbd_connect_systemd_socket_activation(3),
143       nbd_create(3), nbd_kill_subprocess(3), libnbd(3), nbdkit(1).
144

AUTHORS

146       Eric Blake
147
148       Richard W.M. Jones
149

151       Copyright (C) 2019-2021 Red Hat Inc.
152

LICENSE

154       This library is free software; you can redistribute it and/or modify it
155       under the terms of the GNU Lesser General Public License as published
156       by the Free Software Foundation; either version 2 of the License, or
157       (at your option) any later version.
158
159       This library is distributed in the hope that it will be useful, but
160       WITHOUT ANY WARRANTY; without even the implied warranty of
161       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
162       Lesser General Public License for more details.
163
164       You should have received a copy of the GNU Lesser General Public
165       License along with this library; if not, write to the Free Software
166       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
167       02110-1301 USA
168
169
170
171libnbd-1.10.1                     2021-10-25            nbd_connect_command(3)
Impressum