sd_json_parse - Man Page

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

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)