]>
Commit | Line | Data |
---|---|---|
4171a667 | 1 | <?xml version='1.0'?> <!--*-nxml-*--> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
12b42c76 | 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
0307f791 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1+ --> |
4171a667 | 5 | |
7d6b2723 | 6 | <refentry id="sd_journal_get_data" xmlns:xi="http://www.w3.org/2001/XInclude"> |
4171a667 | 7 | |
798d3a52 ZJS |
8 | <refentryinfo> |
9 | <title>sd_journal_get_data</title> | |
10 | <productname>systemd</productname> | |
798d3a52 ZJS |
11 | </refentryinfo> |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>sd_journal_get_data</refentrytitle> | |
15 | <manvolnum>3</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>sd_journal_get_data</refname> | |
20 | <refname>sd_journal_enumerate_data</refname> | |
0da322d9 | 21 | <refname>sd_journal_enumerate_available_data</refname> |
798d3a52 ZJS |
22 | <refname>sd_journal_restart_data</refname> |
23 | <refname>SD_JOURNAL_FOREACH_DATA</refname> | |
24 | <refname>sd_journal_set_data_threshold</refname> | |
25 | <refname>sd_journal_get_data_threshold</refname> | |
26 | <refpurpose>Read data fields from the current journal entry</refpurpose> | |
27 | </refnamediv> | |
28 | ||
29 | <refsynopsisdiv> | |
30 | <funcsynopsis> | |
31 | <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> | |
32 | ||
33 | <funcprototype> | |
34 | <funcdef>int <function>sd_journal_get_data</function></funcdef> | |
35 | <paramdef>sd_journal *<parameter>j</parameter></paramdef> | |
36 | <paramdef>const char *<parameter>field</parameter></paramdef> | |
37 | <paramdef>const void **<parameter>data</parameter></paramdef> | |
38 | <paramdef>size_t *<parameter>length</parameter></paramdef> | |
39 | </funcprototype> | |
40 | ||
41 | <funcprototype> | |
42 | <funcdef>int <function>sd_journal_enumerate_data</function></funcdef> | |
43 | <paramdef>sd_journal *<parameter>j</parameter></paramdef> | |
44 | <paramdef>const void **<parameter>data</parameter></paramdef> | |
45 | <paramdef>size_t *<parameter>length</parameter></paramdef> | |
46 | </funcprototype> | |
47 | ||
0da322d9 ZJS |
48 | <funcprototype> |
49 | <funcdef>int <function>sd_journal_enumerate_available_data</function></funcdef> | |
50 | <paramdef>sd_journal *<parameter>j</parameter></paramdef> | |
51 | <paramdef>const void **<parameter>data</parameter></paramdef> | |
52 | <paramdef>size_t *<parameter>length</parameter></paramdef> | |
53 | </funcprototype> | |
54 | ||
798d3a52 ZJS |
55 | <funcprototype> |
56 | <funcdef>void <function>sd_journal_restart_data</function></funcdef> | |
57 | <paramdef>sd_journal *<parameter>j</parameter></paramdef> | |
58 | </funcprototype> | |
59 | ||
60 | <funcprototype> | |
61 | <funcdef><function>SD_JOURNAL_FOREACH_DATA</function></funcdef> | |
62 | <paramdef>sd_journal *<parameter>j</parameter></paramdef> | |
63 | <paramdef>const void *<parameter>data</parameter></paramdef> | |
64 | <paramdef>size_t <parameter>length</parameter></paramdef> | |
65 | </funcprototype> | |
66 | ||
67 | <funcprototype> | |
68 | <funcdef>int <function>sd_journal_set_data_threshold</function></funcdef> | |
69 | <paramdef>sd_journal *<parameter>j</parameter></paramdef> | |
70 | <paramdef>size_t <parameter>sz</parameter></paramdef> | |
71 | </funcprototype> | |
72 | ||
73 | <funcprototype> | |
74 | <funcdef>int <function>sd_journal_get_data_threshold</function></funcdef> | |
75 | <paramdef>sd_journal *<parameter>j</parameter></paramdef> | |
76 | <paramdef>size_t *<parameter>sz</parameter></paramdef> | |
77 | </funcprototype> | |
78 | </funcsynopsis> | |
79 | </refsynopsisdiv> | |
80 | ||
81 | <refsect1> | |
82 | <title>Description</title> | |
83 | ||
0da322d9 ZJS |
84 | <para><function>sd_journal_get_data()</function> gets the data object associated with a specific field |
85 | from the current journal entry. It takes four arguments: the journal context object, a string with the | |
86 | field name to request, plus a pair of pointers to pointer/size variables where the data object and its | |
87 | size shall be stored in. The field name should be an entry field name. Well-known field names are listed in | |
88 | <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, | |
89 | but any field can be specified. The returned data is in a read-only memory map and is only valid until | |
90 | the next invocation of <function>sd_journal_get_data()</function>, | |
91 | <function>sd_journal_enumerate_data()</function>, | |
92 | <function>sd_journal_enumerate_available_data()</function>, or when the read pointer is altered. Note | |
93 | that the data returned will be prefixed with the field name and <literal>=</literal>. Also note that, by | |
94 | default, data fields larger than 64K might get truncated to 64K. This threshold may be changed and turned | |
95 | off with <function>sd_journal_set_data_threshold()</function> (see below).</para> | |
798d3a52 ZJS |
96 | |
97 | <para><function>sd_journal_enumerate_data()</function> may be used | |
98 | to iterate through all fields of the current entry. On each | |
99 | invocation the data for the next field is returned. The order of | |
100 | these fields is not defined. The data returned is in the same | |
101 | format as with <function>sd_journal_get_data()</function> and also | |
102 | follows the same life-time semantics.</para> | |
103 | ||
0da322d9 ZJS |
104 | <para><function>sd_journal_enumerate_available_data()</function> is similar to |
105 | <function>sd_journal_enumerate_data()</function>, but silently skips any fields which may be valid, but | |
106 | are too large or not supported by current implementation.</para> | |
107 | ||
798d3a52 ZJS |
108 | <para><function>sd_journal_restart_data()</function> resets the |
109 | data enumeration index to the beginning of the entry. The next | |
110 | invocation of <function>sd_journal_enumerate_data()</function> | |
111 | will return the first field of the entry again.</para> | |
112 | ||
0da322d9 ZJS |
113 | <para>Note that the <function>SD_JOURNAL_FOREACH_DATA()</function> macro may be used as a handy wrapper |
114 | around <function>sd_journal_restart_data()</function> and | |
115 | <function>sd_journal_enumerate_available_data()</function>.</para> | |
798d3a52 ZJS |
116 | |
117 | <para>Note that these functions will not work before | |
118 | <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
119 | (or related call) has been called at least once, in order to | |
120 | position the read pointer at a valid entry.</para> | |
121 | ||
122 | <para><function>sd_journal_set_data_threshold()</function> may be | |
123 | used to change the data field size threshold for data returned by | |
124 | <function>sd_journal_get_data()</function>, | |
125 | <function>sd_journal_enumerate_data()</function> and | |
126 | <function>sd_journal_enumerate_unique()</function>. This threshold | |
127 | is a hint only: it indicates that the client program is interested | |
128 | only in the initial parts of the data fields, up to the threshold | |
ccddd104 | 129 | in size — but the library might still return larger data objects. |
798d3a52 ZJS |
130 | That means applications should not rely exclusively on this |
131 | setting to limit the size of the data fields returned, but need to | |
037a3ded | 132 | apply an explicit size limit on the returned data as well. This |
798d3a52 ZJS |
133 | threshold defaults to 64K by default. To retrieve the complete |
134 | data fields this threshold should be turned off by setting it to | |
135 | 0, so that the library always returns the complete data objects. | |
136 | It is recommended to set this threshold as low as possible since | |
137 | this relieves the library from having to decompress large | |
138 | compressed data objects in full.</para> | |
139 | ||
140 | <para><function>sd_journal_get_data_threshold()</function> returns | |
141 | the currently configured data field size threshold.</para> | |
142 | </refsect1> | |
143 | ||
144 | <refsect1> | |
145 | <title>Return Value</title> | |
146 | ||
0da322d9 ZJS |
147 | <para><function>sd_journal_get_data()</function> returns 0 on success or a negative errno-style error |
148 | code. <function>sd_journal_enumerate_data()</function> and | |
149 | <function>sd_journal_enumerate_available_data()</function> return a positive integer if the next field | |
150 | has been read, 0 when no more fields remain, or a negative errno-style error code. | |
151 | <function>sd_journal_restart_data()</function> doesn't return anything. | |
152 | <function>sd_journal_set_data_threshold()</function> and <function>sd_journal_get_threshold()</function> | |
153 | return 0 on success or a negative errno-style error code.</para> | |
154 | ||
155 | <refsect2> | |
156 | <title>Errors</title> | |
157 | ||
158 | <para>Returned errors may indicate the following problems:</para> | |
159 | ||
160 | <variablelist> | |
161 | <varlistentry id='EINVAL'> | |
162 | <term><constant>-EINVAL</constant></term> | |
163 | ||
164 | <listitem><para>One of the required parameters is <constant>NULL</constant> or invalid. | |
165 | </para></listitem> | |
166 | </varlistentry> | |
167 | ||
168 | <varlistentry id='ECHILD'> | |
169 | <term><constant>-ECHILD</constant></term> | |
170 | ||
171 | <listitem><para>The journal object was created in a different process.</para></listitem> | |
172 | </varlistentry> | |
173 | ||
174 | <varlistentry id='EADDRNOTAVAIL'> | |
175 | <term><constant>-EADDRNOTAVAIL</constant></term> | |
176 | ||
177 | <listitem><para>The read pointer is not positioned at a valid entry; | |
178 | <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
179 | or a related call has not been called at least once.</para></listitem> | |
180 | </varlistentry> | |
181 | ||
182 | <varlistentry id='ENOENT'> | |
183 | <term><constant>-ENOENT</constant></term> | |
184 | ||
185 | <listitem><para>The current entry does not include the specified field.</para> | |
186 | </listitem> | |
187 | </varlistentry> | |
188 | ||
189 | <varlistentry id='ENOMEM'> | |
190 | <term><constant>-ENOMEM</constant></term> | |
191 | ||
192 | <listitem><para>Memory allocation failed.</para></listitem> | |
193 | </varlistentry> | |
194 | ||
195 | <varlistentry id='ENOBUFS'> | |
196 | <term><constant>-ENOBUFS</constant></term> | |
197 | ||
198 | <listitem><para>A compressed entry is too large.</para></listitem> | |
199 | </varlistentry> | |
200 | ||
201 | <varlistentry id='E2BIG'> | |
202 | <term><constant>-E2BIG</constant></term> | |
203 | ||
204 | <listitem><para>The data field is too large for this computer architecture (e.g. above 4 GB on a | |
205 | 32-bit architecture).</para></listitem> | |
206 | </varlistentry> | |
207 | ||
208 | <varlistentry id='EPROTONOSUPPORT'> | |
209 | <term><constant>-EPROTONOSUPPORT</constant></term> | |
210 | ||
211 | <listitem><para>The journal is compressed with an unsupported method or the journal uses an | |
212 | unsupported feature.</para></listitem> | |
213 | </varlistentry> | |
214 | ||
215 | <varlistentry id='EBADMSG'> | |
216 | <term><constant>-EBADMSG</constant></term> | |
217 | ||
218 | <listitem><para>The journal is corrupted (possibly just the entry being iterated over). | |
219 | </para></listitem> | |
220 | </varlistentry> | |
221 | ||
222 | <varlistentry id='EIO'> | |
223 | <term><constant>-EIO</constant></term> | |
224 | ||
225 | <listitem><para>An I/O error was reported by the kernel.</para></listitem> | |
226 | </varlistentry> | |
227 | </variablelist> | |
228 | </refsect2> | |
798d3a52 ZJS |
229 | </refsect1> |
230 | ||
64a7ef8b LP |
231 | <refsect1> |
232 | <title>Notes</title> | |
233 | ||
234 | <xi:include href="threads-aware.xml" xpointer="strict"/> | |
235 | ||
236 | <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> | |
237 | </refsect1> | |
798d3a52 ZJS |
238 | |
239 | <refsect1> | |
240 | <title>Examples</title> | |
241 | ||
242 | <para>See | |
243 | <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
244 | for a complete example how to use | |
245 | <function>sd_journal_get_data()</function>.</para> | |
246 | ||
247 | <para>Use the | |
248 | <function>SD_JOURNAL_FOREACH_DATA</function> macro to | |
249 | iterate through all fields of the current journal | |
250 | entry:</para> | |
251 | ||
1eecafb8 | 252 | <programlisting>… |
4171a667 | 253 | int print_fields(sd_journal *j) { |
798d3a52 ZJS |
254 | const void *data; |
255 | size_t length; | |
256 | SD_JOURNAL_FOREACH_DATA(j, data, length) | |
257 | printf("%.*s\n", (int) length, data); | |
4171a667 | 258 | } |
1eecafb8 | 259 | …</programlisting> |
798d3a52 ZJS |
260 | </refsect1> |
261 | ||
262 | <refsect1> | |
263 | <title>See Also</title> | |
264 | ||
265 | <para> | |
266 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
267 | <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, | |
268 | <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
269 | <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
270 | <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
271 | <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
272 | <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
273 | </para> | |
274 | </refsect1> | |
4171a667 LP |
275 | |
276 | </refentry> |