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