SD_JSON_PARSE(3)

NAME
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

SYNOPSIS

#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);

DESCRIPTION

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.

RETURN VALUE

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.

NOTES

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.

HISTORY

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.

SEE ALSO

systemd(1), sd-json(3), sd_json_variant_unref(3), sd_json_variant_get_source(3), sd_json_dispatch(3)