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
43       The following parameters must not be NULL: "h", "argv".  For more
44       information see "Non-NULL parameters" in libnbd(3).
45

HANDLE STATE

47       The handle must be newly created, otherwise this call will return an
48       error.
49

VERSION

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

EXAMPLE

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

SEE ALSO

145       nbd_aio_connect_command(3), nbd_connect_systemd_socket_activation(3),
146       nbd_create(3), nbd_kill_subprocess(3), libnbd(3), nbdkit(1).
147

AUTHORS

149       Eric Blake
150
151       Richard W.M. Jones
152

154       Copyright (C) 2019-2021 Red Hat Inc.
155

LICENSE

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