picnoir/Systemd
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

man: update docs with the new functions and other enhancements

Browse source
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2020-07-21 17:16:52 +02:00
parent 7cbb7d62c6
commit 0da322d9a4
2 changed files with 170 additions and 76 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

141
man/sd_journal_get_data.xml
View file

@ -18,6 +18,7 @@
<refnamediv> <refnamediv>
<refname>sd_journal_get_data</refname> <refname>sd_journal_get_data</refname>
<refname>sd_journal_enumerate_data</refname> <refname>sd_journal_enumerate_data</refname>
<refname>sd_journal_enumerate_available_data</refname>
<refname>sd_journal_restart_data</refname> <refname>sd_journal_restart_data</refname>
<refname>SD_JOURNAL_FOREACH_DATA</refname> <refname>SD_JOURNAL_FOREACH_DATA</refname>
<refname>sd_journal_set_data_threshold</refname> <refname>sd_journal_set_data_threshold</refname>
@ -44,6 +45,13 @@
<paramdef>size_t *<parameter>length</parameter></paramdef> <paramdef>size_t *<parameter>length</parameter></paramdef>
</funcprototype> </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> <funcprototype>
<funcdef>void <function>sd_journal_restart_data</function></funcdef> <funcdef>void <function>sd_journal_restart_data</function></funcdef>
<paramdef>sd_journal *<parameter>j</parameter></paramdef> <paramdef>sd_journal *<parameter>j</parameter></paramdef>
@ -73,24 +81,18 @@
<refsect1> <refsect1>
<title>Description</title> <title>Description</title>
<para><function>sd_journal_get_data()</function> gets the data <para><function>sd_journal_get_data()</function> gets the data object associated with a specific field
object associated with a specific field from the current journal from the current journal entry. It takes four arguments: the journal context object, a string with the
entry. It takes four arguments: the journal context object, a field name to request, plus a pair of pointers to pointer/size variables where the data object and its
string with the field name to request, plus a pair of pointers to size shall be stored in. The field name should be an entry field name. Well-known field names are listed in
pointer/size variables where the data object and its size shall be <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
stored in. The field name should be an entry field name. but any field can be specified. The returned data is in a read-only memory map and is only valid until
Well-known field names are listed in the next invocation of <function>sd_journal_get_data()</function>,
<citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. <function>sd_journal_enumerate_data()</function>,
The returned data is in a read-only memory map and is only valid <function>sd_journal_enumerate_available_data()</function>, or when the read pointer is altered. Note
until the next invocation of that the data returned will be prefixed with the field name and <literal>=</literal>. Also note that, by
<function>sd_journal_get_data()</function> or default, data fields larger than 64K might get truncated to 64K. This threshold may be changed and turned
<function>sd_journal_enumerate_data()</function>, or the read off with <function>sd_journal_set_data_threshold()</function> (see below).</para>
pointer is altered. Note that the data returned will be prefixed
with the field name and '='. 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 <para><function>sd_journal_enumerate_data()</function> may be used
to iterate through all fields of the current entry. On each to iterate through all fields of the current entry. On each
@ -99,15 +101,18 @@
format as with <function>sd_journal_get_data()</function> and also format as with <function>sd_journal_get_data()</function> and also
follows the same life-time semantics.</para> 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 <para><function>sd_journal_restart_data()</function> resets the
data enumeration index to the beginning of the entry. The next data enumeration index to the beginning of the entry. The next
invocation of <function>sd_journal_enumerate_data()</function> invocation of <function>sd_journal_enumerate_data()</function>
will return the first field of the entry again.</para> will return the first field of the entry again.</para>
<para>Note that the <function>SD_JOURNAL_FOREACH_DATA()</function> <para>Note that the <function>SD_JOURNAL_FOREACH_DATA()</function> macro may be used as a handy wrapper
macro may be used as a handy wrapper around around <function>sd_journal_restart_data()</function> and
<function>sd_journal_restart_data()</function> and <function>sd_journal_enumerate_available_data()</function>.</para>
<function>sd_journal_enumerate_data()</function>.</para>
<para>Note that these functions will not work before <para>Note that these functions will not work before
<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
@ -139,18 +144,88 @@
<refsect1> <refsect1>
<title>Return Value</title> <title>Return Value</title>
<para><function>sd_journal_get_data()</function> returns 0 on <para><function>sd_journal_get_data()</function> returns 0 on success or a negative errno-style error
success or a negative errno-style error code. If the current entry code. <function>sd_journal_enumerate_data()</function> and
does not include the specified field, -ENOENT is returned. If <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></listitem>
</varlistentry>
<varlistentry id='ECHILD'>
<term><constant>-ECHILD</constant></term>
<listitem><para>The journal object was created in a different process.</para></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> <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
has not been called at least once, -EADDRNOTAVAIL is returned. or a related call has not been called at least once.</para></listitem>
<function>sd_journal_enumerate_data()</function> returns a </varlistentry>
positive integer if the next field has been read, 0 when no more
fields are known, or a negative errno-style error code. <varlistentry id='ENOENT'>
<function>sd_journal_restart_data()</function> returns nothing. <term><constant>-ENOENT</constant></term>
<function>sd_journal_set_data_threshold()</function> and
<function>sd_journal_get_threshold()</function> return 0 on <listitem><para>The current entry does not include the specified field.</para>
success or a negative errno-style error code.</para> </listitem>
</varlistentry>
<varlistentry id='ENOMEM'>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Memory allocation failed.</para></listitem>
</varlistentry>
<varlistentry id='ENOBUFS'>
<term><constant>-ENOBUFS</constant></term>
<listitem><para>A compressed entry is too large.</para></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></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></listitem>
</varlistentry>
<varlistentry id='EBADMSG'>
<term><constant>-EBADMSG</constant></term>
<listitem><para>The journal is corrupted (possibly just the entry being iterated over).
</para></listitem>
</varlistentry>
<varlistentry id='EIO'>
<term><constant>-EIO</constant></term>
<listitem><para>An I/O error was reported by the kernel.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1> </refsect1>
<refsect1> <refsect1>

