--- name: "nbd_connect_systemd_socket_activation" section: "3" platform: "linux" package: "libnbd" version: "1.24.4-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/nbd_connect_systemd_socket_activation" --- # nbd\_connect\_systemd\_socket\_activation(3) connect using systemd socket activation ## NAME nbd\_connect\_systemd\_socket\_activation - connect using systemd socket activation ## SYNOPSIS ``` #include int nbd_connect_systemd_socket_activation ( struct nbd_handle *h, char **argv ); ``` ## DESCRIPTION Run the command as a subprocess and connect to it using systemd socket activation. This is especially useful for running **qemu-nbd**(1) as a subprocess of libnbd, for example to use it to open qcow2 files. To run nbdkit as a subprocess, this function can be used, or [**nbd\_connect\_command**(3)](/nbd_connect_command/3.md). To run [**nbd-server**(1)](/nbd-server/1.md) as a subprocess, this function cannot be used, you must use [**nbd\_connect\_command**(3)](/nbd_connect_command/3.md). ### Socket activation Libnbd will fork the `"argv"` command and pass an NBD socket to it using special `"LISTEN_*"` environment variables (as defined by the systemd socket activation protocol). ``` ┌─────────┬─────────┐ ┌───────────────┐ │ program │ libnbd │ │ qemu-nbd or │ │ │ │ │ other server │ │ │ socket ╍╍╍╍╍╍╍╍▶ │ └─────────┴─────────┘ └───────────────┘ ``` When the NBD handle is closed the server subprocess is killed. *Socket name* The socket activation protocol lets you optionally give the socket a name. If used, the name is passed to the NBD server using the `"LISTEN_FDNAMES"` environment variable. To provide a socket name, call [**nbd\_set\_socket\_activation\_name**(3)](/nbd_set_socket_activation_name/3.md) before calling the connect function. This call returns when the connection has been made. By default, this proceeds all the way to transmission phase, but [**nbd\_set\_opt\_mode**(3)](/nbd_set_opt_mode/3.md) can be used for manual control over option negotiation performed before transmission phase. ## RETURN VALUE If the call is successful the function returns `0`. ## ERRORS On error `-1` is returned. Refer to "ERROR HANDLING" in [**libnbd**(3)](/libnbd/3.md) for how to get further details of the error. The following parameters must not be NULL: `"h"`, `"argv"`. For more information see "Non-NULL parameters" in [**libnbd**(3)](/libnbd/3.md). ## HANDLE STATE nbd\_connect\_systemd\_socket\_activation can be called when the handle is in the following state: ``` ┌─────────────────────────────────────┬─────────────────────────┐ │ Handle created, before connecting │ ✅ allowed │ │ Connecting │ ❌ error │ │ Connecting & handshaking (opt_mode) │ ❌ error │ │ Connected to the server │ ❌ error │ │ Connection shut down │ ❌ error │ │ Handle dead │ ❌ error │ └─────────────────────────────────────┴─────────────────────────┘ ``` ## VERSION This function first appeared in libnbd 1.2. If you need to test if this function is available at compile time check if the following macro is defined: ``` #define LIBNBD_HAVE_NBD_CONNECT_SYSTEMD_SOCKET_ACTIVATION 1 ``` ## EXAMPLE This example is also available as *examples/open-qcow2.c* in the libnbd source code. ``` /* This example shows how to use qemu-nbd * to open a local qcow2 file. */ #include #include #include #include int main (int argc, const char *argv[]) { const char *filename; struct nbd_handle *nbd; char buf[512]; FILE *fp; if (argc != 2) { fprintf (stderr, "open-qcow2 file.qcow2\n"); exit (EXIT_FAILURE); } filename = argv[1]; /* Create the libnbd handle. */ nbd = nbd_create (); if (nbd == NULL) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } /* Run qemu-nbd as a subprocess using * systemd socket activation. */ char *args[] = { "qemu-nbd", "-f", "qcow2", (char *)filename, NULL }; if (nbd_connect_systemd_socket_activation (nbd, args) == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } /* Read the first sector and print it. */ if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } fp = popen ("hexdump -C", "w"); if (fp == NULL) { perror ("popen: hexdump"); exit (EXIT_FAILURE); } fwrite (buf, sizeof buf, 1, fp); pclose (fp); /* Close the libnbd handle. */ nbd_close (nbd); exit (EXIT_SUCCESS); } ``` ## SEE ALSO [**nbd\_aio\_connect\_systemd\_socket\_activation**(3)](/nbd_aio_connect_systemd_socket_activation/3.md), [**nbd\_connect\_command**(3)](/nbd_connect_command/3.md), [**nbd\_create**(3)](/nbd_create/3.md), [**nbd\_get\_socket\_activation\_name**(3)](/nbd_get_socket_activation_name/3.md), [**nbd\_get\_subprocess\_pid**(3)](/nbd_get_subprocess_pid/3.md), [**nbd\_kill\_subprocess**(3)](/nbd_kill_subprocess/3.md), [**nbd\_set\_opt\_mode**(3)](/nbd_set_opt_mode/3.md), [**nbd\_set\_socket\_activation\_name**(3)](/nbd_set_socket_activation_name/3.md), [**libnbd**(3)](/libnbd/3.md), **qemu-nbd**(1), http://0pointer.de/blog/projects/socket-activation.html. ## AUTHORS Eric Blake Richard W.M. Jones ## COPYRIGHT Copyright Red Hat ## LICENSE This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA