From: Lennart Poettering Date: Tue, 29 Apr 2025 08:41:14 +0000 (+0200) Subject: man: document sd_varlink_send() X-Git-Tag: v258-rc1~717^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5b5c6826ba8f6a64832a5a0b101541fbb68b9645;p=thirdparty%2Fsystemd.git man: document sd_varlink_send() --- diff --git a/man/rules/meson.build b/man/rules/meson.build index 203231534d3..433fffc5719 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -890,6 +890,7 @@ manpages = [ 'sd_uid_is_on_seat'], 'HAVE_PAM'], ['sd_varlink_push_fd', '3', ['sd_varlink_push_dup_fd'], ''], + ['sd_varlink_send', '3', ['sd_varlink_sendb', 'sd_varlink_sendbo'], ''], ['sd_varlink_set_description', '3', ['sd_varlink_get_description'], ''], ['sd_watchdog_enabled', '3', [], ''], ['shutdown', '8', [], ''], diff --git a/man/sd_varlink_send.xml b/man/sd_varlink_send.xml new file mode 100644 index 00000000000..2c6b998ccf2 --- /dev/null +++ b/man/sd_varlink_send.xml @@ -0,0 +1,151 @@ + + + + + + + + sd_varlink_send + systemd + + + + sd_varlink_send + 3 + + + + sd_varlink_send + sd_varlink_sendb + sd_varlink_sendbo + + Enqueues a Varlink method call, not expecting a reply + + + + + #include <systemd/sd-varlink.h> + + + int sd_varlink_send + sd_varlink *link + const char *method + sd_json_variant *parameters + + + + int sd_varlink_sendb + sd_varlink *link + const char *method + … + + + + int sd_varlink_sendbo + sd_varlink *link + const char *method + … + + + + + + Description + + sd_varlink_send() submits a method call via a Varlink connection. It takes the + Varlink connection object, a method name as string parameter, and a JSON object containing the parameters + to pass as function parameters. This call is asynchronous: the message will not be delivered immediately + but only once + sd_varlink_process3 is + invoked (which will happen automatically in one of the following event loop iterations if the Varlink + connection is attached to an even loop). + + sd_varlink_sendb() is similar to sd_varlink_send(), but + instead of expecting a fully constructed sd_json_variant object carrying the parameters, + this object is constructed on-the-fly directly from the parameter list, in a style identical to + sd_json_build3. + + sd_varlink_sendbo() is identical to sd_varlink_sendb(), + but an enclosing object is implicitly added, so that the parameter list is expected to consist of field + pairs only. For details about the expected argument list, see + sd_json_buildo3. + + Use sd_varlink_send(), sd_varlink_sendb() and + sd_varlink_sendbo() only if no method call results are required, as they neither + provide return parameters nor success/failure information. Use + sd_varlink_call3 (and + related calls) to submit a method call synchronously, returning the server's response. + + + + Return Value + + On success, sd_varlink_send(), sd_varlink_sendb() and + sd_varlink_sendbo() return a non-negative integer. On failure, they return a + negative errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + An argument is invalid. + + + + -ENOMEM + + Memory allocation failed. + + + + -ENOTCONN + + The Varlink connection object is not connected. + + + + -EBUSY + + The Varlink connection object is already used for other purposes, i.e. executing a + method call or similar. + + + + -ENOBUFS + + The internal limit of queued messages for the Varlink connection has been + reached. This limit is set very high, and hitting it typically indicates that the Varlink + connection object is stalled — possibly because sd_varlink_process() has not + been called regularly enough, or because the peer is not processing any queued messages. This limit + is a safety precaution to ensure a stalled peer will not result in unbounded memory allocations on + the client side. + + + + + + + + + History + sd_varlink_send(), sd_varlink_sendb(), + sd_varlink_sendbo() were added in version 257. + + + + See Also + + + systemd1 + sd-varlink3 + sd_varlink_call3 + sd_varlink_build3 + + +