sd_varlink_call_and_upgrade - Man Page

#include <systemd/sd-varlink​.h>

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, ​...);

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) 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)​. 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​.

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​.

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​.

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​.

systemd(1), sd-varlink(3), sd_varlink_call(3), sd_varlink_reply_and_upgrade(3), sd_json_build(3)

sd_varlink_reply_and_upgrade(3), systemd.directives(7), systemd.index(7).