man/sd_journal_get_data.xml

   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">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_journal_get_data" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_journal_get_data</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>sd_journal_get_data</refentrytitle>
  18     <manvolnum>3</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  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>
  29   </refnamediv>
  30
  31   <refsynopsisdiv>
  32     <funcsynopsis>
  33       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  34
  35       <funcprototype>
  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>
  41       </funcprototype>
  42
  43       <funcprototype>
  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>
  48       </funcprototype>
  49
  50       <funcprototype>
  51         <funcdef>void <function>sd_journal_restart_data</function></funcdef>
  52         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  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>
  60       </funcprototype>
  61
  62       <funcprototype>
  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>
  66       </funcprototype>
  67
  68       <funcprototype>
  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>
  72       </funcprototype>
  73     </funcsynopsis>
  74   </refsynopsisdiv>
  75
  76   <refsect1>
  77     <title>Description</title>
  78
  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
  96     below).</para>
  97
  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>
 104
 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>
 109
 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>
 114
 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>
 119
 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>
 137
 138     <para><function>sd_journal_get_data_threshold()</function> returns
 139     the currently configured data field size threshold.</para>
 140   </refsect1>
 141
 142   <refsect1>
 143     <title>Return Value</title>
 144
 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>
 157   </refsect1>
 158
 159   <refsect1>
 160     <title>Notes</title>
 161
 162     <xi:include href="threads-aware.xml" xpointer="strict"/>
 163
 164     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 165   </refsect1>
 166
 167   <refsect1>
 168     <title>Examples</title>
 169
 170     <para>See
 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>
 174
 175     <para>Use the
 176     <function>SD_JOURNAL_FOREACH_DATA</function> macro to
 177     iterate through all fields of the current journal
 178     entry:</para>
 179
 180     <programlisting>…
 181 int print_fields(sd_journal *j) {
 182   const void *data;
 183   size_t length;
 184   SD_JOURNAL_FOREACH_DATA(j, data, length)
 185     printf("%.*s\n", (int) length, data);
 186 }
 187 …</programlisting>
 188   </refsect1>
 189
 190   <refsect1>
 191     <title>See Also</title>
 192
 193     <para>
 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>
 201     </para>
 202   </refsect1>
 203
 204 </refentry>