<refname>sd_journal_enumerate_data</refname>
<refname>sd_journal_restart_data</refname>
<refname>SD_JOURNAL_FOREACH_DATA</refname>
+ <refname>sd_journal_set_data_threshold</refname>
+ <refname>sd_journal_get_data_threshold</refname>
<refpurpose>Read data fields from the current journal entry</refpurpose>
</refnamediv>
</funcprototype>
<funcprototype>
- <funcdef>int <function>sd_journal_restart_data</function></funcdef>
+ <funcdef>void <function>sd_journal_restart_data</function></funcdef>
<paramdef>sd_journal* <parameter>j</parameter></paramdef>
</funcprototype>
<paramdef>size_t <parameter>length</parameter></paramdef>
</funcprototype>
+ <funcprototype>
+ <funcdef>int <function>sd_journal_set_data_threshold</function></funcdef>
+ <paramdef>sd_journal* <parameter>j</parameter></paramdef>
+ <paramdef>size_t <parameter>sz</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_journal_get_data_threshold</function></funcdef>
+ <paramdef>sd_journal* <parameter>j</parameter></paramdef>
+ <paramdef>size_t* <parameter>sz</parameter></paramdef>
+ </funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<function>sd_journal_enumerate_data()</function>, or
the read pointer is altered. Note that the data
returned will be prefixed with the field name and
- '='.</para>
+ '='. Also note that by default data fields larger than
+ 64K might get truncated to 64K. This threshold may be
+ changed and turned off with
+ <function>sd_journal_set_data_threshold()</function> (see
+ below).</para>
<para><function>sd_journal_enumerate_data()</function>
may be used to iterate through all fields of the
<para>Note that the
<function>SD_JOURNAL_FOREACH_DATA()</function> macro
- may be used as a wrapper around
+ may be used as a handy wrapper around
<function>sd_journal_restart_data()</function> and
<function>sd_journal_enumerate_data()</function>.</para>
<para>Note that these functions will not work before
<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
(or related call) has been called at least
- once.</para>
+ once, in order to position the read pointer at a valid entry.</para>
+
+ <para><function>sd_journal_set_data_threshold()</function>
+ may be used to change the data field size threshold
+ for data returned by
+ <function>sd_journal_get_data()</function>,
+ <function>sd_journal_enumerate_data()</function> and
+ <function>sd_journal_enumerate_unique()</function>. This
+ threshold is a hint only: it indicates that the client
+ program is interested only in the initial parts of the
+ data fields, up to the threshold in size -- but the
+ library might still return larger data objects. That
+ means applications should not rely exclusively on this
+ setting to limit the size of the data fields returned,
+ but need to apply a explicit size limit on the
+ returned data as well. This threshold defaults to 64K
+ by default. To retrieve the complete data fields this
+ threshold should be turned off by setting it to 0, so
+ that the library always returns the complete data
+ objects. It is recommended to set this threshold as
+ low as possible since this relieves the library from
+ having to decompress large compressed data objects in
+ full.</para>
+
+ <para><function>sd_journal_get_data_threshold()</function>
+ returns the currently configured data field size
+ threshold.</para>
</refsect1>
<refsect1>
<para><function>sd_journal_get_data()</function>
returns 0 on success or a negative errno-style error
code. If the current entry does not include the
- specified field -ENOENT is returned. If
+ specified field, -ENOENT is returned. If
<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- has not been called at least once -EADDRNOTAVAIL is
+ has not been called at least once, -EADDRNOTAVAIL is
returned. <function>sd_journal_enumerate_data()</function>
returns a positive integer if the next field has been
read, 0 when no more fields are known, or a negative
errno-style error
code. <function>sd_journal_restart_data()</function>
- returns nothing.</para>
+ returns
+ nothing. <function>sd_journal_set_data_threshold()</function>
+ and <function>sd_journal_get_threshold()</function>
+ return 0 on success or a negative errno-style error
+ code.</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>The <function>sd_journal_get_data()</function>,
- <function>sd_journal_enumerate_data()</function> and
- <function>sd_journal_restart_data()</function>
- interfaces are available as shared library, which can
+ <function>sd_journal_enumerate_data()</function>,
+ <function>sd_journal_restart_data()</function>,
+ <function>sd_journal_set_data_threshold()</function>
+ and
+ <function>sd_journal_get_data_threshold()</function>
+ interfaces are available as a shared library, which can
be compiled and linked to with the
- <literal>libsystemd-journal</literal>
- <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ <constant>libsystemd-journal</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff