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