|
HTML rendering created 2026-05-24 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | ENVIRONMENT | FILES | HISTORY | SEE ALSO | COLOPHON |
|
|
|
SD_VARLI..._ADDRESS(3) sd_varlink_connect_address SD_VARLI..._ADDRESS(3)
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
#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.
Errors
Returned errors may indicate the following problems:
-EINVAL
A required argument is NULL, or the supplied address, command,
or URL is malformed. This includes addresses that do not begin
with "/" or "@", abstract namespace names that do not fit into
a sockaddr_un structure, and — for sd_varlink_connect_url() —
file system paths that are not absolute or not normalized.
-EBADF
For sd_varlink_connect_fd() and sd_varlink_connect_fd_pair():
a supplied file descriptor is negative.
-EPROTONOSUPPORT
For sd_varlink_connect_url(): the URL contains no ":"
separator, uses an unsupported scheme for which no bridge
helper binary is available, or makes use of the reserved ";",
"?" or "#" URL parameterization characters with a natively
supported scheme.
-ENOMEM
Memory allocation failed.
In addition, these functions may propagate any error returned by
the underlying system calls they use, such as socket(2),
connect(2), fork(2), pipe(2) and the various execution helpers.
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)
This page is part of the systemd (systemd system and service
manager) project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a
bug report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
This page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2026-05-24. (At that
time, the date of the most recent commit that was found in the
repository was 2026-05-24.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
systemd 261~rc1 SD_VARLI..._ADDRESS(3)
Pages that refer to this page: systemd.directives(7), systemd.index(7)
|
HTML rendering created 2026-05-24 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|