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">
6 This file is part of systemd.
8 Copyright 2012 Lennart Poettering
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.
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.
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/>.
24 <refentry id=
"sd_journal_add_match">
27 <title>sd_journal_add_match
</title>
28 <productname>systemd
</productname>
32 <contrib>Developer
</contrib>
33 <firstname>Lennart
</firstname>
34 <surname>Poettering
</surname>
35 <email>lennart@poettering.net
</email>
41 <refentrytitle>sd_journal_add_match
</refentrytitle>
42 <manvolnum>3</manvolnum>
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>
55 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
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>
65 <funcdef>int
<function>sd_journal_add_disjunction
</function></funcdef>
66 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
70 <funcdef>int
<function>sd_journal_add_conjunction
</function></funcdef>
71 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
75 <funcdef>void
<function>sd_journal_flush_matches
</function></funcdef>
76 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
82 <title>Description
</title>
84 <para><function>sd_journal_add_match()
</function> adds a match by
85 which to filter the entries of the journal file. Matches applied
86 with this call will filter what can be iterated through and read
87 from the journal file via calls like
88 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
90 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
91 Parameter
<parameter>data
</parameter> must be of the form
92 <literal><replaceable>FIELD
</replaceable>=
<replaceable>value
</replaceable></literal>,
93 where the
<replaceable>FIELD
</replaceable> part is a short uppercase string consisting only
94 of
0–
9, A–Z and the underscore; it may not begin with two underscores or be the empty
95 string. The
<replaceable>value
</replaceable> part may be anything, including binary. Parameter
96 <parameter>size
</parameter> specifies the number of bytes in
<parameter>data
</parameter>
97 (i.e. the length of
<replaceable>FIELD
</replaceable>, plus one, plus the length of
98 <replaceable>value
</replaceable>). Parameter
<parameter>size
</parameter> may also be
99 specified as
<constant>0</constant>, in which case
<parameter>data
</parameter>
100 must be a
<constant>NUL
</constant>-terminated string, and the bytes before the terminating
101 zero are used as the match.
</para>
103 <para>If a match is applied, only entries with this field set
104 will be iterated. Multiple matches may be active at the same time:
105 If they apply to different fields, only entries with both fields
106 set like this will be iterated. If they apply to the same fields,
107 only entries where the field takes one of the specified values
108 will be iterated. Well known fields are documented in
109 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
110 Whenever a new match is added the current entry position is reset,
112 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
113 (or a similar call) needs to be called before entries can be read
116 <para><function>sd_journal_add_disjunction()
</function> may be
117 used to insert a disjunction (i.e. logical OR) in the match list.
118 If this call is invoked, all previously added matches since the
120 <function>sd_journal_add_disjunction()
</function> or
121 <function>sd_journal_add_conjunction()
</function> are combined in
122 an OR with all matches added afterwards, until
123 <function>sd_journal_add_disjunction()
</function> or
124 <function>sd_journal_add_conjunction()
</function> is invoked again
125 to begin the next OR or AND term.
</para>
127 <para><function>sd_journal_add_conjunction()
</function> may be
128 used to insert a conjunction (i.e. logical AND) in the match list.
129 If this call is invoked, all previously added matches since the
131 <function>sd_journal_add_conjunction()
</function> are combined in
132 an AND with all matches added afterwards, until
133 <function>sd_journal_add_conjunction()
</function> is invoked again
134 to begin the next AND term. The combination of
135 <function>sd_journal_add_match()
</function>,
136 <function>sd_journal_add_disjunction()
</function> and
137 <function>sd_journal_add_conjunction()
</function> may be used to
138 build complex search terms, even though full logical expressions
139 are not available. Note that
140 <function>sd_journal_add_conjunction()
</function> operates one
142 <function>sd_journal_add_disjunction()
</function>. It is hence
143 possible to build an expression of AND terms, consisting of OR
144 terms, consisting of AND terms, consisting of OR terms of matches
145 (the latter OR expression is implicitly created for matches with
146 the same field name, see above).
</para>
148 <para><function>sd_journal_flush_matches()
</function> may be used
149 to flush all matches, disjunction and conjunction terms again.
150 After this call all filtering is removed and all entries in the
151 journal will be iterated again.
</para>
153 <para>Note that filtering via matches only applies to the way the
154 journal is read, it has no effect on storage on disk.
</para>
158 <title>Return Value
</title>
160 <para><function>sd_journal_add_match()
</function>,
161 <function>sd_journal_add_disjunction()
</function> and
162 <function>sd_journal_add_conjunction()
</function>
163 return
0 on success or a negative errno-style error
164 code.
<function>sd_journal_flush_matches()
</function>
165 returns nothing.
</para>
171 <para>All functions listed here are thread-agnostic and only a single thread may operate
172 on a given
<structname>sd_journal
</structname> object.
</para>
174 <para>The
<function>sd_journal_add_match()
</function>,
175 <function>sd_journal_add_disjunction()
</function>,
176 <function>sd_journal_add_conjunction()
</function> and
177 <function>sd_journal_flush_matches()
</function>
178 interfaces are available as a shared library, which can
179 be compiled and linked to with the
180 <constant>libsystemd
</constant> <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
185 <title>Examples
</title>
187 <para>The following example adds matches to a journal context
188 object to iterate only through messages generated by the Avahi
189 service at the four error log levels, plus all messages of the
190 message ID
03bb1dab98ab4ecfbf6fff2738bdd964 coming from any
191 service (this example lacks the necessary error checking):
</para>
194 int add_matches(sd_journal *j) {
195 sd_journal_add_match(j,
"_SYSTEMD_UNIT=avahi-daemon.service",
0);
196 sd_journal_add_match(j,
"PRIORITY=0",
0);
197 sd_journal_add_match(j,
"PRIORITY=1",
0);
198 sd_journal_add_match(j,
"PRIORITY=2",
0);
199 sd_journal_add_match(j,
"PRIORITY=3",
0);
200 sd_journal_add_disjunction(j);
201 sd_journal_add_match(j,
"MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964",
0);
207 <title>See Also
</title>
210 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
211 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
212 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
213 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
214 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
215 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>