sd_varlink_connect_address(3)

.SH "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

.SH "SYNOPSIS"

#include <systemd/sd-varlink.h>

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

.HP 744u int sd_varlink_connect_address(sd_varlink **ret, const char *address);

.HP 672u int sd_varlink_connect_exec(sd_varlink **ret, const char *command, char **argv);

.HP 648u int sd_varlink_connect_url(sd_varlink **ret, const char *url);

.HP 624u int sd_varlink_connect_fd(sd_varlink **ret, int fd);

.HP 744u int sd_varlink_connect_fd_pair(sd_varlink **ret, int input_fd, int output_fd, const struct ucred *override_ucred);

.SH "DESCRIPTION"

.PP 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).

.PP 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.

.PP 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.

.PP 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.

.PP 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.

.PP 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:

.PP unix:PATH