man/sd_journal_add_match.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
   9 <refentry id="sd_journal_add_match" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_journal_add_match</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>sd_journal_add_match</refentrytitle>
  18     <manvolnum>3</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>sd_journal_add_match</refname>
  23     <refname>sd_journal_add_disjunction</refname>
  24     <refname>sd_journal_add_conjunction</refname>
  25     <refname>sd_journal_flush_matches</refname>
  26     <refpurpose>Add or remove entry matches</refpurpose>
  27   </refnamediv>
  28
  29   <refsynopsisdiv>
  30     <funcsynopsis>
  31       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  32
  33       <funcprototype>
  34         <funcdef>int <function>sd_journal_add_match</function></funcdef>
  35         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  36         <paramdef>const void *<parameter>data</parameter></paramdef>
  37         <paramdef>size_t <parameter>size</parameter></paramdef>
  38       </funcprototype>
  39
  40       <funcprototype>
  41         <funcdef>int <function>sd_journal_add_disjunction</function></funcdef>
  42         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  43       </funcprototype>
  44
  45       <funcprototype>
  46         <funcdef>int <function>sd_journal_add_conjunction</function></funcdef>
  47         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  48       </funcprototype>
  49
  50       <funcprototype>
  51         <funcdef>void <function>sd_journal_flush_matches</function></funcdef>
  52         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  53       </funcprototype>
  54     </funcsynopsis>
  55   </refsynopsisdiv>
  56
  57   <refsect1>
  58     <title>Description</title>
  59
  60     <para><function>sd_journal_add_match()</function> adds a match by
  61     which to filter the entries of the journal file. Matches applied
  62     with this call will filter what can be iterated through and read
  63     from the journal file via calls like
  64     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  65     and
  66     <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  67     Parameter <parameter>data</parameter> must be of the form
  68     <literal><replaceable>FIELD</replaceable>=<replaceable>value</replaceable></literal>,
  69     where the <replaceable>FIELD</replaceable> part is a short uppercase string consisting only
  70     of 0–9, A–Z and the underscore; it may not begin with two underscores or be the empty
  71     string. The <replaceable>value</replaceable> part may be anything, including binary. Parameter
  72     <parameter>size</parameter> specifies the number of bytes in <parameter>data</parameter>
  73     (i.e. the length of <replaceable>FIELD</replaceable>, plus one, plus the length of
  74     <replaceable>value</replaceable>). Parameter <parameter>size</parameter> may also be
  75     specified as <constant>0</constant>, in which case <parameter>data</parameter>
  76     must be a <constant>NUL</constant>-terminated string, and the bytes before the terminating
  77     zero are used as the match.</para>
  78
  79     <para>If a match is applied, only entries with this field set
  80     will be iterated. Multiple matches may be active at the same time:
  81     If they apply to different fields, only entries with both fields
  82     set like this will be iterated. If they apply to the same fields,
  83     only entries where the field takes one of the specified values
  84     will be iterated. Well known fields are documented in
  85     <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
  86     Whenever a new match is added the current entry position is reset,
  87     and
  88     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  89     (or a similar call) needs to be called before entries can be read
  90     again.</para>
  91
  92     <para><function>sd_journal_add_disjunction()</function> may be
  93     used to insert a disjunction (i.e. logical OR) in the match list.
  94     If this call is invoked, all previously added matches since the
  95     last invocation of
  96     <function>sd_journal_add_disjunction()</function> or
  97     <function>sd_journal_add_conjunction()</function> are combined in
  98     an OR with all matches added afterwards, until
  99     <function>sd_journal_add_disjunction()</function> or
 100     <function>sd_journal_add_conjunction()</function> is invoked again
 101     to begin the next OR or AND term. </para>
 102
 103     <para><function>sd_journal_add_conjunction()</function> may be
 104     used to insert a conjunction (i.e. logical AND) in the match list.
 105     If this call is invoked, all previously added matches since the
 106     last invocation of
 107     <function>sd_journal_add_conjunction()</function> are combined in
 108     an AND with all matches added afterwards, until
 109     <function>sd_journal_add_conjunction()</function> is invoked again
 110     to begin the next AND term. The combination of
 111     <function>sd_journal_add_match()</function>,
 112     <function>sd_journal_add_disjunction()</function> and
 113     <function>sd_journal_add_conjunction()</function> may be used to
 114     build complex search terms, even though full logical expressions
 115     are not available. Note that
 116     <function>sd_journal_add_conjunction()</function> operates one
 117     level 'higher' than
 118     <function>sd_journal_add_disjunction()</function>. It is hence
 119     possible to build an expression of AND terms, consisting of OR
 120     terms, consisting of AND terms, consisting of OR terms of matches
 121     (the latter OR expression is implicitly created for matches with
 122     the same field name, see above).</para>
 123
 124     <para><function>sd_journal_flush_matches()</function> may be used
 125     to flush all matches, disjunction and conjunction terms again.
 126     After this call all filtering is removed and all entries in the
 127     journal will be iterated again.</para>
 128
 129     <para>Note that filtering via matches only applies to the way the
 130     journal is read, it has no effect on storage on disk.</para>
 131   </refsect1>
 132
 133   <refsect1>
 134     <title>Return Value</title>
 135
 136     <para><function>sd_journal_add_match()</function>,
 137     <function>sd_journal_add_disjunction()</function> and
 138     <function>sd_journal_add_conjunction()</function>
 139     return 0 on success or a negative errno-style error
 140     code. <function>sd_journal_flush_matches()</function>
 141     returns nothing.</para>
 142   </refsect1>
 143
 144   <xi:include href="libsystemd-pkgconfig.xml" />
 145
 146   <refsect1>
 147     <title>Examples</title>
 148
 149     <para>The following example adds matches to a journal context
 150     object to iterate only through messages generated by the Avahi
 151     service at the four error log levels, plus all messages of the
 152     message ID 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any
 153     service (this example lacks the necessary error checking):</para>
 154
 155     <programlisting>…
 156 int add_matches(sd_journal *j) {
 157   sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0);
 158   sd_journal_add_match(j, "PRIORITY=0", 0);
 159   sd_journal_add_match(j, "PRIORITY=1", 0);
 160   sd_journal_add_match(j, "PRIORITY=2", 0);
 161   sd_journal_add_match(j, "PRIORITY=3", 0);
 162   sd_journal_add_disjunction(j);
 163   sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0);
 164 }</programlisting>
 165   </refsect1>
 166
 167   <refsect1>
 168     <title>See Also</title>
 169
 170     <para>
 171       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 172       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 173       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 174       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 175       <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 177     </para>
 178   </refsect1>
 179
 180 </refentry>