systemd sd_json_parse 3 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_unref3 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_source3. 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_sensitive3 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. 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. systemd1 sd-json3 sd_json_variant_unref3 sd_json_variant_get_source3 sd_json_dispatch3