nbd_connect_command(3)

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 (
12              struct nbd_handle *h, char **argv
13            );
14

DESCRIPTION

16       Run the command as a subprocess and connect to it over stdin/stdout.
17       This is for use with NBD servers which can behave like inetd clients,
18       such as nbdkit(1) using the -s/--single flag, and nbd-server(1) with
19       port number set to 0.
20
21       To run qemu-nbd(1), use nbd_connect_systemd_socket_activation(3)
22       instead.
23
24   Subprocess
25       Libnbd will fork the "argv" command and pass the NBD socket to it using
26       file descriptors 0 and 1 (stdin/stdout):
27
28        ┌─────────┬─────────┐    ┌────────────────┐
29        │ program │ libnbd  │    │   NBD server   │
30        │         │         │    │       (argv)   │
31        │         │ socket ╍╍╍╍╍╍╍╍▶ stdin/stdout │
32        └─────────┴─────────┘    └────────────────┘
33
34       When the NBD handle is closed the server subprocess is killed.
35
36       This call returns when the connection has been made.  By default, this
37       proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
38       be used for manual control over option negotiation performed before
39       transmission phase.
40

RETURN VALUE

42       If the call is successful the function returns 0.
43

ERRORS

45       On error -1 is returned.
46
47       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
48       of the error.
49
50       The following parameters must not be NULL: "h", "argv".  For more
51       information see "Non-NULL parameters" in libnbd(3).
52

HANDLE STATE

54       The handle must be newly created, otherwise this call will return an
55       error.
56

VERSION

58       This function first appeared in libnbd 1.0.
59
60       If you need to test if this function is available at compile time check
61       if the following macro is defined:
62
63        #define LIBNBD_HAVE_NBD_CONNECT_COMMAND 1
64

EXAMPLE

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

AUTHORS

157       Eric Blake
158
159       Richard W.M. Jones
160

COPYRIGHT

162       Copyright Red Hat
163

LICENSE

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