man/sd_journal_get_data.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_journal_get_data" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_journal_get_data</title>
  10     <productname>systemd</productname>
  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>
  21     <refname>sd_journal_enumerate_available_data</refname>
  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 &lt;systemd/sd-journal.h&gt;</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
  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
  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
  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>
  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
 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
 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
 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>
 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
 129     in size — but the library might still return larger data objects.
 130     That means applications should not rely exclusively on this
 131     setting to limit the size of the data fields returned, but need to
 132     apply an explicit size limit on the returned data as well. This
 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
 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>
 166
 167           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 168         </varlistentry>
 169
 170         <varlistentry id='ECHILD'>
 171           <term><constant>-ECHILD</constant></term>
 172
 173           <listitem><para>The journal object was created in a different process, library or module instance.</para>
 174
 175           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 176         </varlistentry>
 177
 178         <varlistentry id='EADDRNOTAVAIL'>
 179           <term><constant>-EADDRNOTAVAIL</constant></term>
 180
 181           <listitem><para>The read pointer is not positioned at a valid entry;
 182           <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 183           or a related call has not been called at least once.</para>
 184
 185           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 186         </varlistentry>
 187
 188         <varlistentry id='ENOENT'>
 189           <term><constant>-ENOENT</constant></term>
 190
 191           <listitem><para>The current entry does not include the specified field.</para>
 192
 193           <xi:include href="version-info.xml" xpointer="v246"/>
 194           </listitem>
 195         </varlistentry>
 196
 197         <varlistentry id='ENOMEM'>
 198           <term><constant>-ENOMEM</constant></term>
 199
 200           <listitem><para>Memory allocation failed.</para>
 201
 202           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 203         </varlistentry>
 204
 205         <varlistentry id='ENOBUFS'>
 206           <term><constant>-ENOBUFS</constant></term>
 207
 208           <listitem><para>A compressed entry is too large.</para>
 209
 210           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 211         </varlistentry>
 212
 213         <varlistentry id='E2BIG'>
 214           <term><constant>-E2BIG</constant></term>
 215
 216           <listitem><para>The data field is too large for this computer architecture (e.g. above 4 GB on a
 217           32-bit architecture).</para>
 218
 219           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 220         </varlistentry>
 221
 222         <varlistentry id='EPROTONOSUPPORT'>
 223           <term><constant>-EPROTONOSUPPORT</constant></term>
 224
 225           <listitem><para>The journal is compressed with an unsupported method or the journal uses an
 226           unsupported feature.</para>
 227
 228           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 229         </varlistentry>
 230
 231         <varlistentry id='EBADMSG'>
 232           <term><constant>-EBADMSG</constant></term>
 233
 234           <listitem><para>The journal is corrupted (possibly just the entry being iterated over).
 235           </para>
 236
 237           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 238         </varlistentry>
 239
 240         <varlistentry id='EIO'>
 241           <term><constant>-EIO</constant></term>
 242
 243           <listitem><para>An I/O error was reported by the kernel.</para>
 244
 245           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 246         </varlistentry>
 247       </variablelist>
 248     </refsect2>
 249   </refsect1>
 250
 251   <refsect1>
 252     <title>Notes</title>
 253
 254     <xi:include href="threads-aware.xml" xpointer="strict"/>
 255
 256     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 257   </refsect1>
 258
 259   <refsect1>
 260     <title>Examples</title>
 261
 262     <para>See
 263     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 264     for a complete example how to use
 265     <function>sd_journal_get_data()</function>.</para>
 266
 267     <para>Use the
 268     <function>SD_JOURNAL_FOREACH_DATA()</function> macro to
 269     iterate through all fields of the current journal
 270     entry:</para>
 271
 272     <programlisting>…
 273 int print_fields(sd_journal *j) {
 274   const void *data;
 275   size_t length;
 276   SD_JOURNAL_FOREACH_DATA(j, data, length)
 277     printf("%.*s\n", (int) length, data);
 278 }
 279 …</programlisting>
 280   </refsect1>
 281
 282   <refsect1>
 283     <title>History</title>
 284     <para><function>sd_journal_get_data()</function>,
 285     <function>sd_journal_enumerate_data()</function>,
 286     <function>sd_journal_restart_data()</function>, and
 287     <function>SD_JOURNAL_FOREACH_DATA()</function> were added in version 187.</para>
 288     <para><function>sd_journal_set_data_threshold()</function> and
 289     <function>sd_journal_get_data_threshold()</function> were added in version 196.</para>
 290     <para><function>sd_journal_enumerate_available_data()</function> was added in version 246.</para>
 291   </refsect1>
 292
 293   <refsect1>
 294     <title>See Also</title>
 295
 296     <para><simplelist type="inline">
 297       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 298       <member><citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 299       <member><citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 300       <member><citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 301       <member><citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 302       <member><citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 303       <member><citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 304     </simplelist></para>
 305   </refsect1>
 306
 307 </refentry>