--- name: "sd_varlink_connect_address" section: "3" platform: "linux" package: "systemd-libs" version: "262.1-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/sd_varlink_connect_address" --- # sd\_varlink\_connect\_address(3) Create a Varlink connection object and connect it to a service ## 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 ``` ``` struct ucred; /* defined in */ ``` **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)](/sd-event/3.md) 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)](/execvp/3.md)). *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)](/sd_listen_fds/3.md) 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. ## 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. ### 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)](/socket/2.md), [**connect**(2)](/connect/2.md), [**fork**(2)](/fork/2.md), [**pipe**(2)](/pipe/2.md) and the various execution helpers. ## NOTES Functions described here are available as a shared library, which can be compiled against and linked to with the **libsystemd** [**pkg-config**(1)](/pkg-config/1.md) file. The code described here uses [**getenv**(3)](/getenv/3.md), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call [**setenv**(3)](/setenv/3.md) 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* 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. ## FILES /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)](/sd-varlink/3.md) for details. ## 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)](/systemd/1.md), [**sd-varlink**(3)](/sd-varlink/3.md), **sd\_varlink\_attach\_event**(3), **sd\_varlink\_call**(3), [**sd\_varlink\_send**(3)](/sd_varlink_send/3.md), [**sd\_varlink\_is\_connected**(3)](/sd_varlink_is_connected/3.md), [**sd\_listen\_fds**(3)](/sd_listen_fds/3.md), [**varlinkctl**(1)](/varlinkctl/1.md)