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_flush_matches</refname>
  49                 <refpurpose>Add or remove entry matches</refpurpose>
  50         </refnamediv>
  51
  52         <refsynopsisdiv>
  53                 <funcsynopsis>
  54                         <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  55
  56                         <funcprototype>
  57                                 <funcdef>int <function>sd_journal_add_match</function></funcdef>
  58                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  59                                 <paramdef>const void* <parameter>data</parameter></paramdef>
  60                                 <paramdef>size_t <parameter>size</parameter></paramdef>
  61                         </funcprototype>
  62
  63                         <funcprototype>
  64                                 <funcdef>int <function>sd_journal_add_disjunction</function></funcdef>
  65                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  66                         </funcprototype>
  67
  68                         <funcprototype>
  69                                 <funcdef>void <function>sd_journal_flush_matches</function></funcdef>
  70                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  71                         </funcprototype>
  72                 </funcsynopsis>
  73         </refsynopsisdiv>
  74
  75         <refsect1>
  76                 <title>Description</title>
  77
  78                 <para><function>sd_journal_add_match()</function> adds
  79                 a match by which to filter the entries of the journal
  80                 file. Matches applied with this call will filter what
  81                 can be iterated through and read from the journal file
  82                 via calls like
  83                 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  84                 and
  85                 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Matches
  86                 are of the form <literal>FIELD=value</literal>, where
  87                 the field part is a short uppercase string consisting
  88                 only of 0-9, A-Z and the underscore. It may not begin
  89                 with two underscores or be the empty string. The value
  90                 part may be any value, including binary. If a match is
  91                 applied only entries with this field set will be
  92                 iterated. Multiple matches may be active at the same
  93                 time: if they apply to different fields only entries
  94                 with both fields set like this will be iterated, if
  95                 they apply to the same fields only entries where the
  96                 field takes one of the specified values will be
  97                 iterated. Well known fields are documented in
  98                 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Whenever
  99                 a new match is added the current entry position is
 100                 reset, and
 101                 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> (or a similar call)
 102                 needs to be called before entries can be read
 103                 again.</para>
 104
 105                 <para><function>sd_journal_add_disjunction()</function>
 106                 may be used to insert a disjunction (i.e. logical OR)
 107                 in the match list. If this call is invoked all
 108                 previously added matches are combined in an OR with
 109                 all matches added afterwards, until
 110                 <function>sd_journal_add_disjunction()</function> is
 111                 invoked again to begin the next OR term. The
 112                 combination of
 113                 <function>sd_journal_add_match()</function> and
 114                 <function>sd_journal_add_disjunction()</function> may
 115                 be used to build complex search terms, even though
 116                 full logical expressions are not available.</para>
 117
 118                 <para><function>sd_journal_flush_matches()</function>
 119                 may be used to flush all matches and disjunction terms
 120                 again. After this call all filtering is removed and
 121                 all entries in the journal will be iterated
 122                 again.</para>
 123
 124                 <para>Note that filtering via matches only applies to
 125                 the way the journal is read, it has no effect on storage
 126                 on disk.</para>
 127         </refsect1>
 128
 129         <refsect1>
 130                 <title>Return Value</title>
 131
 132                 <para><function>sd_journal_add_match()</function> and
 133                 <function>sd_journal_add_disjunction()</function>
 134                 return 0 on success or a negative errno-style error
 135                 code. <function>sd_journal_flush_matches()</function>
 136                 returns nothing.</para>
 137         </refsect1>
 138
 139         <refsect1>
 140                 <title>Notes</title>
 141
 142                 <para>The <function>sd_journal_add_match()</function>,
 143                 <function>sd_journal_add_disjunction()</function> and
 144                 <function>sd_journal_flush_matches()</function> interfaces are
 145                 available as shared library, which can be compiled and
 146                 linked to with the
 147                 <literal>libsystemd-journal</literal>
 148                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 149                 file.</para>
 150         </refsect1>
 151
 152         <refsect1>
 153                 <title>Examples</title>
 154
 155                 <para>The following example adds matches to a journal
 156                 context object to iterate only through messages
 157                 generated by the Avahi service at the four error log
 158                 levels, plus all messages of the message ID
 159                 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any
 160                 service (this example lacks the necessary error
 161                 checking):</para>
 162
 163                 <programlisting>...
 164 int add_matches(sd_journal *j) {
 165         sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0);
 166         sd_journal_add_match(j, "PRIORITY=0", 0);
 167         sd_journal_add_match(j, "PRIORITY=1", 0);
 168         sd_journal_add_match(j, "PRIORITY=2", 0);
 169         sd_journal_add_match(j, "PRIORITY=3", 0);
 170         sd_journal_add_disjunction(j);
 171         sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0);
 172 }</programlisting>
 173
 174         </refsect1>
 175
 176         <refsect1>
 177                 <title>See Also</title>
 178
 179                 <para>
 180                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 181                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 182                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 183                         <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 184                         <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 185                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 186                 </para>
 187         </refsect1>
 188
 189 </refentry>