SD\_VARLINK\_CALL\_AND\_UPGRADE(3) sd\_varlink\_call\_and\_upgrade SD\_VARLINK\_CALL\_AND\_UPGRADE(3) .SH "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 .SH "SYNOPSIS" ``` #include ``` .HP 768u **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);** .HP 792u **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, ...);** .HP 816u **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, ...);** .SH "DESCRIPTION" .PP 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)](/man/os/systemd/sd_varlink_reply_and_upgrade.3) 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. .PP **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. .PP 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)](/man/os/systemd/close.2). 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. .PP 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**. .PP **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)](/man/os/systemd/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)](/man/os/systemd/sd_json_buildo.3). This relationship mirrors that of [**sd\_varlink\_call**(3)](/man/os/systemd/sd_varlink_call.3) and its **sd\_varlink\_callb()**/**sd\_varlink\_callbo()** variants. .SH "RETURN VALUE" .PP 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. .SS "Errors" .PP Returned errors may indicate the following problems: .PP **-EINVAL** An argument is invalid. .RE .PP **-ENOTCONN** The Varlink connection object is not connected. .RE .PP **-EPROTO** A protocol error occurred, for example the server sent unexpected raw protocol data before the upgrade completed. .RE .PP **-ENOMEM** Memory allocation failed. .RE .SH "NOTES" .PP Functions described here are available as a shared library, which can be compiled against and linked to with the **libsystemd** [**pkg-config**(1)](/man/os/systemd/pkg-config.1) file. .PP The code described here uses [**getenv**(3)](/man/os/systemd/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)](/man/os/systemd/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. .SH "HISTORY" .PP **sd\_varlink\_call\_and\_upgrade()** was added in version 261. .PP **sd\_varlink\_call\_and\_upgradeb()** and **sd\_varlink\_call\_and\_upgradebo()** were added in version 262. .SH "SEE ALSO" .PP [**systemd**(1)](/man/os/systemd/systemd.1), [**sd-varlink**(3)](/man/os/systemd/sd-varlink.3), [**sd\_varlink\_call**(3)](/man/os/systemd/sd_varlink_call.3), [**sd\_varlink\_reply\_and\_upgrade**(3)](/man/os/systemd/sd_varlink_reply_and_upgrade.3), [**sd\_json\_build**(3)](/man/os/systemd/sd_json_build.3) systemd 262.2 --- Document: sd_varlink_call_and_upgrade(3) from systemd 262.2-r1 (Chainguard OS) Source: https://github.com/systemd/systemd