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

DESCRIPTION

16       Run the command as a subprocess and connect to it using systemd socket
17       activation.
18
19       This is especially useful for running qemu-nbd(1) as a subprocess of
20       libnbd, for example to use it to open qcow2 files.
21
22       To run nbdkit as a subprocess, this function can be used, or
23       nbd_connect_command(3).
24
25       To run nbd-server(1) as a subprocess, this function cannot be used, you
26       must use nbd_connect_command(3).
27
28   Socket activation
29       Libnbd will fork the "argv" command and pass an NBD socket to it using
30       special "LISTEN_*" environment variables (as defined by the systemd
31       socket activation protocol).
32
33        ┌─────────┬─────────┐    ┌───────────────┐
34        │ program │ libnbd  │    │  qemu-nbd or  │
35        │         │         │    │  other server │
36        │         │ socket ╍╍╍╍╍╍╍╍▶             │
37        └─────────┴─────────┘    └───────────────┘
38
39       When the NBD handle is closed the server subprocess is killed.
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.2.
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_SYSTEMD_SOCKET_ACTIVATION 1
64

EXAMPLE

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

AUTHORS

140       Eric Blake
141
142       Richard W.M. Jones
143

COPYRIGHT

145       Copyright (C) 2019-2021 Red Hat Inc.
146

LICENSE

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