nbd_connect_systemd_socket_activation(3)

1nbd_connect_systemd_socket_activationL(I3Bn)NbBdD_connect_systemd_socket_activation(3)
2
3
4

NAME

6       nbd_connect_systemd_socket_activation - connect using systemd socket
7       activation
8

SYNOPSIS

10        #include <libnbd.h>
11
12        int nbd_connect_systemd_socket_activation (
13              struct nbd_handle *h, char **argv
14            );
15

DESCRIPTION

17       Run the command as a subprocess and connect to it using systemd socket
18       activation.
19
20       This is especially useful for running qemu-nbd(1) as a subprocess of
21       libnbd, for example to use it to open qcow2 files.
22
23       To run nbdkit as a subprocess, this function can be used, or
24       nbd_connect_command(3).
25
26       To run nbd-server(1) as a subprocess, this function cannot be used, you
27       must use nbd_connect_command(3).
28
29   Socket activation
30       Libnbd will fork the "argv" command and pass an NBD socket to it using
31       special "LISTEN_*" environment variables (as defined by the systemd
32       socket activation protocol).
33
34        ┌─────────┬─────────┐    ┌───────────────┐
35        │ program │ libnbd  │    │  qemu-nbd or  │
36        │         │         │    │  other server │
37        │         │ socket ╍╍╍╍╍╍╍╍▶             │
38        └─────────┴─────────┘    └───────────────┘
39
40       When the NBD handle is closed the server subprocess is killed.
41
42       Socket name
43
44       The socket activation protocol lets you optionally give the socket a
45       name.  If used, the name is passed to the NBD server using the
46       "LISTEN_FDNAMES" environment variable.  To provide a socket name, call
47       nbd_set_socket_activation_name(3) before calling the connect function.
48
49       This call returns when the connection has been made.  By default, this
50       proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
51       be used for manual control over option negotiation performed before
52       transmission phase.
53

RETURN VALUE

55       If the call is successful the function returns 0.
56

ERRORS

58       On error -1 is returned.
59
60       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
61       of the error.
62
63       The following parameters must not be NULL: "h", "argv".  For more
64       information see "Non-NULL parameters" in libnbd(3).
65

HANDLE STATE

67       The handle must be newly created, otherwise this call will return an
68       error.
69

VERSION

71       This function first appeared in libnbd 1.2.
72
73       If you need to test if this function is available at compile time check
74       if the following macro is defined:
75
76        #define LIBNBD_HAVE_NBD_CONNECT_SYSTEMD_SOCKET_ACTIVATION 1
77

EXAMPLE

79       This example is also available as examples/open-qcow2.c in the libnbd
80       source code.
81
82        /* This example shows how to use qemu-nbd
83         * to open a local qcow2 file.
84         */
85
86        #include <stdio.h>
87        #include <stdlib.h>
88        #include <string.h>
89
90        #include <libnbd.h>
91
92        int
93        main (int argc, const char *argv[])
94        {
95          const char *filename;
96          struct nbd_handle *nbd;
97          char buf[512];
98          FILE *fp;
99
100          if (argc != 2) {
101            fprintf (stderr, "open-qcow2 file.qcow2\n");
102            exit (EXIT_FAILURE);
103          }
104          filename = argv[1];
105
106          /* Create the libnbd handle. */
107          nbd = nbd_create ();
108          if (nbd == NULL) {
109            fprintf (stderr, "%s\n", nbd_get_error ());
110            exit (EXIT_FAILURE);
111          }
112
113          /* Run qemu-nbd as a subprocess using
114           * systemd socket activation.
115           */
116          char *args[] = {
117            "qemu-nbd", "-f", "qcow2",
118            (char *)filename,
119            NULL
120          };
121          if (nbd_connect_systemd_socket_activation (nbd,
122                                                     args) == -1) {
123            fprintf (stderr, "%s\n", nbd_get_error ());
124            exit (EXIT_FAILURE);
125          }
126
127          /* Read the first sector and print it. */
128          if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
129            fprintf (stderr, "%s\n", nbd_get_error ());
130            exit (EXIT_FAILURE);
131          }
132
133          fp = popen ("hexdump -C", "w");
134          if (fp == NULL) {
135            perror ("popen: hexdump");
136            exit (EXIT_FAILURE);
137          }
138          fwrite (buf, sizeof buf, 1, fp);
139          pclose (fp);
140
141          /* Close the libnbd handle. */
142          nbd_close (nbd);
143
144          exit (EXIT_SUCCESS);
145        }
146

AUTHORS

155       Eric Blake
156
157       Richard W.M. Jones
158

COPYRIGHT

160       Copyright Red Hat
161

LICENSE

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