morgan/systemd
1
0
Fork 0
mirror of https://github.com/morgan9e/systemd synced 2026-04-14 00:14:32 +09:00
Code Issues Packages Projects Releases Wiki Activity

man: add documentation for the various sd_json_dispatch_xyz() calls

Browse Source 
Now that we comprehensively return accept null it's a good idea to
document which function maps null to what.
This commit is contained in:
Lennart Poettering
2025-10-24 10:22:36 +02:00
parent 93317e9c17
commit 633a4b8839
2 changed files with 387 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
man/rules/meson.build
View File

@@ -828,6 +828,29 @@ manpages = [
'sd_journal_seek_tail'],
''],
['sd_journal_stream_fd', '3', ['sd_journal_stream_fd_with_namespace'], ''],
['sd_json_dispatch_string',
'3',
['sd_json_dispatch_const_string',
'sd_json_dispatch_double',
'sd_json_dispatch_id128',
'sd_json_dispatch_int16',
'sd_json_dispatch_int32',
'sd_json_dispatch_int64',
'sd_json_dispatch_int8',
'sd_json_dispatch_intbool',
'sd_json_dispatch_signal',
'sd_json_dispatch_stdbool',
'sd_json_dispatch_strv',
'sd_json_dispatch_tristate',
'sd_json_dispatch_uid_gid',
'sd_json_dispatch_uint16',
'sd_json_dispatch_uint32',
'sd_json_dispatch_uint64',
'sd_json_dispatch_uint8',
'sd_json_dispatch_unsupported',
'sd_json_dispatch_variant',
'sd_json_dispatch_variant_noref'],
''],
['sd_listen_fds',
'3',
['SD_LISTEN_FDS_START', 'sd_listen_fds_with_names'],

364
man/sd_json_dispatch_string.xml Normal file
View File

@@ -0,0 +1,364 @@
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="sd_json_dispatch_string" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_json_dispatch_string</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_json_dispatch_string</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_json_dispatch_string</refname>
<refname>sd_json_dispatch_const_string</refname>
<refname>sd_json_dispatch_strv</refname>
<refname>sd_json_dispatch_stdbool</refname>
<refname>sd_json_dispatch_intbool</refname>
<refname>sd_json_dispatch_tristate</refname>
<refname>sd_json_dispatch_variant</refname>
<refname>sd_json_dispatch_variant_noref</refname>
<refname>sd_json_dispatch_int64</refname>
<refname>sd_json_dispatch_int32</refname>
<refname>sd_json_dispatch_int16</refname>
<refname>sd_json_dispatch_int8</refname>
<refname>sd_json_dispatch_uint64</refname>
<refname>sd_json_dispatch_uint32</refname>
<refname>sd_json_dispatch_uint16</refname>
<refname>sd_json_dispatch_uint8</refname>
<refname>sd_json_dispatch_double</refname>
<refname>sd_json_dispatch_uid_gid</refname>
<refname>sd_json_dispatch_id128</refname>
<refname>sd_json_dispatch_signal</refname>
<refname>sd_json_dispatch_unsupported</refname>
<refpurpose>Decode JSON variant values and write them to the specified memory</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-varlink.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_string</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_const_string</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_strv</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_stdbool</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_intbool</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_tristate</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_variant</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_variant_noref</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_int64</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_int32</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_int16</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_int8</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_uint64</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_uint32</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_uint16</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_uint8</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_double</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_uid_gid</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_id128</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_signal</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_json_dispatch_unsupported</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_json_variant *<parameter>variant</parameter></paramdef>
<paramdef>sd_dispatch_flags <parameter>flags</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>The various functions described here are intended for use in the
<type>sd_json_dispatch_field</type> structure arrays the
<citerefentry><refentrytitle>sd_json_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
<citerefentry><refentrytitle>sd_varlink_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>
functions accept; they decode the provided JSON variant object's value, and write it to the memory
indicated by the <parameter>userdata</parameter> pointer. The <parameter>name</parameter> parameter
contains the field name (in the JSON object it is contained in) of the value being decoded. For details
on the <parameter>flags</parameter> parameter see the <function>sd_json_dispatch()</function>
documentation.</para>
<para>Note that all these functions not only accept the native JSON type they are intended for, but also
accept null JSON values, in which case they assign an appropriate invalid/unset/null value, as
appropriate for the type (for details see below).</para>
<para><function>sd_json_dispatch_string()</function> decodes a JSON string value, and allocates a
<constant>NUL</constant> terminated copy in dynamic memory. The <parameter>userdata</parameter> pointer
must point to a pointer to a string, which is freed if non-<constant>NULL</constant>, and then replaced
by the newly allocated one. If a JSON null value is passed, the existing string is freed and
<constant>NULL</constant> is assigned.</para>
<para><function>sd_json_dispatch_const_string()</function> is very similar to
<function>sd_json_dispatch_string()</function>, but does not allocate a string in dynamic
memory. Instead, it just writes a pointer into the JSON object into the indicated memory (or
<constant>NULL</constant> in case a JSON null object is passed). The memory remains valid only as long as
the indicated variant object is kept allocated (which can happen via direct reference, or via an indirect
one via an object that references the specified variant). The memory <parameter>userdata</parameter>
points to on input is <emphasis>not</emphasis> freed before the new value is assigned.</para>
<para><function>sd_json_dispatch_stdbool()</function> and <function>sd_json_dispatch_intbool()</function>
decode JSON boolean values and write them to the indicated memory. The former expects a variable of the
C99 <type>bool</type> type in the indicated memory, the latter an <type>int</type> (which will only
receive the values 0 and 1). The JSON null value is treated equivalent to a JSON false.</para>
<para><function>sd_json_dispatch_tristate()</function> is very similar
to<function>sd_json_dispatch_intbool()</function>, but will assign -1 if a JSON null value is passed. Or
in other words, the integer will have a value &gt; 0, == 0 or &lt; 0, for the cases true, false or
invalid/unset/null.</para>
<para><function>sd_json_dispatch_variant()</function> takes an additional reference to the passed JSON
object (via <function>sd_json_variant_ref()</function>) and writes the pointer to the indicated
memory. No decoding is done. If the indicated pointer is non-<constant>NULL</constant> on input it is
freed (via <function>sd_json_variant_unref()</function>) before the new pointer is written.</para>
<para><function>sd_json_dispatch_variant_noref()</function> is similar, but does <emphasis>not</emphasis>
take a new reference to the JSON variant object. The pointer hence only remains valid as long as the
original object stays referenced. If the indicated pointer is non-<constant>NULL</constant> on input it
is <emphasis>not</emphasis> freed before the new pointer is written.</para>
<para>The <function>sd_json_dispatch_int64()</function>, <function>sd_json_dispatch_int32()</function>,
<function>sd_json_dispatch_int16()</function>, <function>sd_json_dispatch_int8()</function>,
<function>sd_json_dispatch_uint64()</function>, <function>sd_json_dispatch_uint32()</function>,
<function>sd_json_dispatch_uint16()</function> and <function>sd_json_dispatch_uint8()</function>
functions decode a JSON integer value, and write the value to the indicated memory. The function names
indicate the word width and signedness of the integers being parsed. If the JSON null value is passed the
functions for the unsigned integer types will assign the maximum value the type takes
(i.e. <constant>UINT64_MAX</constant>, <constant>UINT32_MAX</constant> …), and the signed versions assign
-1. Instead of a JSON integer value these functions also accept JSON strings that contain formatted
decimal numbers, in order to improve compatibility for encoding integer values that cannot be represented
in 64bit double precision floating point numbers in other programming languages that encode JSON numerals
this way.</para>
<para>The <function>sd_json_dispatch_double()</function> function decodes a 64bit double precision
floating point number. If a JSON null value is passed, assigns NaN.</para>
<para>The <function>sd_json_dispatch_uid_gid()</function> function is similar to
<function>sd_json_dispatch_uint32()</function>, and is intended to decode 32bit UNIX UID/GID numbers, as
used on Linux. It will decode a JSON null value as 4294967295 (i.e. <literal>(uid_t) -1</literal>), and
will refuse the values 65535 and 4294967295 when passed as JSON numerals (i.e. both the 16bit and 32bit
"invalid" UID/GID, as these values have special meaning for various UNIX syscalls, on different OSes and
file systems).</para>
<para><function>sd_json_dispatch_id128()</function> decodes a 128bit ID formatted as a JSON string. It
supports both RFC9562 UUID formatting, as well as 64 hexadecimal characters without separators, the same
way as
<citerefentry><refentrytitle>sd_id128_from_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
the JSON null value is passed, the all-zero ID is assigned.</para>
<para><function>sd_json_dispatch_signal()</function> decodes a UNIX process signal specification. It
expects either an JSON string containing a signal name such as <literal>SIGINT</literal> or
<literal>SIGTERM</literal>, or an unsigned JSON integer value with the signal number (in the Linux
definition). The indicated memory must point to an <type>int</type> variable to write the signal number
to. If the JSON null value is passed a negative value will be written to the memory.</para>
<para><function>sd_json_dispatch_unsupported()</function> will always fail with the
-<constant>EINVAL</constant> error.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these functions return a non-negative integer. On failure, they return a negative
errno-style error code.</para>
<refsect2>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>An argument is invalid.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Memory allocation failed.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>History</title>
<para>
<function>sd_json_dispatch_string()</function>, <function>sd_json_dispatch_const_string()</function>,
<function>sd_json_dispatch_strv()</function>, <function>sd_json_dispatch_stdbool()</function>,
<function>sd_json_dispatch_intbool()</function>, <function>sd_json_dispatch_tristate()</function>,
<function>sd_json_dispatch_variant()</function>, <function>sd_json_dispatch_variant_noref()</function>,
<function>sd_json_dispatch_int64()</function>, <function>sd_json_dispatch_int32()</function>,
<function>sd_json_dispatch_int16()</function>, <function>sd_json_dispatch_int8()</function>,
<function>sd_json_dispatch_uint64()</function>, <function>sd_json_dispatch_uint32()</function>,
<function>sd_json_dispatch_uint16()</function>, <function>sd_json_dispatch_uint8()</function>,
<function>sd_json_dispatch_double()</function>, <function>sd_json_dispatch_uid_gid()</function>,
<function>sd_json_dispatch_id128()</function>, <function>sd_json_dispatch_signal()</function>,
<function>sd_json_dispatch_unsupported()</function> were added in version 257.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd-json</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd-varlink</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_json_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_variant_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>