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.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   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></listitem>
 166         </varlistentry>
 167
 168         <varlistentry id='ECHILD'>
 169           <term><constant>-ECHILD</constant></term>
 170
 171           <listitem><para>The journal object was created in a different process.</para></listitem>
 172         </varlistentry>
 173
 174         <varlistentry id='EADDRNOTAVAIL'>
 175           <term><constant>-EADDRNOTAVAIL</constant></term>
 176
 177           <listitem><para>The read pointer is not positioned at a valid entry;
 178           <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 179           or a related call has not been called at least once.</para></listitem>
 180         </varlistentry>
 181
 182         <varlistentry id='ENOENT'>
 183           <term><constant>-ENOENT</constant></term>
 184
 185           <listitem><para>The current entry does not include the specified field.</para>
 186           </listitem>
 187         </varlistentry>
 188
 189         <varlistentry id='ENOMEM'>
 190           <term><constant>-ENOMEM</constant></term>
 191
 192           <listitem><para>Memory allocation failed.</para></listitem>
 193         </varlistentry>
 194
 195         <varlistentry id='ENOBUFS'>
 196           <term><constant>-ENOBUFS</constant></term>
 197
 198           <listitem><para>A compressed entry is too large.</para></listitem>
 199         </varlistentry>
 200
 201         <varlistentry id='E2BIG'>
 202           <term><constant>-E2BIG</constant></term>
 203
 204           <listitem><para>The data field is too large for this computer architecture (e.g. above 4 GB on a
 205           32-bit architecture).</para></listitem>
 206         </varlistentry>
 207
 208         <varlistentry id='EPROTONOSUPPORT'>
 209           <term><constant>-EPROTONOSUPPORT</constant></term>
 210
 211           <listitem><para>The journal is compressed with an unsupported method or the journal uses an
 212           unsupported feature.</para></listitem>
 213         </varlistentry>
 214
 215         <varlistentry id='EBADMSG'>
 216           <term><constant>-EBADMSG</constant></term>
 217
 218           <listitem><para>The journal is corrupted (possibly just the entry being iterated over).
 219           </para></listitem>
 220         </varlistentry>
 221
 222         <varlistentry id='EIO'>
 223           <term><constant>-EIO</constant></term>
 224
 225           <listitem><para>An I/O error was reported by the kernel.</para></listitem>
 226         </varlistentry>
 227       </variablelist>
 228     </refsect2>
 229   </refsect1>
 230
 231   <refsect1>
 232     <title>Notes</title>
 233
 234     <xi:include href="threads-aware.xml" xpointer="strict"/>
 235
 236     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 237   </refsect1>
 238
 239   <refsect1>
 240     <title>Examples</title>
 241
 242     <para>See
 243     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 244     for a complete example how to use
 245     <function>sd_journal_get_data()</function>.</para>
 246
 247     <para>Use the
 248     <function>SD_JOURNAL_FOREACH_DATA</function> macro to
 249     iterate through all fields of the current journal
 250     entry:</para>
 251
 252     <programlisting>…
 253 int print_fields(sd_journal *j) {
 254   const void *data;
 255   size_t length;
 256   SD_JOURNAL_FOREACH_DATA(j, data, length)
 257     printf("%.*s\n", (int) length, data);
 258 }
 259 …</programlisting>
 260   </refsect1>
 261
 262   <refsect1>
 263     <title>See Also</title>
 264
 265     <para>
 266       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 267       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 268       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 269       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 270       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 271       <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 272       <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 273     </para>
 274   </refsect1>
 275
 276 </refentry>