--- name: "sd_varlink_call_and_upgrade" 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_call_and_upgrade" --- # sd\_varlink\_call\_and\_upgrade(3) Invoke a Varlink method and take over the connection for a raw protocol ## NAME sd\_varlink\_call\_and\_upgrade, sd\_varlink\_call\_and\_upgradeb, sd\_varlink\_call\_and\_upgradebo - Invoke a Varlink method and take over the connection for a raw protocol ## SYNOPSIS ``` #include ``` **int sd\_varlink\_call\_and\_upgrade(sd\_varlink \****link***, const char \****method***, sd\_json\_variant \****parameters***, sd\_json\_variant \*\****ret\_parameters***, const char \*\****ret\_error\_id***, int \****ret\_input\_fd***, int \****ret\_output\_fd***);** **int sd\_varlink\_call\_and\_upgradeb(sd\_varlink \****link***, const char \****method***, sd\_json\_variant \*\****ret\_parameters***, const char \*\****ret\_error\_id***, int \****ret\_input\_fd***, int \****ret\_output\_fd***, ...);** **int sd\_varlink\_call\_and\_upgradebo(sd\_varlink \****link***, const char \****method***, sd\_json\_variant \*\****ret\_parameters***, const char \*\****ret\_error\_id***, int \****ret\_input\_fd***, int \****ret\_output\_fd***, ...);** ## DESCRIPTION These functions implement the client side of a Varlink *protocol upgrade*. They are the counterpart of the server-side [**sd\_varlink\_reply\_and\_upgrade**(3)](/sd_varlink_reply_and_upgrade/3.md) family. If a method call is issued this way, the connection may switch, after the reply, from the Varlink protocol to an arbitrary, non-Varlink ("raw") protocol spoken over the underlying socket or pipe file descriptors, in a manner similar to the "Upgrade:" mechanism of HTTP. **sd\_varlink\_call\_and\_upgrade()** synchronously invokes the method *method* on the connection *link*, requesting a protocol upgrade, and waits for the reply. It takes the Varlink connection object, the method name, a JSON object with the method call parameters (which may be **NULL**), two output pointers for the reply parameters and a possible error identifier, and two output pointers for the file descriptors. The reply parameters returned in *ret\_parameters* and the error identifier returned in *ret\_error\_id* are borrowed references that remain valid only until the connection is closed or unreffed. Either of the two may be passed as **NULL** if the information is not needed. If the server replies with a regular reply (rather than a Varlink error) the connection is upgraded: it is disconnected from the Varlink protocol, and ownership of the underlying file descriptors is transferred to the caller via *ret\_input\_fd* and *ret\_output\_fd*, which is responsible for eventually closing them with [**close**(2)](/close/2.md). If the server replies with a Varlink error instead, the connection is *not* upgraded and no file descriptors are returned; the error identifier is reported in *ret\_error\_id* (if non-**NULL**), otherwise a negative errno-style error derived from it is returned. The returned file descriptors are switched to blocking mode. For bidirectional sockets a single underlying file descriptor carries both directions; in this case *ret\_input\_fd* and *ret\_output\_fd* are returned as two independent (duplicated) descriptors referring to the same socket, so they may be closed separately. For transports backed by a pair of pipes the two descriptors differ and refer to the distinct read and write ends. At least one of *ret\_input\_fd* or *ret\_output\_fd* must be non-**NULL**. **sd\_varlink\_call\_and\_upgradeb()** is similar to **sd\_varlink\_call\_and\_upgrade()**, but instead of expecting a fully constructed **sd\_json\_variant** object carrying the method call parameters, this object is constructed on-the-fly from the variadic argument list, in a style identical to **sd\_json\_build**(3). **sd\_varlink\_call\_and\_upgradebo()** is identical to **sd\_varlink\_call\_and\_upgradeb()**, but an enclosing JSON object is added implicitly, so that the argument list is expected to consist of object field pairs only, in a style identical to **sd\_json\_buildo**(3). This relationship mirrors that of **sd\_varlink\_call**(3) and its **sd\_varlink\_callb()**/**sd\_varlink\_callbo()** variants. ## RETURN VALUE On success, these functions return a positive integer if the connection was upgraded, or zero if the server returned a Varlink error and *ret\_error\_id* was set to it. On failure, they return a negative errno-style error code. ### Errors Returned errors may indicate the following problems: **-EINVAL** An argument is invalid. **-ENOTCONN** The Varlink connection object is not connected. **-EPROTO** A protocol error occurred, for example the server sent unexpected raw protocol data before the upgrade completed. **-ENOMEM** Memory allocation failed. ## 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. ## HISTORY **sd\_varlink\_call\_and\_upgrade()** was added in version 261. **sd\_varlink\_call\_and\_upgradeb()** and **sd\_varlink\_call\_and\_upgradebo()** were added in version 262. ## SEE ALSO [**systemd**(1)](/systemd/1.md), [**sd-varlink**(3)](/sd-varlink/3.md), **sd\_varlink\_call**(3), [**sd\_varlink\_reply\_and\_upgrade**(3)](/sd_varlink_reply_and_upgrade/3.md), **sd\_json\_build**(3)