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