sd_varlink_connect_address - Man Page

#include <systemd/sd-varlink​.h>

struct ucred; /* defined in <sys/socket​.h> */

int sd_varlink_connect_address(sd_varlink **ret, const char *address);

int sd_varlink_connect_exec(sd_varlink **ret, const char *command, char **argv);

int sd_varlink_connect_url(sd_varlink **ret, const char *url);

int sd_varlink_connect_fd(sd_varlink **ret, int fd);

int sd_varlink_connect_fd_pair(sd_varlink **ret, int input_fd, int output_fd, const struct ucred *override_ucred);

These five functions allocate a new client-side Varlink connection object and connect it to a Varlink service​. They differ only in how the service to talk to is specified​. On success, a reference to the new connection object is returned in ret; the caller owns this reference and must eventually release it with sd_varlink_unref(3), sd_varlink_close_unref(3) or sd_varlink_flush_close_unref(3)​.

All five functions return immediately; none of them blocks waiting for the connection to be fully established​. For socket-based connections the actual connect() may still be in progress when the function returns (see below); the connection object handles the completion transparently​.

The returned connection object is not attached to any event loop​. There are three ways to drive it: attach it to an sd-event(3) loop with sd_varlink_attach_event(3); run its I/O manually via sd_varlink_process(3) and sd_varlink_wait(3); or simply issue blocking method calls​. In particular it is perfectly fine to follow any of these connection functions directly with a synchronous, blocking call such as sd_varlink_call(3), which internally drives the connection (including completing a still-pending connect()) and returns once the reply has been received​. In that case no explicit event loop integration or manual processing is required​.

sd_varlink_connect_address() connects to an AF_UNIX stream socket whose address is given as a string in address​. The address must begin either with "/" (to reference a socket in the file system) or with "@" (to reference a socket in the abstract namespace, with the remainder of the string used as the abstract name)​. It must be at least two characters long​. No other forms are accepted (in particular, relative paths are refused)​. Abstract namespace names that embed NUL bytes cannot be expressed through this interface​. If a file system socket path is too long to fit into a sockaddr_un structure, the connection is established transparently via an O_PATH indirection, so overlong paths work​.

sd_varlink_connect_exec() forks off a child process and speaks the Varlink protocol with it over a connected AF_UNIX SOCK_STREAM socket pair​. command is the program to execute; it is looked up in $PATH in the usual way (i​.e​. via execvp(3))​. argv is the argument vector (a NULL-terminated string array) to pass to the child as its argv[]; if it is NULL or empty, an argument vector consisting of just command is synthesized​. The connected socket is handed to the child as file descriptor 3 using the sd_listen_fds(3) protocol, i​.e​. the child is invoked with $LISTEN_FDS set to "1", $LISTEN_FDNAMES set to "varlink", and the appropriate $LISTEN_PID (and, where available, $LISTEN_PIDFDID) variables​. The command and argv strings are copied into the connection object, so the caller may free or modify them once the function returns​.

sd_varlink_connect_url() is a higher-level interface that parses a service address string with a leading scheme and dispatches to the appropriate transport​. Despite the name, these strings are not Internet URLs in the sense of the relevant RFCs​. The following schemes are understood natively:

"unix:"PATH

Connects to an AF_UNIX socket, equivalent to passing PATH to sd_varlink_connect_address()​. PATH must either be an absolute, normalized file system path, or begin with "@" for an abstract namespace socket (for which no path normalization checks are applied)​.

"exec:"PATH

Forks off the executable at PATH, equivalent to passing it to sd_varlink_connect_exec() with no extra arguments​. PATH must be an absolute, normalized path​.

"ssh:"HOST":"PATH, "ssh-unix:"HOST":"PATH

Connects to an AF_UNIX socket at the absolute, normalized path PATH on the remote SSH host HOST​. This relies on OpenSSH 9​.4 or newer on the server side​. Abstract namespace sockets are not supported for this transport​. "ssh:" and "ssh-unix:" are synonyms​.

"ssh-exec:"HOST":"COMMAND

