|
HTML rendering created 2026-09-09 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | HISTORY | SEE ALSO | COLOPHON |
|
|
|
SD_VARL..._UPGRADE(3) sd_varlink_call_and_upgrade SD_VARL..._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_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.
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.
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)
This page is part of the systemd (systemd system and service
manager) project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a
bug report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
This page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2026-08-04. (At that
time, the date of the most recent commit that was found in the
repository was 2026-08-03.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
systemd 262~devel SD_VARL..._UPGRADE(3)
Pages that refer to this page: sd_varlink_reply_and_upgrade(3), systemd.directives(7), systemd.index(7)
|
HTML rendering created 2026-09-09 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|