Debian Codegraph @

upstream/debian-unstable/man3/sd-json.3

raw
1 '\" t
2 .TH "SD\-JSON" "3" "" "systemd 261~rc3" "sd-json"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd-json \- APIs for Dealing with JSON Objects
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-json\&.h>
29 .fi
30 .ft
31 .HP \w'\fBpkg\-config\ \-\-cflags\ \-\-libs\ libsystemd\fR\ 'u
32 \fBpkg\-config \-\-cflags \-\-libs libsystemd\fR
33 .SH "DESCRIPTION"
34 .PP
35 sd\-json\&.h
36 is part of
37 \fBlibsystemd\fR(3)
38 and provides APIs to parse, generate, format and otherwise operate with JSON objects\&.
39 .PP
40 The API\*(Aqs central data structure is
41 \fBJsonVariant\fR
42 which encapsulates a JSON object, array, string, boolean, number or null value\&. These data structures are mostly considered immutable after construction (i\&.e\&. their contents will not change, but some meta\-data might, such as reference counters)\&.
43 .PP
44 The APIs broadly fall into five categories:
45 .sp
46 .RS 4
47 .ie n \{\
48 \h'-04'\(bu\h'+03'\c
49 .\}
50 .el \{\
51 .sp -1
52 .IP \(bu 2.3
53 .\}
54 APIs to directly operate with
55 \fBJsonVariant\fR
56 objects, in the
57 \fBsd_json_variant*\fR
58 namespace\&.
59 .RE
60 .sp
61 .RS 4
62 .ie n \{\
63 \h'-04'\(bu\h'+03'\c
64 .\}
65 .el \{\
66 .sp -1
67 .IP \(bu 2.3
68 .\}
69 APIs to construct complex JSON objects, in the
70 \fBsd_json_build*\fR
71 namespace\&.
72 .RE
73 .sp
74 .RS 4
75 .ie n \{\
76 \h'-04'\(bu\h'+03'\c
77 .\}
78 .el \{\
79 .sp -1
80 .IP \(bu 2.3
81 .\}
82 APIs to map
83 \fBJsonVariant\fR
84 objects and their fields to matching fields in C structures, in the
85 \fBsd_json_dispatch*\fR
86 namespace\&.
87 .RE
88 .sp
89 .RS 4
90 .ie n \{\
91 \h'-04'\(bu\h'+03'\c
92 .\}
93 .el \{\
94 .sp -1
95 .IP \(bu 2.3
96 .\}
97 APIs to convert a string representation of a JSON object into a
98 \fBJsonVariant\fR
99 object, in the
100 \fBsd_json_parse*\fR
101 namespace\&.
102 .RE
103 .sp
104 .RS 4
105 .ie n \{\
106 \h'-04'\(bu\h'+03'\c
107 .\}
108 .el \{\
109 .sp -1
110 .IP \(bu 2.3
111 .\}
112 APIs to convert an
113 \fBJsonVariant\fR
114 object into its string representation, in the
115 \fBsd_json_format*\fR
116 namespace\&.
117 .RE
118 .PP
119 This JSON library will internally encode JSON integer numbers in the range
120 \fBINT64_MIN\fR\&...\fBUINT64_MAX\fR
121 into native 64bit signed or unsigned integers, and will reproduce them without loss of precision\&. Non\-integer numbers are stored in 64bit IEEE floating point numbers\&.
122 .PP
123 If the functions return string arrays, these are generally
124 \fBNULL\fR
125 terminated and need to be freed by the caller with the libc
126 \fBfree\fR(3)
127 call after use, including the strings referenced therein\&. Similarly, individual strings returned need to be freed, as well\&.
128 .PP
129 As a special exception, instead of an empty string array
130 \fBNULL\fR
131 may be returned, which should be treated equivalent to an empty string array\&.
132 .SH "NOTES"
133 .PP
134 Functions described here are available as a shared library, which can be compiled against and linked to with the
135 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
136 file\&.
137 .PP
138 The code described here uses
139 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
140 \fBsetenv\fR(3)
141 from a parallel thread\&. It is recommended to only do calls to
142 \fBsetenv()\fR
143 from an early phase of the program when no other threads have been started\&.
144 .SH "SEE ALSO"
145 .PP
146 \fBsystemd\fR(1), \fBsd-varlink\fR(3), \fBpkg-config\fR(1)