1<?xml version='1.0'?> <!--*-nxml-*--> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_journal_add_match" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_journal_add_match</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_journal_add_match</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_journal_add_match</refname> 20 <refname>sd_journal_add_disjunction</refname> 21 <refname>sd_journal_add_conjunction</refname> 22 <refname>sd_journal_flush_matches</refname> 23 <refpurpose>Add or remove entry matches</refpurpose> 24 </refnamediv> 25 26 <refsynopsisdiv> 27 <funcsynopsis> 28 <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> 29 30 <funcprototype> 31 <funcdef>int <function>sd_journal_add_match</function></funcdef> 32 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 33 <paramdef>const void *<parameter>data</parameter></paramdef> 34 <paramdef>size_t <parameter>size</parameter></paramdef> 35 </funcprototype> 36 37 <funcprototype> 38 <funcdef>int <function>sd_journal_add_disjunction</function></funcdef> 39 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 40 </funcprototype> 41 42 <funcprototype> 43 <funcdef>int <function>sd_journal_add_conjunction</function></funcdef> 44 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 45 </funcprototype> 46 47 <funcprototype> 48 <funcdef>void <function>sd_journal_flush_matches</function></funcdef> 49 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 50 </funcprototype> 51 </funcsynopsis> 52 </refsynopsisdiv> 53 54 <refsect1> 55 <title>Description</title> 56 57 <para><function>sd_journal_add_match()</function> adds a match by 58 which to filter the entries of the journal file. Matches applied 59 with this call will filter what can be iterated through and read 60 from the journal file via calls like 61 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> 62 and 63 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 64 Parameter <parameter>data</parameter> must be of the form 65 <literal><replaceable>FIELD</replaceable>=<replaceable>value</replaceable></literal>, 66 where the <replaceable>FIELD</replaceable> part is a short uppercase string consisting only 67 of 0–9, A–Z and the underscore; it may not begin with two underscores or be the empty 68 string. The <replaceable>value</replaceable> part may be anything, including binary. Parameter 69 <parameter>size</parameter> specifies the number of bytes in <parameter>data</parameter> 70 (i.e. the length of <replaceable>FIELD</replaceable>, plus one, plus the length of 71 <replaceable>value</replaceable>). Parameter <parameter>size</parameter> may also be 72 specified as <constant>0</constant>, in which case <parameter>data</parameter> 73 must be a <constant>NUL</constant>-terminated string, and the bytes before the terminating 74 zero are used as the match.</para> 75 76 <para>If a match is applied, only entries with this field set 77 will be iterated. Multiple matches may be active at the same time: 78 If they apply to different fields, only entries with both fields 79 set like this will be iterated. If they apply to the same fields, 80 only entries where the field takes one of the specified values 81 will be iterated. Well known fields are documented in 82 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. 83 Whenever a new match is added the current entry position is reset, 84 and 85 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> 86 (or a similar call) needs to be called before entries can be read 87 again.</para> 88 89 <para><function>sd_journal_add_disjunction()</function> may be 90 used to insert a disjunction (i.e. logical OR) in the match list. 91 If this call is invoked, all previously added matches since the 92 last invocation of 93 <function>sd_journal_add_disjunction()</function> or 94 <function>sd_journal_add_conjunction()</function> are combined in 95 an OR with all matches added afterwards, until 96 <function>sd_journal_add_disjunction()</function> or 97 <function>sd_journal_add_conjunction()</function> is invoked again 98 to begin the next OR or AND term. </para> 99 100 <para><function>sd_journal_add_conjunction()</function> may be 101 used to insert a conjunction (i.e. logical AND) in the match list. 102 If this call is invoked, all previously added matches since the 103 last invocation of 104 <function>sd_journal_add_conjunction()</function> are combined in 105 an AND with all matches added afterwards, until 106 <function>sd_journal_add_conjunction()</function> is invoked again 107 to begin the next AND term. The combination of 108 <function>sd_journal_add_match()</function>, 109 <function>sd_journal_add_disjunction()</function> and 110 <function>sd_journal_add_conjunction()</function> may be used to 111 build complex search terms, even though full logical expressions 112 are not available. Note that 113 <function>sd_journal_add_conjunction()</function> operates one 114 level 'higher' than 115 <function>sd_journal_add_disjunction()</function>. It is hence 116 possible to build an expression of AND terms, consisting of OR 117 terms, consisting of AND terms, consisting of OR terms of matches 118 (the latter OR expression is implicitly created for matches with 119 the same field name, see above).</para> 120 121 <para><function>sd_journal_flush_matches()</function> may be used 122 to flush all matches, disjunction and conjunction terms again. 123 After this call all filtering is removed and all entries in the 124 journal will be iterated again.</para> 125 126 <para>Note that filtering via matches only applies to the way the 127 journal is read, it has no effect on storage on disk.</para> 128 </refsect1> 129 130 <refsect1> 131 <title>Return Value</title> 132 133 <para><function>sd_journal_add_match()</function>, 134 <function>sd_journal_add_disjunction()</function> and 135 <function>sd_journal_add_conjunction()</function> 136 return 0 on success or a negative errno-style error 137 code. <function>sd_journal_flush_matches()</function> 138 returns nothing.</para> 139 </refsect1> 140 141 <xi:include href="libsystemd-pkgconfig.xml" /> 142 143 <refsect1> 144 <title>Examples</title> 145 146 <para>The following example adds matches to a journal context 147 object to iterate only through messages generated by the Avahi 148 service at the four error log levels, plus all messages of the 149 message ID 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any 150 service (this example lacks the necessary error checking):</para> 151 152 <programlisting>… 153int add_matches(sd_journal *j) { 154 sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0); 155 sd_journal_add_match(j, "PRIORITY=0", 0); 156 sd_journal_add_match(j, "PRIORITY=1", 0); 157 sd_journal_add_match(j, "PRIORITY=2", 0); 158 sd_journal_add_match(j, "PRIORITY=3", 0); 159 sd_journal_add_disjunction(j); 160 sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0); 161}</programlisting> 162 </refsect1> 163 164 <refsect1> 165 <title>See Also</title> 166 167 <para> 168 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 169 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 170 <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 171 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 172 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 173 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> 174 </para> 175 </refsect1> 176 177</refentry> 178