NAME¶

sd_varlink_connect_address, sd_varlink_connect_exec, sd_varlink_connect_url, sd_varlink_connect_fd, sd_varlink_connect_fd_pair - Create a Varlink connection object and connect it to a service

SYNOPSIS¶

#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);

DESCRIPTION¶

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

"exec:"PATH

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

"ssh-exec:"HOST":"COMMAND

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.

RETURN VALUE¶

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.

NOTES¶

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.

ENVIRONMENT¶

$SYSTEMD_SSH

$SYSTEMD_VARLINK_BRIDGES_DIR

FILES¶

/usr/lib/systemd/varlink-bridges/

HISTORY¶

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.

SEE ALSO¶

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)