Adding upstream version 252.22.upstream/252.22upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 177 insertions, 0 deletions

diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml
new file mode 100644
index 0000000..f7f5ee3
--- /dev/null
+++ b/man/sd_journal_add_match.xml
@@ -0,0 +1,177 @@
+<?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_add_match" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_journal_add_match</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_journal_add_match</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_journal_add_match</refname>
+    <refname>sd_journal_add_disjunction</refname>
+    <refname>sd_journal_add_conjunction</refname>
+    <refname>sd_journal_flush_matches</refname>
+    <refpurpose>Add or remove entry matches</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_journal_add_match</function></funcdef>
+        <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+        <paramdef>const void *<parameter>data</parameter></paramdef>
+        <paramdef>size_t <parameter>size</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_journal_add_disjunction</function></funcdef>
+        <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_journal_add_conjunction</function></funcdef>
+        <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>void <function>sd_journal_flush_matches</function></funcdef>
+        <paramdef>sd_journal *<parameter>j</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_journal_add_match()</function> adds a match by
+    which to filter the entries of the journal file. Matches applied
+    with this call will filter what can be iterated through and read
+    from the journal file via calls like
+    <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    and
+    <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    Parameter <parameter>data</parameter> must be of the form
+    <literal><replaceable>FIELD</replaceable>=<replaceable>value</replaceable></literal>,
+    where the <replaceable>FIELD</replaceable> part is a short uppercase string consisting only
+    of 0–9, A–Z and the underscore; it may not begin with two underscores or be the empty
+    string. The <replaceable>value</replaceable> part may be anything, including binary. Parameter
+    <parameter>size</parameter> specifies the number of bytes in <parameter>data</parameter>
+    (i.e. the length of <replaceable>FIELD</replaceable>, plus one, plus the length of
+    <replaceable>value</replaceable>). Parameter <parameter>size</parameter> may also be
+    specified as <constant>0</constant>, in which case <parameter>data</parameter>
+    must be a <constant>NUL</constant>-terminated string, and the bytes before the terminating
+    zero are used as the match.</para>
+
+    <para>If a match is applied, only entries with this field set
+    will be iterated. Multiple matches may be active at the same time:
+    If they apply to different fields, only entries with both fields
+    set like this will be iterated. If they apply to the same fields,
+    only entries where the field takes one of the specified values
+    will be iterated. Well known fields are documented in
+    <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+    Whenever a new match is added the current entry position is reset,
+    and
+    <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    (or a similar call) needs to be called before entries can be read
+    again.</para>
+
+    <para><function>sd_journal_add_disjunction()</function> may be
+    used to insert a disjunction (i.e. logical OR) in the match list.
+    If this call is invoked, all previously added matches since the
+    last invocation of
+    <function>sd_journal_add_disjunction()</function> or
+    <function>sd_journal_add_conjunction()</function> are combined in
+    an OR with all matches added afterwards, until
+    <function>sd_journal_add_disjunction()</function> or
+    <function>sd_journal_add_conjunction()</function> is invoked again
+    to begin the next OR or AND term. </para>
+
+    <para><function>sd_journal_add_conjunction()</function> may be
+    used to insert a conjunction (i.e. logical AND) in the match list.
+    If this call is invoked, all previously added matches since the
+    last invocation of
+    <function>sd_journal_add_conjunction()</function> are combined in
+    an AND with all matches added afterwards, until
+    <function>sd_journal_add_conjunction()</function> is invoked again
+    to begin the next AND term. The combination of
+    <function>sd_journal_add_match()</function>,
+    <function>sd_journal_add_disjunction()</function> and
+    <function>sd_journal_add_conjunction()</function> may be used to
+    build complex search terms, even though full logical expressions
+    are not available. Note that
+    <function>sd_journal_add_conjunction()</function> operates one
+    level 'higher' than
+    <function>sd_journal_add_disjunction()</function>. It is hence
+    possible to build an expression of AND terms, consisting of OR
+    terms, consisting of AND terms, consisting of OR terms of matches
+    (the latter OR expression is implicitly created for matches with
+    the same field name, see above).</para>
+
+    <para><function>sd_journal_flush_matches()</function> may be used
+    to flush all matches, disjunction and conjunction terms again.
+    After this call all filtering is removed and all entries in the
+    journal will be iterated again.</para>
+
+    <para>Note that filtering via matches only applies to the way the
+    journal is read, it has no effect on storage on disk.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para><function>sd_journal_add_match()</function>,
+    <function>sd_journal_add_disjunction()</function> and
+    <function>sd_journal_add_conjunction()</function>
+    return 0 on success or a negative errno-style error
+    code. <function>sd_journal_flush_matches()</function>
+    returns nothing.</para>
+  </refsect1>
+
+  <xi:include href="libsystemd-pkgconfig.xml" />
+
+  <refsect1>
+    <title>Examples</title>
+
+    <para>The following example adds matches to a journal context
+    object to iterate only through messages generated by the Avahi
+    service at the four error log levels, plus all messages of the
+    message ID 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any
+    service (this example lacks the necessary error checking):</para>
+
+    <programlisting>…
+int add_matches(sd_journal *j) {
+  sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0);
+  sd_journal_add_match(j, "PRIORITY=0", 0);
+  sd_journal_add_match(j, "PRIORITY=1", 0);
+  sd_journal_add_match(j, "PRIORITY=2", 0);
+  sd_journal_add_match(j, "PRIORITY=3", 0);
+  sd_journal_add_disjunction(j);
+  sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0);
+}</programlisting>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</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_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>