Invokes COMMAND (a command line, split on whitespace with shell-style quoting and unescaping) on the remote SSH host HOST and speaks the Varlink protocol over its standard input and output​.

If the scheme is none of the above but is otherwise a syntactically valid URL scheme, sd_varlink_connect_url() looks for a bridge helper binary of that name in the directory configured via $SYSTEMD_VARLINK_BRIDGES_DIR (see below)​. If found and executable, it is invoked like an "exec:" transport, with the complete, unmodified URL passed as its sole command line argument​. This allows additional transports to be plugged in out of tree​.

For the natively supported schemes, URL parameterization using ";", "?" or "#" is rejected (these are reserved for possible future use)​. A "vsock:" scheme is not currently supported​.

sd_varlink_connect_fd() turns an already existing, already connected file descriptor fd into a Varlink connection​. The descriptor is used for both reading and writing​. It may refer to a connected stream socket, but also to a pipe or other bidirectional file descriptor​.

sd_varlink_connect_fd_pair() is like sd_varlink_connect_fd(), but accepts a separate input_fd (used for reading from the peer) and output_fd (used for writing to the peer)​. This is useful when the two directions are backed by different descriptors, for example a pair of pipes, or the standard output and standard input of a co-process​. The two descriptors may also be identical, which is exactly what sd_varlink_connect_fd() does internally​. If override_ucred is non-NULL, the peer credentials reported for the connection (as returned e​.g​. by sd_varlink_get_peer_uid(3)) are taken from the supplied ucred structure instead of being queried from the socket via SO_PEERCRED​. This is primarily useful when the descriptors are not sockets (and hence carry no kernel-supplied peer credentials), or when the credentials need to be overridden for other reasons​. If override_ucred is NULL, peer credentials are determined from the socket as usual​.

sd_varlink_connect_fd() and sd_varlink_connect_fd_pair() take over ownership of the descriptors passed to them: the descriptors are closed automatically when the connection object is freed, and the caller must not close them itself​. On failure ownership remains with the caller​.

The connection objects created by sd_varlink_connect_exec(), and by the "exec:", "ssh:"/"ssh-unix:", "ssh-exec:" and bridge-helper paths of sd_varlink_connect_url(), are bound to the lifetime of the spawned child process​. When such a connection object is freed, the associated child process is sent SIGTERM and reaped​. The child is also configured to receive SIGTERM if the calling process dies​.

On success, these functions return a non-negative integer and store a pointer to the new connection object in ret​. On failure, they return a negative errno-style error code and leave ret unchanged​.

Functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd ​pkg-config(1) file​.

The code described here uses getenv(3), which is declared to be not multi-thread-safe​. This means that the code calling the functions described here must not call setenv(3) from a parallel thread​. It is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started​.

$SYSTEMD_SSH

Used by the "ssh:"/"ssh-unix:" and "ssh-exec:" transports of sd_varlink_connect_url() to override the ssh binary to invoke​. May be a plain file name (looked up in $PATH) or an absolute path​.

Added in version 257​.

$SYSTEMD_VARLINK_BRIDGES_DIR

Overrides the directory in which sd_varlink_connect_url() looks up bridge helper binaries for non-native URL schemes​. Defaults to /usr/lib/systemd/varlink-bridges/​.

Added in version 257​.

/usr/lib/systemd/varlink-bridges/

Default directory searched for bridge helper binaries when sd_varlink_connect_url() encounters a URL with a scheme that is not natively supported​. See sd-varlink(3) for details​.

sd_varlink_connect_address(), sd_varlink_connect_exec(), sd_varlink_connect_url(), sd_varlink_connect_fd() and sd_varlink_connect_fd_pair() were added in version 257​.

systemd(1), sd-varlink(3), sd_varlink_attach_event(3), sd_varlink_call(3), sd_varlink_send(3), sd_varlink_is_connected(3), sd_listen_fds(3), varlinkctl(1)

systemd.directives(7), systemd.index(7).

The man pages sd_varlink_connect_exec(3), sd_varlink_connect_fd(3), sd_varlink_connect_fd_pair(3) and sd_varlink_connect_url(3) are aliases of sd_varlink_connect_address(3).