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

The flags argument is a bitmask of zero or more of the following flags:

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.

See Also¶

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