'\" t
.TH "SD_VARLINK_CONNECT_ADDRESS" "3" "" "systemd 261.2" "sd_varlink_connect_address"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.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"
.sp
.ft B
.nf
#include <systemd/sd\-varlink\&.h>
.fi
.ft
.sp
.ft B
.nf
struct ucred; /* defined in <sys/socket\&.h> */
.fi
.ft
.HP \w'int\ sd_varlink_connect_address('u
.BI "int sd_varlink_connect_address(sd_varlink\ **" "ret" ", const\ char\ *" "address" ");"
.HP \w'int\ sd_varlink_connect_exec('u
.BI "int sd_varlink_connect_exec(sd_varlink\ **" "ret" ", const\ char\ *" "command" ", char\ **" "argv" ");"
.HP \w'int\ sd_varlink_connect_url('u
.BI "int sd_varlink_connect_url(sd_varlink\ **" "ret" ", const\ char\ *" "url" ");"
.HP \w'int\ sd_varlink_connect_fd('u
.BI "int sd_varlink_connect_fd(sd_varlink\ **" "ret" ", int\ " "fd" ");"
.HP \w'int\ sd_varlink_connect_fd_pair('u
.BI "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
\fIret\fR; the caller owns this reference and must eventually release it with
\fBsd_varlink_unref\fR(3),
\fBsd_varlink_close_unref\fR(3)
or
\fBsd_varlink_flush_close_unref\fR(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
\fBconnect()\fR
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
\fBsd-event\fR(3)
loop with
\fBsd_varlink_attach_event\fR(3); run its I/O manually via
\fBsd_varlink_process\fR(3)
and
\fBsd_varlink_wait\fR(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
\fBsd_varlink_call\fR(3), which internally drives the connection (including completing a still\-pending
\fBconnect()\fR) and returns once the reply has been received\&. In that case no explicit event loop integration or manual processing is required\&.
.PP
\fBsd_varlink_connect_address()\fR
connects to an
\fBAF_UNIX\fR
stream socket whose address is given as a string in
\fIaddress\fR\&. 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
\fBNUL\fR
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
\fBO_PATH\fR
indirection, so overlong paths work\&.
.PP
\fBsd_varlink_connect_exec()\fR
forks off a child process and speaks the Varlink protocol with it over a connected
\fBAF_UNIX\fR
\fBSOCK_STREAM\fR
socket pair\&.
\fIcommand\fR
is the program to execute; it is looked up in
\fI$PATH\fR
in the usual way (i\&.e\&. via
\fBexecvp\fR(3))\&.
\fIargv\fR
is the argument vector (a
\fBNULL\fR\-terminated string array) to pass to the child as its
\fIargv[]\fR; if it is
\fBNULL\fR
or empty, an argument vector consisting of just
\fIcommand\fR
is synthesized\&. The connected socket is handed to the child as file descriptor 3 using the
\fBsd_listen_fds\fR(3)
protocol, i\&.e\&. the child is invoked with
\fI$LISTEN_FDS\fR
set to
"1",
\fI$LISTEN_FDNAMES\fR
set to
"varlink", and the appropriate
\fI$LISTEN_PID\fR
(and, where available,
\fI$LISTEN_PIDFDID\fR) variables\&. The
\fIcommand\fR
and
\fIargv\fR
strings are copied into the connection object, so the caller may free or modify them once the function returns\&.
.PP
\fBsd_varlink_connect_url()\fR
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
\fInot\fR
Internet URLs in the sense of the relevant RFCs\&. The following schemes are understood natively:
.PP
"unix:"\fIPATH\fR
.RS 4
Connects to an
\fBAF_UNIX\fR
socket, equivalent to passing
\fIPATH\fR
to
\fBsd_varlink_connect_address()\fR\&.
\fIPATH\fR
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)\&.
.RE
.PP
"exec:"\fIPATH\fR
.RS 4
Forks off the executable at
\fIPATH\fR, equivalent to passing it to
\fBsd_varlink_connect_exec()\fR
with no extra arguments\&.
\fIPATH\fR
must be an absolute, normalized path\&.
.RE
.PP
"ssh:"\fIHOST\fR":"\fIPATH\fR, "ssh\-unix:"\fIHOST\fR":"\fIPATH\fR
.RS 4
Connects to an
\fBAF_UNIX\fR
socket at the absolute, normalized path
\fIPATH\fR
on the remote SSH host
\fIHOST\fR\&. 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\&.
.RE
.PP
"ssh\-exec:"\fIHOST\fR":"\fICOMMAND\fR
.RS 4
Invokes
\fICOMMAND\fR
(a command line, split on whitespace with shell\-style quoting and unescaping) on the remote SSH host
\fIHOST\fR
and speaks the Varlink protocol over its standard input and output\&.
.RE
.PP
If the scheme is none of the above but is otherwise a syntactically valid URL scheme,
\fBsd_varlink_connect_url()\fR
looks for a
\fIbridge helper\fR
binary of that name in the directory configured via
\fI$SYSTEMD_VARLINK_BRIDGES_DIR\fR
(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\&.
.PP
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\&.
.PP
\fBsd_varlink_connect_fd()\fR
turns an already existing, already connected file descriptor
\fIfd\fR
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\&.
.PP
\fBsd_varlink_connect_fd_pair()\fR
is like
\fBsd_varlink_connect_fd()\fR, but accepts a separate
\fIinput_fd\fR
(used for reading from the peer) and
\fIoutput_fd\fR
(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
\fBsd_varlink_connect_fd()\fR
does internally\&. If
\fIoverride_ucred\fR
is non\-\fBNULL\fR, the peer credentials reported for the connection (as returned e\&.g\&. by
\fBsd_varlink_get_peer_uid\fR(3)) are taken from the supplied
ucred
structure instead of being queried from the socket via
\fBSO_PEERCRED\fR\&. 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
\fIoverride_ucred\fR
is
\fBNULL\fR, peer credentials are determined from the socket as usual\&.
.PP
\fBsd_varlink_connect_fd()\fR
and
\fBsd_varlink_connect_fd_pair()\fR
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\&.
.PP
The connection objects created by
\fBsd_varlink_connect_exec()\fR, and by the
"exec:",
"ssh:"/"ssh\-unix:",
"ssh\-exec:"
and bridge\-helper paths of
\fBsd_varlink_connect_url()\fR, are bound to the lifetime of the spawned child process\&. When such a connection object is freed, the associated child process is sent
\fBSIGTERM\fR
and reaped\&. The child is also configured to receive
\fBSIGTERM\fR
if the calling process dies\&.
.SH "RETURN VALUE"
.PP
On success, these functions return a non\-negative integer and store a pointer to the new connection object in
\fIret\fR\&. On failure, they return a negative errno\-style error code and leave
\fIret\fR
unchanged\&.
.SS "Errors"
.PP
Returned errors may indicate the following problems:
.PP
\fB\-EINVAL\fR
.RS 4
A required argument is
\fBNULL\fR, 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 \(em for
\fBsd_varlink_connect_url()\fR
\(em file system paths that are not absolute or not normalized\&.
.RE
.PP
\fB\-EBADF\fR
.RS 4
For
\fBsd_varlink_connect_fd()\fR
and
\fBsd_varlink_connect_fd_pair()\fR: a supplied file descriptor is negative\&.
.RE
.PP
\fB\-EPROTONOSUPPORT\fR
.RS 4
For
\fBsd_varlink_connect_url()\fR: 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\&.
.RE
.PP
\fB\-ENOMEM\fR
.RS 4
Memory allocation failed\&.
.RE
.PP
In addition, these functions may propagate any error returned by the underlying system calls they use, such as
\fBsocket\fR(2),
\fBconnect\fR(2),
\fBfork\fR(2),
\fBpipe\fR(2)
and the various execution helpers\&.
.SH "NOTES"
.PP
Functions described here are available as a shared library, which can be compiled against and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.PP
The code described here uses
\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
\fBsetenv\fR(3)
from a parallel thread\&. It is recommended to only do calls to
\fBsetenv()\fR
from an early phase of the program when no other threads have been started\&.
.SH "ENVIRONMENT"
.PP
\fI$SYSTEMD_SSH\fR
.RS 4
Used by the
"ssh:"/"ssh\-unix:"
and
"ssh\-exec:"
transports of
\fBsd_varlink_connect_url()\fR
to override the
\fBssh\fR
binary to invoke\&. May be a plain file name (looked up in
\fI$PATH\fR) or an absolute path\&.
.sp
Added in version 257\&.
.RE
.PP
\fI$SYSTEMD_VARLINK_BRIDGES_DIR\fR
.RS 4
Overrides the directory in which
\fBsd_varlink_connect_url()\fR
looks up bridge helper binaries for non\-native URL schemes\&. Defaults to
/usr/lib/systemd/varlink\-bridges/\&.
.sp
Added in version 257\&.
.RE
.SH "FILES"
.PP
/usr/lib/systemd/varlink\-bridges/
.RS 4
Default directory searched for bridge helper binaries when
\fBsd_varlink_connect_url()\fR
encounters a URL with a scheme that is not natively supported\&. See
\fBsd-varlink\fR(3)
for details\&.
.RE
.SH "HISTORY"
.PP
\fBsd_varlink_connect_address()\fR,
\fBsd_varlink_connect_exec()\fR,
\fBsd_varlink_connect_url()\fR,
\fBsd_varlink_connect_fd()\fR
and
\fBsd_varlink_connect_fd_pair()\fR
were added in version 257\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsd-varlink\fR(3), \fBsd_varlink_attach_event\fR(3), \fBsd_varlink_call\fR(3), \fBsd_varlink_send\fR(3), \fBsd_varlink_is_connected\fR(3), \fBsd_listen_fds\fR(3), \fBvarlinkctl\fR(1)