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
  85                 a match by which to filter the entries of the journal
  86                 file. Matches applied with this call will filter what
  87                 can be iterated through and read from the journal file
  88                 via calls like
  89                 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  90                 and
  91                 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Matches
  92                 are of the form <literal>FIELD=value</literal>, where
  93                 the field part is a short uppercase string consisting
  94                 only of 0-9, A-Z and the underscore. It may not begin
  95                 with two underscores or be the empty string. The value
  96                 part may be any value, including binary. If a match is
  97                 applied, only entries with this field set will be
  98                 iterated. Multiple matches may be active at the same
  99                 time: If they apply to different fields, only entries
 100                 with both fields set like this will be iterated. If
 101                 they apply to the same fields, only entries where the
 102                 field takes one of the specified values will be
 103                 iterated. Well known fields are documented in
 104                 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Whenever
 105                 a new match is added the current entry position is
 106                 reset, and
 107                 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> (or a similar call)
 108                 needs to be called before entries can be read
 109                 again.</para>
 110
 111                 <para><function>sd_journal_add_disjunction()</function>
 112                 may be used to insert a disjunction (i.e. logical OR)
 113                 in the match list. If this call is invoked, all
 114                 previously added matches since the last invocation of
 115                 <function>sd_journal_add_disjunction()</function> or
 116                 <function>sd_journal_add_conjunction()</function> are
 117                 combined in an OR with all matches added afterwards,
 118                 until
 119                 <function>sd_journal_add_disjunction()</function> or
 120                 <function>sd_journal_add_conjunction()</function> is
 121                 invoked again to begin the next OR or AND
 122                 term. </para>
 123
 124                 <para><function>sd_journal_add_conjunction()</function>
 125                 may be used to insert a conjunction (i.e. logical AND)
 126                 in the match list. If this call is invoked, all
 127                 previously added matches since the last invocation of
 128                 <function>sd_journal_add_conjunction()</function> are
 129                 combined in an AND with all matches added afterwards,
 130                 until
 131                 <function>sd_journal_add_conjunction()</function> is
 132                 invoked again to begin the next AND term. The
 133                 combination of
 134                 <function>sd_journal_add_match()</function>,
 135                 <function>sd_journal_add_disjunction()</function> and
 136                 <function>sd_journal_add_conjunction()</function> may
 137                 be used to build complex search terms, even though
 138                 full logical expressions are not available. Note that
 139                 <function>sd_journal_add_conjunction()</function>
 140                 operates one level 'higher' than
 141                 <function>sd_journal_add_disjunction()</function>. It
 142                 is hence possible to build an expression of AND terms,
 143                 consisting of OR terms, consisting of AND terms,
 144                 consisting of OR terms of matches (the latter OR
 145                 expression is implicitly created for matches with the
 146                 same field name, see above).</para>
 147
 148                 <para><function>sd_journal_flush_matches()</function>
 149                 may be used to flush all matches, disjunction and
 150                 conjunction terms again. After this call all filtering
 151                 is removed and all entries in the journal will be
 152                 iterated again.</para>
 153
 154                 <para>Note that filtering via matches only applies to
 155                 the way the journal is read, it has no effect on storage
 156                 on disk.</para>
 157         </refsect1>
 158
 159         <refsect1>
 160                 <title>Return Value</title>
 161
 162                 <para><function>sd_journal_add_match()</function>,
 163                 <function>sd_journal_add_disjunction()</function> and
 164                 <function>sd_journal_add_conjunction()</function>
 165                 return 0 on success or a negative errno-style error
 166                 code. <function>sd_journal_flush_matches()</function>
 167                 returns nothing.</para>
 168         </refsect1>
 169
 170         <refsect1>
 171                 <title>Notes</title>
 172
 173                 <para>The <function>sd_journal_add_match()</function>,
 174                 <function>sd_journal_add_disjunction()</function>,
 175                 <function>sd_journal_add_conjunction()</function> and
 176                 <function>sd_journal_flush_matches()</function>
 177                 interfaces are available as a shared library, which can
 178                 be compiled and linked to with the
 179                 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 180                 file.</para>
 181         </refsect1>
 182
 183         <refsect1>
 184                 <title>Examples</title>
 185
 186                 <para>The following example adds matches to a journal
 187                 context object to iterate only through messages
 188                 generated by the Avahi service at the four error log
 189                 levels, plus all messages of the message ID
 190                 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any
 191                 service (this example lacks the necessary error
 192                 checking):</para>
 193
 194                 <programlisting>...
 195 int add_matches(sd_journal *j) {
 196         sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0);
 197         sd_journal_add_match(j, "PRIORITY=0", 0);
 198         sd_journal_add_match(j, "PRIORITY=1", 0);
 199         sd_journal_add_match(j, "PRIORITY=2", 0);
 200         sd_journal_add_match(j, "PRIORITY=3", 0);
 201         sd_journal_add_disjunction(j);
 202         sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0);
 203 }</programlisting>
 204
 205         </refsect1>
 206
 207         <refsect1>
 208                 <title>See Also</title>
 209
 210                 <para>
 211                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 212                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 213                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 214                         <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 215                         <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 216                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 217                 </para>
 218         </refsect1>
 219
 220 </refentry>