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