chiark / gitweb /
man: add systemd.generator(7)
[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 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>
89     and
90     <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
91     Matches are of the form <literal>FIELD=value</literal>, where the
92     field part is a short uppercase string consisting only of 0-9, A-Z
93     and the underscore. It may not begin with two underscores or be
94     the empty string. The value part may be any value, including
95     binary. If a match is applied, only entries with this field set
96     will be iterated. Multiple matches may be active at the same time:
97     If they apply to different fields, only entries with both fields
98     set like this will be iterated. If they apply to the same fields,
99     only entries where the field takes one of the specified values
100     will be iterated. Well known fields are documented in
101     <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
102     Whenever a new match is added the current entry position is reset,
103     and
104     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
105     (or a similar call) needs to be called before entries can be read
106     again.</para>
107
108     <para><function>sd_journal_add_disjunction()</function> may be
109     used to insert a disjunction (i.e. logical OR) in the match list.
110     If this call is invoked, all previously added matches since the
111     last invocation of
112     <function>sd_journal_add_disjunction()</function> or
113     <function>sd_journal_add_conjunction()</function> are combined in
114     an OR with all matches added afterwards, until
115     <function>sd_journal_add_disjunction()</function> or
116     <function>sd_journal_add_conjunction()</function> is invoked again
117     to begin the next OR or AND term. </para>
118
119     <para><function>sd_journal_add_conjunction()</function> may be
120     used to insert a conjunction (i.e. logical AND) in the match list.
121     If this call is invoked, all previously added matches since the
122     last invocation of
123     <function>sd_journal_add_conjunction()</function> are combined in
124     an AND with all matches added afterwards, until
125     <function>sd_journal_add_conjunction()</function> is invoked again
126     to begin the next AND term. The combination of
127     <function>sd_journal_add_match()</function>,
128     <function>sd_journal_add_disjunction()</function> and
129     <function>sd_journal_add_conjunction()</function> may be used to
130     build complex search terms, even though full logical expressions
131     are not available. Note that
132     <function>sd_journal_add_conjunction()</function> operates one
133     level 'higher' than
134     <function>sd_journal_add_disjunction()</function>. It is hence
135     possible to build an expression of AND terms, consisting of OR
136     terms, consisting of AND terms, consisting of OR terms of matches
137     (the latter OR expression is implicitly created for matches with
138     the same field name, see above).</para>
139
140     <para><function>sd_journal_flush_matches()</function> may be used
141     to flush all matches, disjunction and conjunction terms again.
142     After this call all filtering is removed and all entries in the
143     journal will be iterated again.</para>
144
145     <para>Note that filtering via matches only applies to the way the
146     journal is read, it has no effect on storage on disk.</para>
147   </refsect1>
148
149   <refsect1>
150     <title>Return Value</title>
151
152     <para><function>sd_journal_add_match()</function>,
153     <function>sd_journal_add_disjunction()</function> and
154     <function>sd_journal_add_conjunction()</function>
155     return 0 on success or a negative errno-style error
156     code. <function>sd_journal_flush_matches()</function>
157     returns nothing.</para>
158   </refsect1>
159
160   <refsect1>
161     <title>Notes</title>
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>