systemd sd_varlink_call_and_upgrade 3 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 #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_upgrade3 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 close2. 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_build3. 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_buildo3. This relationship mirrors that of sd_varlink_call3 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. 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. 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. systemd1 sd-varlink3 sd_varlink_call3 sd_varlink_reply_and_upgrade3 sd_json_build3