1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"sd_journal_get_data" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
12 <title>sd_journal_get_data
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>sd_journal_get_data
</refentrytitle>
18 <manvolnum>3</manvolnum>
22 <refname>sd_journal_get_data
</refname>
23 <refname>sd_journal_enumerate_data
</refname>
24 <refname>sd_journal_restart_data
</refname>
25 <refname>SD_JOURNAL_FOREACH_DATA
</refname>
26 <refname>sd_journal_set_data_threshold
</refname>
27 <refname>sd_journal_get_data_threshold
</refname>
28 <refpurpose>Read data fields from the current journal entry
</refpurpose>
33 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
36 <funcdef>int
<function>sd_journal_get_data
</function></funcdef>
37 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
38 <paramdef>const char *
<parameter>field
</parameter></paramdef>
39 <paramdef>const void **
<parameter>data
</parameter></paramdef>
40 <paramdef>size_t *
<parameter>length
</parameter></paramdef>
44 <funcdef>int
<function>sd_journal_enumerate_data
</function></funcdef>
45 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
46 <paramdef>const void **
<parameter>data
</parameter></paramdef>
47 <paramdef>size_t *
<parameter>length
</parameter></paramdef>
51 <funcdef>void
<function>sd_journal_restart_data
</function></funcdef>
52 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
56 <funcdef><function>SD_JOURNAL_FOREACH_DATA
</function></funcdef>
57 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
58 <paramdef>const void *
<parameter>data
</parameter></paramdef>
59 <paramdef>size_t
<parameter>length
</parameter></paramdef>
63 <funcdef>int
<function>sd_journal_set_data_threshold
</function></funcdef>
64 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
65 <paramdef>size_t
<parameter>sz
</parameter></paramdef>
69 <funcdef>int
<function>sd_journal_get_data_threshold
</function></funcdef>
70 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
71 <paramdef>size_t *
<parameter>sz
</parameter></paramdef>
77 <title>Description
</title>
79 <para><function>sd_journal_get_data()
</function> gets the data
80 object associated with a specific field from the current journal
81 entry. It takes four arguments: the journal context object, a
82 string with the field name to request, plus a pair of pointers to
83 pointer/size variables where the data object and its size shall be
84 stored in. The field name should be an entry field name.
85 Well-known field names are listed in
86 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
87 The returned data is in a read-only memory map and is only valid
88 until the next invocation of
89 <function>sd_journal_get_data()
</function> or
90 <function>sd_journal_enumerate_data()
</function>, or the read
91 pointer is altered. Note that the data returned will be prefixed
92 with the field name and '='. Also note that, by default, data fields
93 larger than
64K might get truncated to
64K. This threshold may be
94 changed and turned off with
95 <function>sd_journal_set_data_threshold()
</function> (see
98 <para><function>sd_journal_enumerate_data()
</function> may be used
99 to iterate through all fields of the current entry. On each
100 invocation the data for the next field is returned. The order of
101 these fields is not defined. The data returned is in the same
102 format as with
<function>sd_journal_get_data()
</function> and also
103 follows the same life-time semantics.
</para>
105 <para><function>sd_journal_restart_data()
</function> resets the
106 data enumeration index to the beginning of the entry. The next
107 invocation of
<function>sd_journal_enumerate_data()
</function>
108 will return the first field of the entry again.
</para>
110 <para>Note that the
<function>SD_JOURNAL_FOREACH_DATA()
</function>
111 macro may be used as a handy wrapper around
112 <function>sd_journal_restart_data()
</function> and
113 <function>sd_journal_enumerate_data()
</function>.
</para>
115 <para>Note that these functions will not work before
116 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
117 (or related call) has been called at least once, in order to
118 position the read pointer at a valid entry.
</para>
120 <para><function>sd_journal_set_data_threshold()
</function> may be
121 used to change the data field size threshold for data returned by
122 <function>sd_journal_get_data()
</function>,
123 <function>sd_journal_enumerate_data()
</function> and
124 <function>sd_journal_enumerate_unique()
</function>. This threshold
125 is a hint only: it indicates that the client program is interested
126 only in the initial parts of the data fields, up to the threshold
127 in size — but the library might still return larger data objects.
128 That means applications should not rely exclusively on this
129 setting to limit the size of the data fields returned, but need to
130 apply an explicit size limit on the returned data as well. This
131 threshold defaults to
64K by default. To retrieve the complete
132 data fields this threshold should be turned off by setting it to
133 0, so that the library always returns the complete data objects.
134 It is recommended to set this threshold as low as possible since
135 this relieves the library from having to decompress large
136 compressed data objects in full.
</para>
138 <para><function>sd_journal_get_data_threshold()
</function> returns
139 the currently configured data field size threshold.
</para>
143 <title>Return Value
</title>
145 <para><function>sd_journal_get_data()
</function> returns
0 on
146 success or a negative errno-style error code. If the current entry
147 does not include the specified field, -ENOENT is returned. If
148 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
149 has not been called at least once, -EADDRNOTAVAIL is returned.
150 <function>sd_journal_enumerate_data()
</function> returns a
151 positive integer if the next field has been read,
0 when no more
152 fields are known, or a negative errno-style error code.
153 <function>sd_journal_restart_data()
</function> returns nothing.
154 <function>sd_journal_set_data_threshold()
</function> and
155 <function>sd_journal_get_threshold()
</function> return
0 on
156 success or a negative errno-style error code.
</para>
162 <xi:include href=
"threads-aware.xml" xpointer=
"strict"/>
164 <xi:include href=
"libsystemd-pkgconfig.xml" xpointer=
"pkgconfig-text"/>
168 <title>Examples
</title>
171 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
172 for a complete example how to use
173 <function>sd_journal_get_data()
</function>.
</para>
176 <function>SD_JOURNAL_FOREACH_DATA
</function> macro to
177 iterate through all fields of the current journal
181 int print_fields(sd_journal *j) {
184 SD_JOURNAL_FOREACH_DATA(j, data, length)
185 printf(
"%.*s\n", (int) length, data);
191 <title>See Also
</title>
194 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
195 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
196 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
197 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
198 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
199 <citerefentry><refentrytitle>sd_journal_get_realtime_usec
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
200 <citerefentry><refentrytitle>sd_journal_query_unique
</refentrytitle><manvolnum>3</manvolnum></citerefentry>