man/sd_journal_add_match.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_journal_add_match</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21   <a href="../libudev/index.html">libudev </a>·
  22   <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 204</span><hr><div class="refentry"><a name="sd_journal_add_match"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_journal_add_match, sd_journal_add_disjunction, sd_journal_add_conjunction, sd_journal_flush_matches — Add or remove entry matches</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;systemd/sd-journal.h&gt;</pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_add_match</b>(</code></td><td>sd_journal* <var class="pdparam">j</var>, </td></tr><tr><td> </td><td>const void* <var class="pdparam">data</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_add_disjunction</b>(</code></td><td>sd_journal* <var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_add_conjunction</b>(</code></td><td>sd_journal* <var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">sd_journal_flush_matches</b>(</code></td><td>sd_journal* <var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm259780241840"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><code class="function">sd_journal_add_match()</code> adds
  23                 a match by which to filter the entries of the journal
  24                 file. Matches applied with this call will filter what
  25                 can be iterated through and read from the journal file
  26                 via calls like
  27                 <a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>
  28                 and
  29                 <a href="sd_journal_get_data.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_data</span>(3)</span></a>. Matches
  30                 are of the form <code class="literal">FIELD=value</code>, where
  31                 the field part is a short uppercase string consisting
  32                 only of 0-9, A-Z and the underscore. It may not begin
  33                 with two underscores or be the empty string. The value
  34                 part may be any value, including binary. If a match is
  35                 applied only entries with this field set will be
  36                 iterated. Multiple matches may be active at the same
  37                 time: if they apply to different fields only entries
  38                 with both fields set like this will be iterated, if
  39                 they apply to the same fields only entries where the
  40                 field takes one of the specified values will be
  41                 iterated. Well known fields are documented in
  42                 <a href="systemd.journal-fields.html"><span class="citerefentry"><span class="refentrytitle">systemd.journal-fields</span>(7)</span></a>. Whenever
  43                 a new match is added the current entry position is
  44                 reset, and
  45                 <a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a> (or a similar call)
  46                 needs to be called before entries can be read
  47                 again.</p><p><code class="function">sd_journal_add_disjunction()</code>
  48                 may be used to insert a disjunction (i.e. logical OR)
  49                 in the match list. If this call is invoked all
  50                 previously added matches since the last invocation of
  51                 <code class="function">sd_journal_add_disjunction()</code> or
  52                 <code class="function">sd_journal_add_conjunction()</code> are
  53                 combined in an OR with all matches added afterwards,
  54                 until
  55                 <code class="function">sd_journal_add_disjunction()</code> or
  56                 <code class="function">sd_journal_add_conjunction()</code> is
  57                 invoked again to begin the next OR or AND
  58                 term. </p><p><code class="function">sd_journal_add_conjunction()</code>
  59                 may be used to insert a conjunction (i.e. logical AND)
  60                 in the match list. If this call is invoked all
  61                 previously added matches since the last invocation of
  62                 <code class="function">sd_journal_add_conjunction()</code> are
  63                 combined in an AND with all matches added afterwards,
  64                 until
  65                 <code class="function">sd_journal_add_conjunction()</code> is
  66                 invoked again to begin the next AND term. The
  67                 combination of
  68                 <code class="function">sd_journal_add_match()</code>,
  69                 <code class="function">sd_journal_add_disjunction()</code> and
  70                 <code class="function">sd_journal_add_conjunction()</code> may
  71                 be used to build complex search terms, even though
  72                 full logical expressions are not available. Note that
  73                 <code class="function">sd_journal_add_conjunction()</code>
  74                 operates one level 'higher' than
  75                 <code class="function">sd_journal_add_disjunction()</code>. It
  76                 is hence possible to build an expression of AND terms,
  77                 consisting of OR terms, consisting of AND terms,
  78                 consisting of OR terms of matches (the latter OR
  79                 expression is implicitly created for matches with the
  80                 same field name, see above).</p><p><code class="function">sd_journal_flush_matches()</code>
  81                 may be used to flush all matches, disjunction and
  82                 conjunction terms again. After this call all filtering
  83                 is removed and all entries in the journal will be
  84                 iterated again.</p><p>Note that filtering via matches only applies to
  85                 the way the journal is read, it has no effect on storage
  86                 on disk.</p></div><div class="refsect1"><a name="idm259784119376"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value">¶</a></h2><p><code class="function">sd_journal_add_match()</code>,
  87                 <code class="function">sd_journal_add_disjunction()</code> and
  88                 <code class="function">sd_journal_add_conjunction()</code>
  89                 return 0 on success or a negative errno-style error
  90                 code. <code class="function">sd_journal_flush_matches()</code>
  91                 returns nothing.</p></div><div class="refsect1"><a name="idm259784115328"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p>The <code class="function">sd_journal_add_match()</code>,
  92                 <code class="function">sd_journal_add_disjunction()</code>,
  93                 <code class="function">sd_journal_add_conjunction()</code> and
  94                 <code class="function">sd_journal_flush_matches()</code>
  95                 interfaces are available as shared library, which can
  96                 be compiled and linked to with the
  97                 <code class="literal">libsystemd-journal</code>
  98                 <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
  99                 file.</p></div><div class="refsect1"><a name="idm259784109488"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><p>The following example adds matches to a journal
 100                 context object to iterate only through messages
 101                 generated by the Avahi service at the four error log
 102                 levels, plus all messages of the message ID
 103                 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any
 104                 service (this example lacks the necessary error
 105                 checking):</p><pre class="programlisting">...
 106 int add_matches(sd_journal *j) {
 107         sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0);
 108         sd_journal_add_match(j, "PRIORITY=0", 0);
 109         sd_journal_add_match(j, "PRIORITY=1", 0);
 110         sd_journal_add_match(j, "PRIORITY=2", 0);
 111         sd_journal_add_match(j, "PRIORITY=3", 0);
 112         sd_journal_add_disjunction(j);
 113         sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0);
 114 }</pre></div><div class="refsect1"><a name="idm259784106784"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
 115                         <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
 116                         <a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
 117                         <a href="sd_journal_open.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_open</span>(3)</span></a>,
 118                         <a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>,
 119                         <a href="sd_journal_get_data.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_data</span>(3)</span></a>,
 120                         <a href="systemd.journal-fields.html"><span class="citerefentry"><span class="refentrytitle">systemd.journal-fields</span>(7)</span></a>
 121                 </p></div></div></body></html>