Debian Codegraph @

upstream/debian-unstable/man3/sd_json_dispatch_string.3

raw
1 '\" t
2 .TH "SD_JSON_DISPATCH_STRING" "3" "" "systemd 261~rc3" "sd_json_dispatch_string"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_json_dispatch_string, sd_json_dispatch_const_string, sd_json_dispatch_strv, sd_json_dispatch_stdbool, sd_json_dispatch_intbool, sd_json_dispatch_tristate, sd_json_dispatch_variant, sd_json_dispatch_variant_noref, sd_json_dispatch_int64, sd_json_dispatch_int32, sd_json_dispatch_int16, sd_json_dispatch_int8, sd_json_dispatch_uint64, sd_json_dispatch_uint32, sd_json_dispatch_uint16, sd_json_dispatch_uint8, sd_json_dispatch_double, sd_json_dispatch_uid_gid, sd_json_dispatch_id128, sd_json_dispatch_signal, sd_json_dispatch_unsupported \- Decode JSON variant values and write them to the specified memory
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-varlink\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_json_dispatch_string('u
32 .BI "int sd_json_dispatch_string(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
33 .HP \w'int\ sd_json_dispatch_const_string('u
34 .BI "int sd_json_dispatch_const_string(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
35 .HP \w'int\ sd_json_dispatch_strv('u
36 .BI "int sd_json_dispatch_strv(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
37 .HP \w'int\ sd_json_dispatch_stdbool('u
38 .BI "int sd_json_dispatch_stdbool(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
39 .HP \w'int\ sd_json_dispatch_intbool('u
40 .BI "int sd_json_dispatch_intbool(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
41 .HP \w'int\ sd_json_dispatch_tristate('u
42 .BI "int sd_json_dispatch_tristate(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
43 .HP \w'int\ sd_json_dispatch_variant('u
44 .BI "int sd_json_dispatch_variant(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
45 .HP \w'int\ sd_json_dispatch_variant_noref('u
46 .BI "int sd_json_dispatch_variant_noref(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
47 .HP \w'int\ sd_json_dispatch_int64('u
48 .BI "int sd_json_dispatch_int64(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
49 .HP \w'int\ sd_json_dispatch_int32('u
50 .BI "int sd_json_dispatch_int32(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
51 .HP \w'int\ sd_json_dispatch_int16('u
52 .BI "int sd_json_dispatch_int16(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
53 .HP \w'int\ sd_json_dispatch_int8('u
54 .BI "int sd_json_dispatch_int8(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
55 .HP \w'int\ sd_json_dispatch_uint64('u
56 .BI "int sd_json_dispatch_uint64(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
57 .HP \w'int\ sd_json_dispatch_uint32('u
58 .BI "int sd_json_dispatch_uint32(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
59 .HP \w'int\ sd_json_dispatch_uint16('u
60 .BI "int sd_json_dispatch_uint16(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
61 .HP \w'int\ sd_json_dispatch_uint8('u
62 .BI "int sd_json_dispatch_uint8(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
63 .HP \w'int\ sd_json_dispatch_double('u
64 .BI "int sd_json_dispatch_double(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
65 .HP \w'int\ sd_json_dispatch_uid_gid('u
66 .BI "int sd_json_dispatch_uid_gid(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
67 .HP \w'int\ sd_json_dispatch_id128('u
68 .BI "int sd_json_dispatch_id128(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
69 .HP \w'int\ sd_json_dispatch_signal('u
70 .BI "int sd_json_dispatch_signal(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
71 .HP \w'int\ sd_json_dispatch_unsupported('u
72 .BI "int sd_json_dispatch_unsupported(const\ char\ *" "name" ", sd_json_variant\ *" "variant" ", sd_dispatch_flags\ " "flags" ", void\ *" "userdata" ");"
73 .SH "DESCRIPTION"
74 .PP
75 The various functions described here are intended for use in the
76 \fBsd_json_dispatch_field\fR
77 structure arrays the
78 \fBsd_json_dispatch\fR(3)
79 and
80 \fBsd_varlink_dispatch\fR(3)
81 functions accept; they decode the provided JSON variant object\*(Aqs value, and write it to the memory indicated by the
82 \fIuserdata\fR
83 pointer\&. The
84 \fIname\fR
85 parameter contains the field name (in the JSON object it is contained in) of the value being decoded\&. For details on the
86 \fIflags\fR
87 parameter see the
88 \fBsd_json_dispatch()\fR
89 documentation\&.
90 .PP
91 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)\&.
92 .PP
93 \fBsd_json_dispatch_string()\fR
94 decodes a JSON string value, and allocates a
95 \fBNUL\fR
96 terminated copy in dynamic memory\&. The
97 \fIuserdata\fR
98 pointer must point to a pointer to a string, which is freed if non\-\fBNULL\fR, and then replaced by the newly allocated one\&. If a JSON null value is passed, the existing string is freed and
99 \fBNULL\fR
100 is assigned\&.
101 .PP
102 \fBsd_json_dispatch_const_string()\fR
103 is very similar to
104 \fBsd_json_dispatch_string()\fR, but does not allocate a string in dynamic memory\&. Instead, it just writes a pointer into the JSON object into the indicated memory (or
105 \fBNULL\fR
106 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
107 \fIuserdata\fR
108 points to on input is
109 \fInot\fR
110 freed before the new value is assigned\&.
111 .PP
112 \fBsd_json_dispatch_stdbool()\fR
113 and
114 \fBsd_json_dispatch_intbool()\fR
115 decode JSON boolean values and write them to the indicated memory\&. The former expects a variable of the C99
116 \fBbool\fR
117 type in the indicated memory, the latter an
118 \fBint\fR
119 (which will only receive the values 0 and 1)\&. The JSON null value is treated equivalent to a JSON false\&.
120 .PP
121 \fBsd_json_dispatch_tristate()\fR
122 is very similar to\fBsd_json_dispatch_intbool()\fR, but will assign \-1 if a JSON null value is passed\&. Or in other words, the integer will have a value > 0, == 0 or < 0, for the cases true, false or invalid/unset/null\&.
123 .PP
124 \fBsd_json_dispatch_variant()\fR
125 takes an additional reference to the passed JSON object (via
126 \fBsd_json_variant_ref()\fR) and writes the pointer to the indicated memory\&. No decoding is done\&. If the indicated pointer is non\-\fBNULL\fR
127 on input it is freed (via
128 \fBsd_json_variant_unref()\fR) before the new pointer is written\&.
129 .PP
130 \fBsd_json_dispatch_variant_noref()\fR
131 is similar, but does
132 \fInot\fR
133 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\-\fBNULL\fR
134 on input it is
135 \fInot\fR
136 freed before the new pointer is written\&.
137 .PP
138 The
139 \fBsd_json_dispatch_int64()\fR,
140 \fBsd_json_dispatch_int32()\fR,
141 \fBsd_json_dispatch_int16()\fR,
142 \fBsd_json_dispatch_int8()\fR,
143 \fBsd_json_dispatch_uint64()\fR,
144 \fBsd_json_dispatch_uint32()\fR,
145 \fBsd_json_dispatch_uint16()\fR
146 and
147 \fBsd_json_dispatch_uint8()\fR
148 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\&.
149 \fBUINT64_MAX\fR,
150 \fBUINT32_MAX\fR
151 \&...), 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\&.
152 .PP
153 The
154 \fBsd_json_dispatch_double()\fR
155 function decodes a 64bit double precision floating point number\&. If a JSON null value is passed, assigns NaN\&.
156 .PP
157 The
158 \fBsd_json_dispatch_uid_gid()\fR
159 function is similar to
160 \fBsd_json_dispatch_uint32()\fR, 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\&.
161 "(uid_t) \-1"), 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)\&.
162 .PP
163 \fBsd_json_dispatch_id128()\fR
164 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
165 \fBsd_id128_from_string\fR(3)\&. If the JSON null value is passed, the all\-zero ID is assigned\&.
166 .PP
167 \fBsd_json_dispatch_signal()\fR
168 decodes a UNIX process signal specification\&. It expects either an JSON string containing a signal name such as
169 "SIGINT"
170 or
171 "SIGTERM", or an unsigned JSON integer value with the signal number (in the Linux definition)\&. The indicated memory must point to an
172 \fBint\fR
173 variable to write the signal number to\&. If the JSON null value is passed a negative value will be written to the memory\&.
174 .PP
175 \fBsd_json_dispatch_unsupported()\fR
176 will always fail with the \-\fBEINVAL\fR
177 error\&.
178 .SH "RETURN VALUE"
179 .PP
180 On success, these functions return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
181 .SS "Errors"
182 .PP
183 Returned errors may indicate the following problems:
184 .PP
185 \fB\-EINVAL\fR
186 .RS 4
187 An argument is invalid\&.
188 .RE
189 .PP
190 \fB\-ENOMEM\fR
191 .RS 4
192 Memory allocation failed\&.
193 .RE
194 .SH "NOTES"
195 .PP
196 Functions described here are available as a shared library, which can be compiled against and linked to with the
197 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
198 file\&.
199 .PP
200 The code described here uses
201 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
202 \fBsetenv\fR(3)
203 from a parallel thread\&. It is recommended to only do calls to
204 \fBsetenv()\fR
205 from an early phase of the program when no other threads have been started\&.
206 .SH "HISTORY"
207 .PP
208 \fBsd_json_dispatch_string()\fR,
209 \fBsd_json_dispatch_const_string()\fR,
210 \fBsd_json_dispatch_strv()\fR,
211 \fBsd_json_dispatch_stdbool()\fR,
212 \fBsd_json_dispatch_intbool()\fR,
213 \fBsd_json_dispatch_tristate()\fR,
214 \fBsd_json_dispatch_variant()\fR,
215 \fBsd_json_dispatch_variant_noref()\fR,
216 \fBsd_json_dispatch_int64()\fR,
217 \fBsd_json_dispatch_int32()\fR,
218 \fBsd_json_dispatch_int16()\fR,
219 \fBsd_json_dispatch_int8()\fR,
220 \fBsd_json_dispatch_uint64()\fR,
221 \fBsd_json_dispatch_uint32()\fR,
222 \fBsd_json_dispatch_uint16()\fR,
223 \fBsd_json_dispatch_uint8()\fR,
224 \fBsd_json_dispatch_double()\fR,
225 \fBsd_json_dispatch_uid_gid()\fR,
226 \fBsd_json_dispatch_id128()\fR,
227 \fBsd_json_dispatch_signal()\fR,
228 \fBsd_json_dispatch_unsupported()\fR
229 were added in version 257\&.
230 .SH "SEE ALSO"
231 .PP
232 \fBsystemd\fR(1), \fBsd-json\fR(3), \fBsd-varlink\fR(3), \fBsd_json_dispatch\fR(3), \fBsd_variant_dispatch\fR(3)