Debian Codegraph @

upstream/debian-unstable/man3/sd_json_parse.3

raw
1 '\" t
2 .TH "SD_JSON_PARSE" "3" "" "systemd 261~rc3" "sd_json_parse"
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_parse, sd_json_parse_continue, sd_json_parse_with_source, sd_json_parse_with_source_continue, sd_json_parse_file, sd_json_parse_file_at, sd_json_parse_fd, SD_JSON_PARSE_SENSITIVE, SD_JSON_PARSE_MUST_BE_OBJECT, SD_JSON_PARSE_MUST_BE_ARRAY, SD_JSON_PARSE_SEEK0, SD_JSON_PARSE_DONATE_FD, SD_JSON_PARSE_REOPEN_FD \- Parse JSON strings and files into JSON variant objects
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-json\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_json_parse('u
32 .BI "int sd_json_parse(const\ char\ *" "string" ", sd_json_parse_flags_t\ " "flags" ", sd_json_variant\ **" "ret" ", unsigned\ *" "reterr_line" ", unsigned\ *" "reterr_column" ");"
33 .HP \w'int\ sd_json_parse_continue('u
34 .BI "int sd_json_parse_continue(const\ char\ **" "p" ", sd_json_parse_flags_t\ " "flags" ", sd_json_variant\ **" "ret" ", unsigned\ *" "reterr_line" ", unsigned\ *" "reterr_column" ");"
35 .HP \w'int\ sd_json_parse_with_source('u
36 .BI "int sd_json_parse_with_source(const\ char\ *" "string" ", const\ char\ *" "source" ", sd_json_parse_flags_t\ " "flags" ", sd_json_variant\ **" "ret" ", unsigned\ *" "reterr_line" ", unsigned\ *" "reterr_column" ");"
37 .HP \w'int\ sd_json_parse_with_source_continue('u
38 .BI "int sd_json_parse_with_source_continue(const\ char\ **" "p" ", const\ char\ *" "source" ", sd_json_parse_flags_t\ " "flags" ", sd_json_variant\ **" "ret" ", unsigned\ *" "reterr_line" ", unsigned\ *" "reterr_column" ");"
39 .HP \w'int\ sd_json_parse_file('u
40 .BI "int sd_json_parse_file(FILE\ *" "f" ", const\ char\ *" "path" ", sd_json_parse_flags_t\ " "flags" ", sd_json_variant\ **" "ret" ", unsigned\ *" "reterr_line" ", unsigned\ *" "reterr_column" ");"
41 .HP \w'int\ sd_json_parse_file_at('u
42 .BI "int sd_json_parse_file_at(FILE\ *" "f" ", int\ " "dir_fd" ", const\ char\ *" "path" ", sd_json_parse_flags_t\ " "flags" ", sd_json_variant\ **" "ret" ", unsigned\ *" "reterr_line" ", unsigned\ *" "reterr_column" ");"
43 .HP \w'int\ sd_json_parse_fd('u
44 .BI "int sd_json_parse_fd(const\ char\ *" "path" ", int\ " "fd" ", sd_json_parse_flags_t\ " "flags" ", sd_json_variant\ **" "ret" ", unsigned\ *" "reterr_line" ", unsigned\ *" "reterr_column" ");"
45 .SH "DESCRIPTION"
46 .PP
47 \fBsd_json_parse()\fR
48 parses the JSON string in
49 \fIstring\fR
50 and returns the resulting JSON variant object in
51 \fIret\fR\&. The input must contain exactly one JSON value (object, array, string, number, boolean, or null); any trailing non\-whitespace content after the first parsed value is considered an error\&.
52 .PP
53 If parsing fails, the
54 \fIreterr_line\fR
55 and
56 \fIreterr_column\fR
57 arguments are set to the line and column (both one\-based) where the parse error occurred\&. One or both may be passed as
58 \fBNULL\fR
59 if the caller is not interested in error location information\&. On success, the return value is non\-negative and
60 \fIret\fR
61 is set to a newly allocated JSON variant object (which must be freed with
62 \fBsd_json_variant_unref\fR(3)
63 when no longer needed)\&.
64 \fIret\fR
65 may be passed as
66 \fBNULL\fR, in which case the input is validated but no object is returned\&.
67 .PP
68 \fBsd_json_parse_continue()\fR
69 is similar, but is intended for parsing a sequence of concatenated JSON values from a single input string\&. Instead of taking a
70 \fBconst char *\fR
71 string directly, it takes a pointer to a
72 \fBconst char *\fR
73 pointer\&. After each successful parse, the pointer is advanced past the consumed input, so that subsequent calls will parse the next JSON value\&. This is useful for parsing newline\-delimited JSON (NDJSON) streams or similar concatenated JSON formats\&. Unlike
74 \fBsd_json_parse()\fR, trailing content after the first JSON value is not considered an error \(em it is expected to be the beginning of the next value\&.
75 .PP
76 \fBsd_json_parse_with_source()\fR
77 and
78 \fBsd_json_parse_with_source_continue()\fR
79 are similar to
80 \fBsd_json_parse()\fR
81 and
82 \fBsd_json_parse_continue()\fR, respectively, but take an additional
83 \fIsource\fR
84 argument\&. This is a human\-readable string (typically a file name or other origin identifier) that is attached to the parsed JSON variant object and can later be retrieved via
85 \fBsd_json_variant_get_source\fR(3)\&. If
86 \fIsource\fR
87 is
88 \fBNULL\fR, no source information is attached\&.
89 \fBsd_json_parse()\fR
90 and
91 \fBsd_json_parse_continue()\fR
92 are equivalent to calling their
93 \fB_with_source\fR
94 counterparts with
95 \fIsource\fR
96 set to
97 \fBNULL\fR\&.
98 .PP
99 \fBsd_json_parse_file()\fR
100 reads and parses a JSON value from a file\&. If the
101 \fIf\fR
102 argument is non\-\fBNULL\fR, the JSON text is read from the specified
103 \fBFILE\fR
104 stream\&. If
105 \fIf\fR
106 is
107 \fBNULL\fR, the file indicated by
108 \fIpath\fR
109 is opened and read instead\&. The
110 \fIpath\fR
111 argument serves a dual purpose: it is both used for opening the file (if
112 \fIf\fR
113 is
114 \fBNULL\fR) and recorded as source information in the resulting JSON variant (see above)\&.
115 .PP
116 \fBsd_json_parse_file_at()\fR
117 is similar to
118 \fBsd_json_parse_file()\fR, but takes an additional
119 \fIdir_fd\fR
120 argument which specifies a file descriptor referring to the directory to resolve relative paths specified in
121 \fIpath\fR
122 against\&. If set to
123 \fBAT_FDCWD\fR, relative paths are resolved against the current working directory, which is the default behaviour of
124 \fBsd_json_parse_file()\fR\&.
125 .PP
126 \fBsd_json_parse_fd()\fR
127 reads and parses a JSON value from the file referenced by the file descriptor
128 \fIfd\fR\&. By default the file descriptor is internally duplicated and the caller\*(Aqs descriptor is left untouched (the current file offset will be shared with the original file descriptor however); the JSON text is read starting at the descriptor\*(Aqs current file offset\&. This behaviour may be modified via the
129 \fBSD_JSON_PARSE_SEEK0\fR,
130 \fBSD_JSON_PARSE_DONATE_FD\fR
131 and
132 \fBSD_JSON_PARSE_REOPEN_FD\fR
133 flags, see below\&. The
134 \fIpath\fR
135 argument is not used to open anything in this case; it is only recorded as source information in the resulting JSON variant (see above) and may be passed as
136 \fBNULL\fR\&.
137 .PP
138 The
139 \fIflags\fR
140 argument is a bitmask of zero or more of the following flags:
141 .PP
142 \fBSD_JSON_PARSE_SENSITIVE\fR
143 .RS 4
144 Marks the resulting JSON variant as "sensitive", indicating that it contains secret key material or similar confidential data\&. Sensitive variants are erased from memory when freed and are excluded from certain debug logging and introspection operations\&. See
145 \fBsd_json_variant_sensitive\fR(3)
146 for details\&.
147 .RE
148 .PP
149 \fBSD_JSON_PARSE_MUST_BE_OBJECT\fR
150 .RS 4
151 Requires that the top\-level JSON value be a JSON object (i\&.e\&.
152 "{\&...}")\&. If the top\-level value is an array, string, number, boolean, or null, parsing fails with
153 \fB\-EINVAL\fR\&.
154 .sp
155 Added in version 261\&.
156 .RE
157 .PP
158 \fBSD_JSON_PARSE_MUST_BE_ARRAY\fR
159 .RS 4
160 Requires that the top\-level JSON value be a JSON array (i\&.e\&.
161 "[\&...]")\&. If the top\-level value is an object, string, number, boolean, or null, parsing fails with
162 \fB\-EINVAL\fR\&.
163 .sp
164 Added in version 261\&.
165 .RE
166 .PP
167 \fBSD_JSON_PARSE_SEEK0\fR
168 .RS 4
169 Before reading, seek the input to its beginning (i\&.e\&. file offset 0)\&. This flag has no effect when parsing from a string\&. When used together with
170 \fBSD_JSON_PARSE_REOPEN_FD\fR
171 in
172 \fBsd_json_parse_fd()\fR
173 it is redundant, since a freshly reopened file descriptor starts at offset 0 anyway\&.
174 .sp
175 Added in version 261\&.
176 .RE
177 .PP
178 \fBSD_JSON_PARSE_DONATE_FD\fR
179 .RS 4
180 Only has an effect on
181 \fBsd_json_parse_fd()\fR\&. If set, ownership of the file descriptor passed in
182 \fIfd\fR
183 is transferred into the call: the descriptor is consumed and closed before the function returns, including in the error path\&. If not set (the default), the caller retains ownership of
184 \fIfd\fR
185 and the function operates on an internally duplicated descriptor instead\&. This flag may not be combined with
186 \fBSD_JSON_PARSE_REOPEN_FD\fR\&.
187 .sp
188 Added in version 261\&.
189 .RE
190 .PP
191 \fBSD_JSON_PARSE_REOPEN_FD\fR
192 .RS 4
193 Only has an effect on
194 \fBsd_json_parse_fd()\fR\&. If set, the file descriptor passed in
195 \fIfd\fR
196 is reopened (read\-only) before reading, instead of being duplicated\&. This is primarily useful to obtain an independent file offset (positioned at the beginning of the file) and a clean, read\-only access mode, even if the original descriptor was opened differently (for example with
197 \fBO_PATH\fR)\&. The caller retains ownership of the original descriptor, which is left untouched\&. This flag may not be combined with
198 \fBSD_JSON_PARSE_DONATE_FD\fR\&.
199 .sp
200 Added in version 261\&.
201 .RE
202 .PP
203 If both
204 \fBSD_JSON_PARSE_MUST_BE_OBJECT\fR
205 and
206 \fBSD_JSON_PARSE_MUST_BE_ARRAY\fR
207 are set, both objects and arrays are accepted, but non\-container values (strings, numbers, booleans, null) are still refused\&.
208 .SH "RETURN VALUE"
209 .PP
210 On success, these functions return 0\&. On failure, they return a negative errno\-style error code\&.
211 .SS "Errors"
212 .PP
213 Returned errors may indicate the following problems:
214 .PP
215 \fB\-EINVAL\fR
216 .RS 4
217 The input is not valid JSON, the input contains trailing content after the parsed value (only for non\-\fB_continue\fR
218 variants), or a top\-level type constraint specified via
219 \fBSD_JSON_PARSE_MUST_BE_OBJECT\fR
220 or
221 \fBSD_JSON_PARSE_MUST_BE_ARRAY\fR
222 was violated\&.
223 .RE
224 .PP
225 \fB\-ENODATA\fR
226 .RS 4
227 The input string is empty or
228 \fBNULL\fR\&.
229 .RE
230 .PP
231 \fB\-ENOMEM\fR
232 .RS 4
233 Memory allocation failed\&.
234 .RE
235 .SH "NOTES"
236 .PP
237 Functions described here are available as a shared library, which can be compiled against and linked to with the
238 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
239 file\&.
240 .PP
241 The code described here uses
242 \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
243 \fBsetenv\fR(3)
244 from a parallel thread\&. It is recommended to only do calls to
245 \fBsetenv()\fR
246 from an early phase of the program when no other threads have been started\&.
247 .SH "HISTORY"
248 .PP
249 \fBsd_json_parse()\fR,
250 \fBsd_json_parse_continue()\fR,
251 \fBsd_json_parse_with_source()\fR,
252 \fBsd_json_parse_with_source_continue()\fR,
253 \fBsd_json_parse_file()\fR, and
254 \fBsd_json_parse_file_at()\fR
255 were added in version 257\&.
256 .PP
257 \fBsd_json_parse_fd()\fR
258 and the
259 \fBSD_JSON_PARSE_MUST_BE_OBJECT\fR,
260 \fBSD_JSON_PARSE_MUST_BE_ARRAY\fR,
261 \fBSD_JSON_PARSE_SEEK0\fR,
262 \fBSD_JSON_PARSE_DONATE_FD\fR
263 and
264 \fBSD_JSON_PARSE_REOPEN_FD\fR
265 flags were added in version 261\&.
266 .SH "SEE ALSO"
267 .PP
268 \fBsystemd\fR(1), \fBsd-json\fR(3), \fBsd_json_variant_unref\fR(3), \fBsd_json_variant_get_source\fR(3), \fBsd_json_dispatch\fR(3)