man/sd_journal_add_match.xml

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