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

sd_varlink_invoke_and_upgrade() is the asynchronous counterpart of sd_varlink_call_and_upgrade(), for connections attached to an event loop with sd_varlink_attach_event(3). It enqueues the method call with the upgrade request and returns immediately. Once the reply arrives it is passed to the reply callback installed with sd_varlink_bind_reply(3). If the server replied with a Varlink error, the connection stays in the Varlink protocol and may be used further. Otherwise the connection is upgraded on the next dispatch after the reply callback returned (i.e. the next invocation of sd_varlink_process(), typically by the event loop): it is detached from the event loop, disconnected from the Varlink protocol, and the underlying file descriptors are passed to the upgrade callback installed with sd_varlink_bind_upgrade(3), with the same semantics as the descriptors returned by sd_varlink_call_and_upgrade(). The callback takes ownership of both descriptors. Unlike with regular method calls, no further method calls may be enqueued on the connection while an upgrade request is pending, since the connection leaves the Varlink protocol once the request has been answered. sd_varlink_invoke_and_upgradeb() and sd_varlink_invoke_and_upgradebo() relate to sd_varlink_invoke_and_upgrade() like the …b() and …bo() variants described above.

Return Value¶

On success, sd_varlink_call_and_upgrade() and its variants return a positive integer if the connection was upgraded. If the server returns a Varlink error and ret_error_id was provided by the caller, it is set to the error identifier and zero is returned. Otherwise, the Varlink error is treated as a failure. sd_varlink_invoke_and_upgrade() and its variants return zero once the request has been enqueued. On failure, all functions return a negative errno-style error code.

Notes¶

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.

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.

sd_varlink_invoke_and_upgrade(), sd_varlink_invoke_and_upgradeb() and sd_varlink_invoke_and_upgradebo() were added in version 263.

See Also¶

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