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.
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.
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.
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.
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.
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.
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.