103
man/sd_journal_query_unique.xml
View file

@ -18,6 +18,7 @@
<refnamediv> <refnamediv>
<refname>sd_journal_query_unique</refname> <refname>sd_journal_query_unique</refname>
<refname>sd_journal_enumerate_unique</refname> <refname>sd_journal_enumerate_unique</refname>
<refname>sd_journal_enumerate_available_unique</refname>
<refname>sd_journal_restart_unique</refname> <refname>sd_journal_restart_unique</refname>
<refname>SD_JOURNAL_FOREACH_UNIQUE</refname> <refname>SD_JOURNAL_FOREACH_UNIQUE</refname>
<refpurpose>Read unique data fields from the journal</refpurpose> <refpurpose>Read unique data fields from the journal</refpurpose>
@ -33,6 +34,13 @@
<paramdef>const char *<parameter>field</parameter></paramdef> <paramdef>const char *<parameter>field</parameter></paramdef>
</funcprototype> </funcprototype>
<funcprototype>
<funcdef>int <function>sd_journal_enumerate_available_unique</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> <funcprototype>
<funcdef>int <function>sd_journal_enumerate_unique</function></funcdef> <funcdef>int <function>sd_journal_enumerate_unique</function></funcdef>
<paramdef>sd_journal *<parameter>j</parameter></paramdef> <paramdef>sd_journal *<parameter>j</parameter></paramdef>
@ -58,33 +66,31 @@
<refsect1> <refsect1>
<title>Description</title> <title>Description</title>
<para><function>sd_journal_query_unique()</function> queries the <para><function>sd_journal_query_unique()</function> queries the journal for all unique values the
journal for all unique values the specified field can take. It specified field can take. It takes two arguments: the journal to query and the field name to look
takes two arguments: the journal to query and the field name to for. Well-known field names are listed on
look for. Well-known field names are listed on <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. but any field can be specified. Field names must be specified without a trailing
Field names must be specified without a trailing '='. After this <literal>=</literal>. After this function has been executed successfully the field values may be queried
function has been executed successfully the field values may be using <function>sd_journal_enumerate_unique()</function> and
queried using <function>sd_journal_enumerate_unique()</function>. <function>sd_journal_enumerate_available_unique()</function>. Invoking one of those calls will change the
Invoking this call a second time will change the field name being field name being queried and reset the enumeration index to the first field value that matches.</para>
queried and reset the enumeration index to the first field value
that matches.</para>
<para><function>sd_journal_enumerate_unique()</function> may be <para><function>sd_journal_enumerate_unique()</function> may be used to iterate through all data fields
used to iterate through all data fields which match the previously which match the previously selected field name as set with
selected field name as set with <function>sd_journal_query_unique()</function>. On each invocation the next field data matching the field
<function>sd_journal_query_unique()</function>. On each invocation name is returned. The order of the returned data fields is not defined. It takes three arguments: the
the next field data matching the field name is returned. The order journal object, plus a pair of pointers to pointer/size variables where the data object and its size
of the returned data fields is not defined. It takes three shall be stored. The returned data is in a read-only memory map and is only valid until the next
arguments: the journal context object, plus a pair of pointers to invocation of <function>sd_journal_enumerate_unique()</function>. Note that the data returned will be
pointer/size variables where the data object and its size shall be prefixed with the field name and <literal>=</literal>. Note that this call is subject to the data field
stored in. The returned data is in a read-only memory map and is size threshold as controlled by <function>sd_journal_set_data_threshold()</function> and only the initial
only valid until the next invocation of part of the field up to the threshold is returned. An error is returned for fields which cannot be
<function>sd_journal_enumerate_unique()</function>. Note that the retrieved. See the error list below for details.</para>
data returned will be prefixed with the field name and '='. Note
that this call is subject to the data field size threshold as <para><function>sd_journal_enumerate_available_unique()</function> is similar to
controlled by <function>sd_journal_enumerate_unique()</function>, but silently skips any fields which may be valid, but
<function>sd_journal_set_data_threshold()</function>.</para> are too large or not supported by current implementation.</para>
<para><function>sd_journal_restart_unique()</function> resets the <para><function>sd_journal_restart_unique()</function> resets the
data enumeration index to the beginning of the list. The next data enumeration index to the beginning of the list. The next
@ -92,11 +98,9 @@
will return the first field data matching the field name will return the first field data matching the field name
again.</para> again.</para>
<para>Note that the <para>Note that the <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro may be used as a handy wrapper
<function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro may be used around <function>sd_journal_restart_unique()</function> and
as a handy wrapper around <function>sd_journal_enumerate_available_unique()</function>.</para>
<function>sd_journal_restart_unique()</function> and
<function>sd_journal_enumerate_unique()</function>.</para>
<para>Note that these functions currently are not influenced by <para>Note that these functions currently are not influenced by
matches set with <function>sd_journal_add_match()</function> but matches set with <function>sd_journal_add_match()</function> but
@ -111,13 +115,29 @@
<refsect1> <refsect1>
<title>Return Value</title> <title>Return Value</title>
<para><function>sd_journal_query_unique()</function> returns 0 on <para><function>sd_journal_query_unique()</function> returns 0 on success or a negative errno-style error
success or a negative errno-style error code. code. <function>sd_journal_enumerate_unique()</function> and and
<function>sd_journal_enumerate_unique()</function> returns a <function>sd_journal_query_available_unique()</function> return a positive integer if the next field data
positive integer if the next field data has been read, 0 when no has been read, 0 when no more fields remain, or a negative errno-style error code.
more fields are known, or a negative errno-style error code. <function>sd_journal_restart_unique()</function> doesn't return anything.</para>
<function>sd_journal_restart_unique()</function> returns
nothing.</para> <refsect2>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<xi:include href="sd_journal_get_data.xml" xpointer="EINVAL"/>
<xi:include href="sd_journal_get_data.xml" xpointer="ECHILD"/>
<xi:include href="sd_journal_get_data.xml" xpointer="EADDRNOTAVAIL"/>
<xi:include href="sd_journal_get_data.xml" xpointer="ENOENT"/>
<xi:include href="sd_journal_get_data.xml" xpointer="ENOBUFS"/>
<xi:include href="sd_journal_get_data.xml" xpointer="E2BIG"/>
<xi:include href="sd_journal_get_data.xml" xpointer="EPROTONOSUPPORT"/>
<xi:include href="sd_journal_get_data.xml" xpointer="EBADMSG"/>
<xi:include href="sd_journal_get_data.xml" xpointer="EIO"/>
</variablelist>
</refsect2>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -131,10 +151,9 @@
<refsect1> <refsect1>
<title>Examples</title> <title>Examples</title>
<para>Use the <function>SD_JOURNAL_FOREACH_UNIQUE</function> macro <para>Use the <function>SD_JOURNAL_FOREACH_UNIQUE</function> macro to iterate through all values a field
to iterate through all values a field of the journal can take. The of the journal can take (and which can be accessed on the given architecture and are not compressed with
following example lists all unit names referenced in the an unsupported mechanism). The following example lists all unit names referenced in the journal:</para>
journal:</para>
<programlisting><xi:include href="journal-iterate-unique.c" parse="text" /></programlisting> <programlisting><xi:include href="journal-iterate-unique.c" parse="text" /></programlisting>
</refsect1> </refsect1>