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