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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2012 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="sd_journal_add_match">
  28
  29   <refentryinfo>
  30     <title>sd_journal_add_match</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>sd_journal_add_match</refentrytitle>
  45     <manvolnum>3</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>sd_journal_add_match</refname>
  50     <refname>sd_journal_add_disjunction</refname>
  51     <refname>sd_journal_add_conjunction</refname>
  52     <refname>sd_journal_flush_matches</refname>
  53     <refpurpose>Add or remove entry matches</refpurpose>
  54   </refnamediv>
  55
  56   <refsynopsisdiv>
  57     <funcsynopsis>
  58       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_journal_add_match</function></funcdef>
  62         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  63         <paramdef>const void *<parameter>data</parameter></paramdef>
  64         <paramdef>size_t <parameter>size</parameter></paramdef>
  65       </funcprototype>
  66
  67       <funcprototype>
  68         <funcdef>int <function>sd_journal_add_disjunction</function></funcdef>
  69         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  70       </funcprototype>
  71
  72       <funcprototype>
  73         <funcdef>int <function>sd_journal_add_conjunction</function></funcdef>
  74         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  75       </funcprototype>
  76
  77       <funcprototype>
  78         <funcdef>void <function>sd_journal_flush_matches</function></funcdef>
  79         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  80       </funcprototype>
  81     </funcsynopsis>
  82   </refsynopsisdiv>
  83
  84   <refsect1>
  85     <title>Description</title>
  86
  87     <para><function>sd_journal_add_match()</function> adds a match by
  88     which to filter the entries of the journal file. Matches applied
  89     with this call will filter what can be iterated through and read
  90     from the journal file via calls like
  91     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  92     and
  93     <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  94     Matches are of the form <literal>FIELD=value</literal>, where the
  95     field part is a short uppercase string consisting only of 0-9, A-Z
  96     and the underscore. It may not begin with two underscores or be
  97     the empty string. The value part may be any value, including
  98     binary. If a match is applied, only entries with this field set
  99     will be iterated. Multiple matches may be active at the same time:
 100     If they apply to different fields, only entries with both fields
 101     set like this will be iterated. If they apply to the same fields,
 102     only entries where the field takes one of the specified values
 103     will be iterated. Well known fields are documented in
 104     <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 105     Whenever a new match is added the current entry position is reset,
 106     and
 107     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 108     (or a similar call) needs to be called before entries can be read
 109     again.</para>
 110
 111     <para><function>sd_journal_add_disjunction()</function> may be
 112     used to insert a disjunction (i.e. logical OR) in the match list.
 113     If this call is invoked, all previously added matches since the
 114     last invocation of
 115     <function>sd_journal_add_disjunction()</function> or
 116     <function>sd_journal_add_conjunction()</function> are combined in
 117     an OR with all matches added afterwards, until
 118     <function>sd_journal_add_disjunction()</function> or
 119     <function>sd_journal_add_conjunction()</function> is invoked again
 120     to begin the next OR or AND term. </para>
 121
 122     <para><function>sd_journal_add_conjunction()</function> may be
 123     used to insert a conjunction (i.e. logical AND) in the match list.
 124     If this call is invoked, all previously added matches since the
 125     last invocation of
 126     <function>sd_journal_add_conjunction()</function> are combined in
 127     an AND with all matches added afterwards, until
 128     <function>sd_journal_add_conjunction()</function> is invoked again
 129     to begin the next AND term. The combination of
 130     <function>sd_journal_add_match()</function>,
 131     <function>sd_journal_add_disjunction()</function> and
 132     <function>sd_journal_add_conjunction()</function> may be used to
 133     build complex search terms, even though full logical expressions
 134     are not available. Note that
 135     <function>sd_journal_add_conjunction()</function> operates one
 136     level 'higher' than
 137     <function>sd_journal_add_disjunction()</function>. It is hence
 138     possible to build an expression of AND terms, consisting of OR
 139     terms, consisting of AND terms, consisting of OR terms of matches
 140     (the latter OR expression is implicitly created for matches with
 141     the same field name, see above).</para>
 142
 143     <para><function>sd_journal_flush_matches()</function> may be used
 144     to flush all matches, disjunction and conjunction terms again.
 145     After this call all filtering is removed and all entries in the
 146     journal will be iterated again.</para>
 147
 148     <para>Note that filtering via matches only applies to the way the
 149     journal is read, it has no effect on storage on disk.</para>
 150   </refsect1>
 151
 152   <refsect1>
 153     <title>Return Value</title>
 154
 155     <para><function>sd_journal_add_match()</function>,
 156     <function>sd_journal_add_disjunction()</function> and
 157     <function>sd_journal_add_conjunction()</function>
 158     return 0 on success or a negative errno-style error
 159     code. <function>sd_journal_flush_matches()</function>
 160     returns nothing.</para>
 161   </refsect1>
 162
 163   <refsect1>
 164     <title>Notes</title>
 165
 166     <para>The <function>sd_journal_add_match()</function>,
 167     <function>sd_journal_add_disjunction()</function>,
 168     <function>sd_journal_add_conjunction()</function> and
 169     <function>sd_journal_flush_matches()</function>
 170     interfaces are available as a shared library, which can
 171     be compiled and linked to with the
 172     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 173     file.</para>
 174   </refsect1>
 175
 176   <refsect1>
 177     <title>Examples</title>
 178
 179     <para>The following example adds matches to a journal context
 180     object to iterate only through messages generated by the Avahi
 181     service at the four error log levels, plus all messages of the
 182     message ID 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any
 183     service (this example lacks the necessary error checking):</para>
 184
 185     <programlisting>...
 186 int add_matches(sd_journal *j) {
 187   sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0);
 188   sd_journal_add_match(j, "PRIORITY=0", 0);
 189   sd_journal_add_match(j, "PRIORITY=1", 0);
 190   sd_journal_add_match(j, "PRIORITY=2", 0);
 191   sd_journal_add_match(j, "PRIORITY=3", 0);
 192   sd_journal_add_disjunction(j);
 193   sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0);
 194 }</programlisting>
 195
 196   </refsect1>
 197
 198   <refsect1>
 199     <title>See Also</title>
 200
 201     <para>
 202       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 203       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 204       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 205       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 206       <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 207       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 208     </para>
 209   </refsect1>
 210
 211 </refentry>