diff options
Diffstat (limited to 'man/sd_journal_get_data.xml')
| -rw-r--r-- | man/sd_journal_get_data.xml | 307 |
1 files changed, 307 insertions, 0 deletions
diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml new file mode 100644 index 0000000..ae0911f --- /dev/null +++ b/man/sd_journal_get_data.xml @@ -0,0 +1,307 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="sd_journal_get_data" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_journal_get_data</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_get_data</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_data</refname> + <refname>sd_journal_enumerate_data</refname> + <refname>sd_journal_enumerate_available_data</refname> + <refname>sd_journal_restart_data</refname> + <refname>SD_JOURNAL_FOREACH_DATA</refname> + <refname>sd_journal_set_data_threshold</refname> + <refname>sd_journal_get_data_threshold</refname> + <refpurpose>Read data fields from the current journal entry</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_data</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const char *<parameter>field</parameter></paramdef> + <paramdef>const void **<parameter>data</parameter></paramdef> + <paramdef>size_t *<parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_enumerate_data</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const void **<parameter>data</parameter></paramdef> + <paramdef>size_t *<parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_enumerate_available_data</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const void **<parameter>data</parameter></paramdef> + <paramdef>size_t *<parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_journal_restart_data</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef><function>SD_JOURNAL_FOREACH_DATA</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const void *<parameter>data</parameter></paramdef> + <paramdef>size_t <parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_set_data_threshold</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>size_t <parameter>sz</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_get_data_threshold</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>size_t *<parameter>sz</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_data()</function> gets the data object associated with a specific field + from the current journal entry. It takes four arguments: the journal context object, a string with the + field name to request, plus a pair of pointers to pointer/size variables where the data object and its + size shall be stored in. The field name should be an entry field name. Well-known field names are listed in + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + but any field can be specified. The returned data is in a read-only memory map and is only valid until + the next invocation of <function>sd_journal_get_data()</function>, + <function>sd_journal_enumerate_data()</function>, + <function>sd_journal_enumerate_available_data()</function>, or when the read pointer is altered. Note + that the data returned will be prefixed with the field name and <literal>=</literal>. Also note that, by + default, data fields larger than 64K might get truncated to 64K. This threshold may be changed and turned + off with <function>sd_journal_set_data_threshold()</function> (see below).</para> + + <para><function>sd_journal_enumerate_data()</function> may be used + to iterate through all fields of the current entry. On each + invocation the data for the next field is returned. The order of + these fields is not defined. The data returned is in the same + format as with <function>sd_journal_get_data()</function> and also + follows the same life-time semantics.</para> + + <para><function>sd_journal_enumerate_available_data()</function> is similar to + <function>sd_journal_enumerate_data()</function>, but silently skips any fields which may be valid, but + are too large or not supported by current implementation.</para> + + <para><function>sd_journal_restart_data()</function> resets the + data enumeration index to the beginning of the entry. The next + invocation of <function>sd_journal_enumerate_data()</function> + will return the first field of the entry again.</para> + + <para>Note that the <function>SD_JOURNAL_FOREACH_DATA()</function> macro may be used as a handy wrapper + around <function>sd_journal_restart_data()</function> and + <function>sd_journal_enumerate_available_data()</function>.</para> + + <para>Note that these functions will not work before + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + (or related call) has been called at least once, in order to + position the read pointer at a valid entry.</para> + + <para><function>sd_journal_set_data_threshold()</function> may be + used to change the data field size threshold for data returned by + <function>sd_journal_get_data()</function>, + <function>sd_journal_enumerate_data()</function> and + <function>sd_journal_enumerate_unique()</function>. This threshold + is a hint only: it indicates that the client program is interested + only in the initial parts of the data fields, up to the threshold + in size — but the library might still return larger data objects. + That means applications should not rely exclusively on this + setting to limit the size of the data fields returned, but need to + apply an explicit size limit on the returned data as well. This + threshold defaults to 64K by default. To retrieve the complete + data fields this threshold should be turned off by setting it to + 0, so that the library always returns the complete data objects. + It is recommended to set this threshold as low as possible since + this relieves the library from having to decompress large + compressed data objects in full.</para> + + <para><function>sd_journal_get_data_threshold()</function> returns + the currently configured data field size threshold.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_data()</function> returns 0 on success or a negative errno-style error + code. <function>sd_journal_enumerate_data()</function> and + <function>sd_journal_enumerate_available_data()</function> return a positive integer if the next field + has been read, 0 when no more fields remain, or a negative errno-style error code. + <function>sd_journal_restart_data()</function> doesn't return anything. + <function>sd_journal_set_data_threshold()</function> and <function>sd_journal_get_threshold()</function> + return 0 on success or a negative errno-style error code.</para> + + <refsect2> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry id='EINVAL'> + <term><constant>-EINVAL</constant></term> + + <listitem><para>One of the required parameters is <constant>NULL</constant> or invalid. + </para> + + <xi:include href="version-info.xml" xpointer="v246"/></listitem> + </varlistentry> + + <varlistentry id='ECHILD'> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The journal object was created in a different process, library or module instance.</para> + + <xi:include href="version-info.xml" xpointer="v246"/></listitem> + </varlistentry> + + <varlistentry id='EADDRNOTAVAIL'> + <term><constant>-EADDRNOTAVAIL</constant></term> + + <listitem><para>The read pointer is not positioned at a valid entry; + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or a related call has not been called at least once.</para> + + <xi:include href="version-info.xml" xpointer="v246"/></listitem> + </varlistentry> + + <varlistentry id='ENOENT'> + <term><constant>-ENOENT</constant></term> + + <listitem><para>The current entry does not include the specified field.</para> + + <xi:include href="version-info.xml" xpointer="v246"/> + </listitem> + </varlistentry> + + <varlistentry id='ENOMEM'> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para> + + <xi:include href="version-info.xml" xpointer="v246"/></listitem> + </varlistentry> + + <varlistentry id='ENOBUFS'> + <term><constant>-ENOBUFS</constant></term> + + <listitem><para>A compressed entry is too large.</para> + + <xi:include href="version-info.xml" xpointer="v246"/></listitem> + </varlistentry> + + <varlistentry id='E2BIG'> + <term><constant>-E2BIG</constant></term> + + <listitem><para>The data field is too large for this computer architecture (e.g. above 4 GB on a + 32-bit architecture).</para> + + <xi:include href="version-info.xml" xpointer="v246"/></listitem> + </varlistentry> + + <varlistentry id='EPROTONOSUPPORT'> + <term><constant>-EPROTONOSUPPORT</constant></term> + + <listitem><para>The journal is compressed with an unsupported method or the journal uses an + unsupported feature.</para> + + <xi:include href="version-info.xml" xpointer="v246"/></listitem> + </varlistentry> + + <varlistentry id='EBADMSG'> + <term><constant>-EBADMSG</constant></term> + + <listitem><para>The journal is corrupted (possibly just the entry being iterated over). + </para> + + <xi:include href="version-info.xml" xpointer="v246"/></listitem> + </varlistentry> + + <varlistentry id='EIO'> + <term><constant>-EIO</constant></term> + + <listitem><para>An I/O error was reported by the kernel.</para> + + <xi:include href="version-info.xml" xpointer="v246"/></listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="threads-aware.xml" xpointer="strict"/> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>See + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for a complete example how to use + <function>sd_journal_get_data()</function>.</para> + + <para>Use the + <function>SD_JOURNAL_FOREACH_DATA()</function> macro to + iterate through all fields of the current journal + entry:</para> + + <programlisting>… +int print_fields(sd_journal *j) { + const void *data; + size_t length; + SD_JOURNAL_FOREACH_DATA(j, data, length) + printf("%.*s\n", (int) length, data); +} +…</programlisting> + </refsect1> + + <refsect1> + <title>History</title> + <para><function>sd_journal_get_data()</function>, + <function>sd_journal_enumerate_data()</function>, + <function>sd_journal_restart_data()</function>, and + <function>SD_JOURNAL_FOREACH_DATA()</function> were added in version 187.</para> + <para><function>sd_journal_set_data_threshold()</function> and + <function>sd_journal_get_data_threshold()</function> were added in version 196.</para> + <para><function>sd_journal_enumerate_available_data()</function> was added in version 246.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |