|
HTML rendering created 2026-05-24 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_JSON_PARSE(3) sd_json_parse SD_JSON_PARSE(3)
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
#include <systemd/sd-json.h>
int sd_json_parse(const char *string, sd_json_parse_flags_t flags,
sd_json_variant **ret, unsigned *reterr_line,
unsigned *reterr_column);
int sd_json_parse_continue(const char **p,
sd_json_parse_flags_t flags,
sd_json_variant **ret,
unsigned *reterr_line,
unsigned *reterr_column);
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);
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);
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);
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);
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);
sd_json_parse() parses the JSON string in string and returns the
resulting JSON variant object in ret. 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.
If parsing fails, the reterr_line and reterr_column arguments are
set to the line and column (both one-based) where the parse error
occurred. One or both may be passed as NULL if the caller is not
interested in error location information. On success, the return
value is non-negative and ret is set to a newly allocated JSON
variant object (which must be freed with sd_json_variant_unref(3)
when no longer needed). ret may be passed as NULL, in which case
the input is validated but no object is returned.
sd_json_parse_continue() is similar, but is intended for parsing a
sequence of concatenated JSON values from a single input string.
Instead of taking a const char * string directly, it takes a
pointer to a const char * 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 sd_json_parse(), trailing
content after the first JSON value is not considered an error — it
is expected to be the beginning of the next value.
sd_json_parse_with_source() and
sd_json_parse_with_source_continue() are similar to
sd_json_parse() and sd_json_parse_continue(), respectively, but
take an additional source 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 sd_json_variant_get_source(3). If source is NULL, no
source information is attached. sd_json_parse() and
sd_json_parse_continue() are equivalent to calling their
_with_source counterparts with source set to NULL.
sd_json_parse_file() reads and parses a JSON value from a file. If
the f argument is non-NULL, the JSON text is read from the
specified FILE stream. If f is NULL, the file indicated by path is
opened and read instead. The path argument serves a dual purpose:
it is both used for opening the file (if f is NULL) and recorded
as source information in the resulting JSON variant (see above).
sd_json_parse_file_at() is similar to sd_json_parse_file(), but
takes an additional dir_fd argument which specifies a file
descriptor referring to the directory to resolve relative paths
specified in path against. If set to AT_FDCWD, relative paths are
resolved against the current working directory, which is the
default behaviour of sd_json_parse_file().
sd_json_parse_fd() reads and parses a JSON value from the file
referenced by the file descriptor fd. By default the file
descriptor is internally duplicated and the caller's 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's current file offset. This behaviour may be
modified via the SD_JSON_PARSE_SEEK0, SD_JSON_PARSE_DONATE_FD and
SD_JSON_PARSE_REOPEN_FD flags, see below. The path 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 NULL.
The flags argument is a bitmask of zero or more of the following
flags:
SD_JSON_PARSE_SENSITIVE
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 sd_json_variant_sensitive(3) for details.
SD_JSON_PARSE_MUST_BE_OBJECT
Requires that the top-level JSON value be a JSON object (i.e.
"{...}"). If the top-level value is an array, string, number,
boolean, or null, parsing fails with -EINVAL.
Added in version 261.
SD_JSON_PARSE_MUST_BE_ARRAY
Requires that the top-level JSON value be a JSON array (i.e.
"[...]"). If the top-level value is an object, string, number,
boolean, or null, parsing fails with -EINVAL.
Added in version 261.
SD_JSON_PARSE_SEEK0
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 SD_JSON_PARSE_REOPEN_FD in
sd_json_parse_fd() it is redundant, since a freshly reopened
file descriptor starts at offset 0 anyway.
Added in version 261.
SD_JSON_PARSE_DONATE_FD
Only has an effect on sd_json_parse_fd(). If set, ownership of
the file descriptor passed in fd 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 fd and the function
operates on an internally duplicated descriptor instead. This
flag may not be combined with SD_JSON_PARSE_REOPEN_FD.
Added in version 261.
SD_JSON_PARSE_REOPEN_FD
Only has an effect on sd_json_parse_fd(). If set, the file
descriptor passed in fd 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 O_PATH). The caller retains ownership of the
original descriptor, which is left untouched. This flag may
not be combined with SD_JSON_PARSE_DONATE_FD.
Added in version 261.
If both SD_JSON_PARSE_MUST_BE_OBJECT and
SD_JSON_PARSE_MUST_BE_ARRAY are set, both objects and arrays are
accepted, but non-container values (strings, numbers, booleans,
null) are still refused.
On success, these functions return 0. On failure, they return a
negative errno-style error code.
Errors
Returned errors may indicate the following problems:
-EINVAL
The input is not valid JSON, the input contains trailing
content after the parsed value (only for non-_continue
variants), or a top-level type constraint specified via
SD_JSON_PARSE_MUST_BE_OBJECT or SD_JSON_PARSE_MUST_BE_ARRAY
was violated.
-ENODATA
The input string is empty or NULL.
-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_json_parse(), sd_json_parse_continue(),
sd_json_parse_with_source(), sd_json_parse_with_source_continue(),
sd_json_parse_file(), and sd_json_parse_file_at() were added in
version 257.
sd_json_parse_fd() and the SD_JSON_PARSE_MUST_BE_OBJECT,
SD_JSON_PARSE_MUST_BE_ARRAY, SD_JSON_PARSE_SEEK0,
SD_JSON_PARSE_DONATE_FD and SD_JSON_PARSE_REOPEN_FD flags were
added in version 261.
systemd(1), sd-json(3), sd_json_variant_unref(3),
sd_json_variant_get_source(3), sd_json_dispatch(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-05-24. (At that
time, the date of the most recent commit that was found in the
repository was 2026-05-24.) 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 261~rc1 SD_JSON_PARSE(3)
Pages that refer to this page: systemd.directives(7), systemd.index(7)
|
HTML rendering created 2026-05-24 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. |
|