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