sd_journal_get_data.xml revision 74d005783e355acc784d123024e33bbb66ef9ef1
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering This file is part of systemd.
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering Copyright 2012 Lennart Poettering
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering systemd is free software; you can redistribute it and/or modify it
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering under the terms of the GNU Lesser General Public License as published by
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering the Free Software Foundation; either version 2.1 of the License, or
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering (at your option) any later version.
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering systemd is distributed in the hope that it will be useful, but
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering Lesser General Public License for more details.
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering You should have received a copy of the GNU Lesser General Public License
c2756a68401102786be343712c0c35acbd73d28dLennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
9b15b7846d4de01bb5d9700a24077787e984e8abLennart Poettering <refentryinfo>
6482f6269c87d2249e52e889a63adbdd50f2d691Ronny Chevalier </authorgroup>
24882e06c135584f16f31ba8a00fecde8b7f6fadLennart Poettering </refentryinfo>
6577c7cea72f19185ad999c223bcf663c010dc6fLennart Poettering <refentrytitle>sd_journal_get_data</refentrytitle>
d21ed1ead18d16d35c30299a69d3366847f8a039Lennart Poettering <refname>sd_journal_enumerate_data</refname>
1ac67edb7c4d31a287fa98c0b554ae98bd34e71bLennart Poettering <refname>sd_journal_restart_data</refname>
d21ed1ead18d16d35c30299a69d3366847f8a039Lennart Poettering <refname>SD_JOURNAL_FOREACH_DATA</refname>
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering <refname>sd_journal_set_data_threshold</refname>
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering <refname>sd_journal_get_data_threshold</refname>
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering <refpurpose>Read data fields from the current journal entry</refpurpose>
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering <refsynopsisdiv>
df31a6c0fe07805cb50045fbe91c2a6e7e430562Lennart Poettering <funcsynopsis>
9b15b7846d4de01bb5d9700a24077787e984e8abLennart Poettering <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <funcprototype>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <funcdef>int <function>sd_journal_get_data</function></funcdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <paramdef>sd_journal* <parameter>j</parameter></paramdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <paramdef>const char* <parameter>field</parameter></paramdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <paramdef>const void** <parameter>data</parameter></paramdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <paramdef>size_t* <parameter>length</parameter></paramdef>
095dc59660c3dde782f32fe5a52b577f7700578bLennart Poettering </funcprototype>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <funcdef>int <function>sd_journal_enumerate_data</function></funcdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <paramdef>sd_journal* <parameter>j</parameter></paramdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <paramdef>const void** <parameter>data</parameter></paramdef>
cd32b977facd20145f570efbfdf541ffc2780c4eZbigniew Jędrzejewski-Szmek <paramdef>size_t* <parameter>length</parameter></paramdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho </funcprototype>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <funcprototype>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <funcdef>void <function>sd_journal_restart_data</function></funcdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <paramdef>sd_journal* <parameter>j</parameter></paramdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho </funcprototype>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <funcprototype>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <funcdef><function>SD_JOURNAL_FOREACH_DATA</function></funcdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <paramdef>sd_journal* <parameter>j</parameter></paramdef>
3d161f991e16369aa59f447eb4cdb90af33261c8Lennart Poettering <paramdef>const void* <parameter>data</parameter></paramdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <paramdef>size_t <parameter>length</parameter></paramdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho </funcprototype>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <funcprototype>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <funcdef>int <function>sd_journal_set_data_threshold</function></funcdef>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <paramdef>sd_journal* <parameter>j</parameter></paramdef>
9b15b7846d4de01bb5d9700a24077787e984e8abLennart Poettering <paramdef>size_t <parameter>sz</parameter></paramdef>
095dc59660c3dde782f32fe5a52b577f7700578bLennart Poettering </funcprototype>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <funcprototype>
b57b06258e0b1894edb6d1fc52a80b3c33164892Zbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_journal_get_data_threshold</function></funcdef>
b57b06258e0b1894edb6d1fc52a80b3c33164892Zbigniew Jędrzejewski-Szmek <paramdef>sd_journal* <parameter>j</parameter></paramdef>
b57b06258e0b1894edb6d1fc52a80b3c33164892Zbigniew Jędrzejewski-Szmek <paramdef>size_t* <parameter>sz</parameter></paramdef>
b57b06258e0b1894edb6d1fc52a80b3c33164892Zbigniew Jędrzejewski-Szmek </funcprototype>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho </refsynopsisdiv>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <para><function>sd_journal_get_data()</function> gets
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho the data object associated with a specific field from
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho the current journal entry. It takes four arguments:
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho the journal context object, a string with the field
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering name to request, plus a pair of pointers to
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering pointer/size variables where the data object and its
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering size shall be stored in. The field name should be an
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering entry field name. Well-known field names are listed in
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
66b1e746055b9c56fd72c0451a4cfb2b06cf3f20Lennart Poettering returned data is in a read-only memory map and is only
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering valid until the next invocation of
9f2e86af0600e99cff00d1c92f9bb8d38f29896aLennart Poettering <function>sd_journal_get_data()</function> or
c221420be8744bb0f8b8a8145efc1f247f1aa801Lennart Poettering <function>sd_journal_enumerate_data()</function>, or
a6c0353b9268d5b780fb7ff05a10cb5031446e5dLennart Poettering the read pointer is altered. Note that the data
a6c0353b9268d5b780fb7ff05a10cb5031446e5dLennart Poettering returned will be prefixed with the field name and
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering '='. Also note that by default data fields larger than
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering 64K might get truncated to 64K. This threshold may be
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering changed and turned off with
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering <function>sd_journal_set_data_threshold()</function> (see
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho below).</para>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <para><function>sd_journal_enumerate_data()</function>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho may be used to iterate through all fields of the
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho current entry. On each invocation the data for the
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho next field is returned. The order of these fields is
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho not defined. The data returned is in the same format
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho as with <function>sd_journal_get_data()</function> and
3d161f991e16369aa59f447eb4cdb90af33261c8Lennart Poettering also follows the same life-time semantics.</para>
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering <para><function>sd_journal_restart_data()</function>
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering resets the data enumeration index to the beginning of
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering the entry. The next invocation of
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <function>sd_journal_enumerate_data()</function> will return the first
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho field of the entry again.</para>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <para>Note that the
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <function>SD_JOURNAL_FOREACH_DATA()</function> macro
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho may be used as a handy wrapper around
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <function>sd_journal_restart_data()</function> and
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <function>sd_journal_enumerate_data()</function>.</para>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <para>Note that these functions will not work before
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho (or related call) has been called at least
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho once, in order to position the read pointer at a valid entry.</para>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho <para><function>sd_journal_set_data_threshold()</function>
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho may be used to change the data field size threshold
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho for data returned by
9b15b7846d4de01bb5d9700a24077787e984e8abLennart Poettering <function>sd_journal_enumerate_data()</function> and
095dc59660c3dde782f32fe5a52b577f7700578bLennart Poettering <function>sd_journal_enumerate_unique()</function>. This
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho threshold is a hint only: it indicates that the client
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho program is interested only in the initial parts of the
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho data fields, up to the threshold in size -- but the
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho library might still return larger data objects. That
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho means applications should not rely exclusively on this
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho setting to limit the size of the data fields returned,
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho but need to apply a explicit size limit on the
3d161f991e16369aa59f447eb4cdb90af33261c8Lennart Poettering returned data as well. This threshold defaults to 64K
eb9da376d76b48585b3b63b4f91903b54f7abd36Lennart Poettering by default. To retrieve the complete data fields this
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering threshold should be turned off by setting it to 0, so
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering that the library always returns the complete data
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering objects. It is recommended to set this threshold as
4c213d6cf416917c61f82d8bee795b8f3a4c5372WaLyong Cho low as possible since this relieves the library from
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering having to decompress large compressed data objects in
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering <para><function>sd_journal_get_data_threshold()</function>
095dc59660c3dde782f32fe5a52b577f7700578bLennart Poettering returns the currently configured data field size
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering threshold.</para>
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering <para><function>sd_journal_get_data()</function>
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering returns 0 on success or a negative errno-style error
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering code. If the current entry does not include the
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering specified field -ENOENT is returned. If
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering has not been called at least once -EADDRNOTAVAIL is
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering returned. <function>sd_journal_enumerate_data()</function>
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering returns a positive integer if the next field has been
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering read, 0 when no more fields are known, or a negative
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering errno-style error
66b1e746055b9c56fd72c0451a4cfb2b06cf3f20Lennart Poettering code. <function>sd_journal_restart_data()</function>
66b1e746055b9c56fd72c0451a4cfb2b06cf3f20Lennart Poettering nothing. <function>sd_journal_set_data_threshold()</function>
66b1e746055b9c56fd72c0451a4cfb2b06cf3f20Lennart Poettering and <function>sd_journal_get_threshold()</function>
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering return 0 on success or a negative errno-style error
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering <para>The <function>sd_journal_get_data()</function>,
9f2e86af0600e99cff00d1c92f9bb8d38f29896aLennart Poettering <function>sd_journal_enumerate_data()</function>,
9f2e86af0600e99cff00d1c92f9bb8d38f29896aLennart Poettering <function>sd_journal_restart_data()</function>,
9f2e86af0600e99cff00d1c92f9bb8d38f29896aLennart Poettering <function>sd_journal_set_data_threshold()</function>
c221420be8744bb0f8b8a8145efc1f247f1aa801Lennart Poettering <function>sd_journal_get_data_threshold()</function>
c221420be8744bb0f8b8a8145efc1f247f1aa801Lennart Poettering interfaces are available as shared library, which can
c221420be8744bb0f8b8a8145efc1f247f1aa801Lennart Poettering be compiled and linked to with the
a6c0353b9268d5b780fb7ff05a10cb5031446e5dLennart Poettering <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
d21ed1ead18d16d35c30299a69d3366847f8a039Lennart Poettering <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
d21ed1ead18d16d35c30299a69d3366847f8a039Lennart Poettering for a complete example how to use
d21ed1ead18d16d35c30299a69d3366847f8a039Lennart Poettering <function>sd_journal_get_data()</function>.</para>
d21ed1ead18d16d35c30299a69d3366847f8a039Lennart Poettering <function>SD_JOURNAL_FOREACH_DATA</function> macro to
de33fc625725d199629ed074d6278504deb23debLennart Poettering iterate through all fields of the current journal
d21ed1ead18d16d35c30299a69d3366847f8a039Lennart Poettering <programlisting>...
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poetteringint print_fields(sd_journal *j) {
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering const void *data;
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering SD_JOURNAL_FOREACH_DATA(j, data, length)
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering printf("%.*s\n", (int) length, data);
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering...</programlisting>
1ac67edb7c4d31a287fa98c0b554ae98bd34e71bLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
c7040b5d1c2c148f12b6a5eef3dfce1661805131Lennart Poettering <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>