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

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

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.

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)