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
  15     <authorgroup>
  16       <author>
  17         <contrib>Developer</contrib>
  18         <firstname>Lennart</firstname>
  19         <surname>Poettering</surname>
  20         <email>lennart@poettering.net</email>
  21       </author>
  22     </authorgroup>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle>sd_journal_get_data</refentrytitle>
  27     <manvolnum>3</manvolnum>
  28   </refmeta>
  29
  30   <refnamediv>
  31     <refname>sd_journal_get_data</refname>
  32     <refname>sd_journal_enumerate_data</refname>
  33     <refname>sd_journal_restart_data</refname>
  34     <refname>SD_JOURNAL_FOREACH_DATA</refname>
  35     <refname>sd_journal_set_data_threshold</refname>
  36     <refname>sd_journal_get_data_threshold</refname>
  37     <refpurpose>Read data fields from the current journal entry</refpurpose>
  38   </refnamediv>
  39
  40   <refsynopsisdiv>
  41     <funcsynopsis>
  42       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_journal_get_data</function></funcdef>
  46         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  47         <paramdef>const char *<parameter>field</parameter></paramdef>
  48         <paramdef>const void **<parameter>data</parameter></paramdef>
  49         <paramdef>size_t *<parameter>length</parameter></paramdef>
  50       </funcprototype>
  51
  52       <funcprototype>
  53         <funcdef>int <function>sd_journal_enumerate_data</function></funcdef>
  54         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  55         <paramdef>const void **<parameter>data</parameter></paramdef>
  56         <paramdef>size_t *<parameter>length</parameter></paramdef>
  57       </funcprototype>
  58
  59       <funcprototype>
  60         <funcdef>void <function>sd_journal_restart_data</function></funcdef>
  61         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef><function>SD_JOURNAL_FOREACH_DATA</function></funcdef>
  66         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  67         <paramdef>const void *<parameter>data</parameter></paramdef>
  68         <paramdef>size_t <parameter>length</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>int <function>sd_journal_set_data_threshold</function></funcdef>
  73         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  74         <paramdef>size_t <parameter>sz</parameter></paramdef>
  75       </funcprototype>
  76
  77       <funcprototype>
  78         <funcdef>int <function>sd_journal_get_data_threshold</function></funcdef>
  79         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  80         <paramdef>size_t *<parameter>sz</parameter></paramdef>
  81       </funcprototype>
  82     </funcsynopsis>
  83   </refsynopsisdiv>
  84
  85   <refsect1>
  86     <title>Description</title>
  87
  88     <para><function>sd_journal_get_data()</function> gets the data
  89     object associated with a specific field from the current journal
  90     entry. It takes four arguments: the journal context object, a
  91     string with the field name to request, plus a pair of pointers to
  92     pointer/size variables where the data object and its size shall be
  93     stored in. The field name should be an entry field name.
  94     Well-known field names are listed in
  95     <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
  96     The returned data is in a read-only memory map and is only valid
  97     until the next invocation of
  98     <function>sd_journal_get_data()</function> or
  99     <function>sd_journal_enumerate_data()</function>, or the read
 100     pointer is altered. Note that the data returned will be prefixed
 101     with the field name and '='. Also note that, by default, data fields
 102     larger than 64K might get truncated to 64K. This threshold may be
 103     changed and turned off with
 104     <function>sd_journal_set_data_threshold()</function> (see
 105     below).</para>
 106
 107     <para><function>sd_journal_enumerate_data()</function> may be used
 108     to iterate through all fields of the current entry. On each
 109     invocation the data for the next field is returned. The order of
 110     these fields is not defined. The data returned is in the same
 111     format as with <function>sd_journal_get_data()</function> and also
 112     follows the same life-time semantics.</para>
 113
 114     <para><function>sd_journal_restart_data()</function> resets the
 115     data enumeration index to the beginning of the entry. The next
 116     invocation of <function>sd_journal_enumerate_data()</function>
 117     will return the first field of the entry again.</para>
 118
 119     <para>Note that the <function>SD_JOURNAL_FOREACH_DATA()</function>
 120     macro may be used as a handy wrapper around
 121     <function>sd_journal_restart_data()</function> and
 122     <function>sd_journal_enumerate_data()</function>.</para>
 123
 124     <para>Note that these functions will not work before
 125     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 126     (or related call) has been called at least once, in order to
 127     position the read pointer at a valid entry.</para>
 128
 129     <para><function>sd_journal_set_data_threshold()</function> may be
 130     used to change the data field size threshold for data returned by
 131     <function>sd_journal_get_data()</function>,
 132     <function>sd_journal_enumerate_data()</function> and
 133     <function>sd_journal_enumerate_unique()</function>. This threshold
 134     is a hint only: it indicates that the client program is interested
 135     only in the initial parts of the data fields, up to the threshold
 136     in size — but the library might still return larger data objects.
 137     That means applications should not rely exclusively on this
 138     setting to limit the size of the data fields returned, but need to
 139     apply an explicit size limit on the returned data as well. This
 140     threshold defaults to 64K by default. To retrieve the complete
 141     data fields this threshold should be turned off by setting it to
 142     0, so that the library always returns the complete data objects.
 143     It is recommended to set this threshold as low as possible since
 144     this relieves the library from having to decompress large
 145     compressed data objects in full.</para>
 146
 147     <para><function>sd_journal_get_data_threshold()</function> returns
 148     the currently configured data field size threshold.</para>
 149   </refsect1>
 150
 151   <refsect1>
 152     <title>Return Value</title>
 153
 154     <para><function>sd_journal_get_data()</function> returns 0 on
 155     success or a negative errno-style error code. If the current entry
 156     does not include the specified field, -ENOENT is returned. If
 157     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 158     has not been called at least once, -EADDRNOTAVAIL is returned.
 159     <function>sd_journal_enumerate_data()</function> returns a
 160     positive integer if the next field has been read, 0 when no more
 161     fields are known, or a negative errno-style error code.
 162     <function>sd_journal_restart_data()</function> returns nothing.
 163     <function>sd_journal_set_data_threshold()</function> and
 164     <function>sd_journal_get_threshold()</function> return 0 on
 165     success or a negative errno-style error code.</para>
 166   </refsect1>
 167
 168   <xi:include href="libsystemd-pkgconfig.xml" />
 169
 170   <refsect1>
 171     <title>Examples</title>
 172
 173     <para>See
 174     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 175     for a complete example how to use
 176     <function>sd_journal_get_data()</function>.</para>
 177
 178     <para>Use the
 179     <function>SD_JOURNAL_FOREACH_DATA</function> macro to
 180     iterate through all fields of the current journal
 181     entry:</para>
 182
 183     <programlisting>…
 184 int print_fields(sd_journal *j) {
 185   const void *data;
 186   size_t length;
 187   SD_JOURNAL_FOREACH_DATA(j, data, length)
 188     printf("%.*s\n", (int) length, data);
 189 }
 190 …</programlisting>
 191   </refsect1>
 192
 193   <refsect1>
 194     <title>See Also</title>
 195
 196     <para>
 197       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 198       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 199       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 200       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 201       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 202       <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 203       <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 204     </para>
 205   </refsect1>
 206
 207 </refentry>