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   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2012 Lennart Poettering
  11 -->
  12
  13 <refentry id="sd_journal_add_match">
  14
  15   <refentryinfo>
  16     <title>sd_journal_add_match</title>
  17     <productname>systemd</productname>
  18
  19     <authorgroup>
  20       <author>
  21         <contrib>Developer</contrib>
  22         <firstname>Lennart</firstname>
  23         <surname>Poettering</surname>
  24         <email>lennart@poettering.net</email>
  25       </author>
  26     </authorgroup>
  27   </refentryinfo>
  28
  29   <refmeta>
  30     <refentrytitle>sd_journal_add_match</refentrytitle>
  31     <manvolnum>3</manvolnum>
  32   </refmeta>
  33
  34   <refnamediv>
  35     <refname>sd_journal_add_match</refname>
  36     <refname>sd_journal_add_disjunction</refname>
  37     <refname>sd_journal_add_conjunction</refname>
  38     <refname>sd_journal_flush_matches</refname>
  39     <refpurpose>Add or remove entry matches</refpurpose>
  40   </refnamediv>
  41
  42   <refsynopsisdiv>
  43     <funcsynopsis>
  44       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  45
  46       <funcprototype>
  47         <funcdef>int <function>sd_journal_add_match</function></funcdef>
  48         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  49         <paramdef>const void *<parameter>data</parameter></paramdef>
  50         <paramdef>size_t <parameter>size</parameter></paramdef>
  51       </funcprototype>
  52
  53       <funcprototype>
  54         <funcdef>int <function>sd_journal_add_disjunction</function></funcdef>
  55         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  56       </funcprototype>
  57
  58       <funcprototype>
  59         <funcdef>int <function>sd_journal_add_conjunction</function></funcdef>
  60         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>void <function>sd_journal_flush_matches</function></funcdef>
  65         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  66       </funcprototype>
  67     </funcsynopsis>
  68   </refsynopsisdiv>
  69
  70   <refsect1>
  71     <title>Description</title>
  72
  73     <para><function>sd_journal_add_match()</function> adds a match by
  74     which to filter the entries of the journal file. Matches applied
  75     with this call will filter what can be iterated through and read
  76     from the journal file via calls like
  77     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  78     and
  79     <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  80     Parameter <parameter>data</parameter> must be of the form
  81     <literal><replaceable>FIELD</replaceable>=<replaceable>value</replaceable></literal>,
  82     where the <replaceable>FIELD</replaceable> part is a short uppercase string consisting only
  83     of 0–9, A–Z and the underscore; it may not begin with two underscores or be the empty
  84     string. The <replaceable>value</replaceable> part may be anything, including binary. Parameter
  85     <parameter>size</parameter> specifies the number of bytes in <parameter>data</parameter>
  86     (i.e. the length of <replaceable>FIELD</replaceable>, plus one, plus the length of
  87     <replaceable>value</replaceable>). Parameter <parameter>size</parameter> may also be
  88     specified as <constant>0</constant>, in which case <parameter>data</parameter>
  89     must be a <constant>NUL</constant>-terminated string, and the bytes before the terminating
  90     zero are used as the match.</para>
  91
  92     <para>If a match is applied, only entries with this field set
  93     will be iterated. Multiple matches may be active at the same time:
  94     If they apply to different fields, only entries with both fields
  95     set like this will be iterated. If they apply to the same fields,
  96     only entries where the field takes one of the specified values
  97     will be iterated. Well known fields are documented in
  98     <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
  99     Whenever a new match is added the current entry position is reset,
 100     and
 101     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 102     (or a similar call) needs to be called before entries can be read
 103     again.</para>
 104
 105     <para><function>sd_journal_add_disjunction()</function> may be
 106     used to insert a disjunction (i.e. logical OR) in the match list.
 107     If this call is invoked, all previously added matches since the
 108     last invocation of
 109     <function>sd_journal_add_disjunction()</function> or
 110     <function>sd_journal_add_conjunction()</function> are combined in
 111     an OR with all matches added afterwards, until
 112     <function>sd_journal_add_disjunction()</function> or
 113     <function>sd_journal_add_conjunction()</function> is invoked again
 114     to begin the next OR or AND term. </para>
 115
 116     <para><function>sd_journal_add_conjunction()</function> may be
 117     used to insert a conjunction (i.e. logical AND) in the match list.
 118     If this call is invoked, all previously added matches since the
 119     last invocation of
 120     <function>sd_journal_add_conjunction()</function> are combined in
 121     an AND with all matches added afterwards, until
 122     <function>sd_journal_add_conjunction()</function> is invoked again
 123     to begin the next AND term. The combination of
 124     <function>sd_journal_add_match()</function>,
 125     <function>sd_journal_add_disjunction()</function> and
 126     <function>sd_journal_add_conjunction()</function> may be used to
 127     build complex search terms, even though full logical expressions
 128     are not available. Note that
 129     <function>sd_journal_add_conjunction()</function> operates one
 130     level 'higher' than
 131     <function>sd_journal_add_disjunction()</function>. It is hence
 132     possible to build an expression of AND terms, consisting of OR
 133     terms, consisting of AND terms, consisting of OR terms of matches
 134     (the latter OR expression is implicitly created for matches with
 135     the same field name, see above).</para>
 136
 137     <para><function>sd_journal_flush_matches()</function> may be used
 138     to flush all matches, disjunction and conjunction terms again.
 139     After this call all filtering is removed and all entries in the
 140     journal will be iterated again.</para>
 141
 142     <para>Note that filtering via matches only applies to the way the
 143     journal is read, it has no effect on storage on disk.</para>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>Return Value</title>
 148
 149     <para><function>sd_journal_add_match()</function>,
 150     <function>sd_journal_add_disjunction()</function> and
 151     <function>sd_journal_add_conjunction()</function>
 152     return 0 on success or a negative errno-style error
 153     code. <function>sd_journal_flush_matches()</function>
 154     returns nothing.</para>
 155   </refsect1>
 156
 157   <refsect1>
 158     <title>Notes</title>
 159
 160     <para>All functions listed here are thread-agnostic and only a single thread may operate
 161     on a given <structname>sd_journal</structname> object.</para>
 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>