sd_journal_add_match.xml revision 1e158d273bb63883566358cbb886cd4167421df6
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann This file is part of systemd.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann Copyright 2012 Lennart Poettering
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann systemd is free software; you can redistribute it and/or modify it
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann under the terms of the GNU Lesser General Public License as published by
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann the Free Software Foundation; either version 2.1 of the License, or
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann (at your option) any later version.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann systemd is distributed in the hope that it will be useful, but
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann WITHOUT ANY WARRANTY; without even the implied warranty of
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann Lesser General Public License for more details.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann You should have received a copy of the GNU Lesser General Public License
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann along with systemd; If not, see <http://www.gnu.org/licenses/>.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <refentryinfo>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <authorgroup>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </authorgroup>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </refentryinfo>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <refentrytitle>sd_journal_add_match</refentrytitle>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <refname>sd_journal_add_disjunction</refname>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <refname>sd_journal_add_conjunction</refname>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <refpurpose>Add or remove entry matches</refpurpose>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </refnamediv>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <refsynopsisdiv>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <funcsynopsis>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <funcprototype>
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann <funcdef>int <function>sd_journal_add_match</function></funcdef>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <paramdef>sd_journal* <parameter>j</parameter></paramdef>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <paramdef>const void* <parameter>data</parameter></paramdef>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <paramdef>size_t <parameter>size</parameter></paramdef>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </funcprototype>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <funcprototype>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <funcdef>int <function>sd_journal_add_disjunction</function></funcdef>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <paramdef>sd_journal* <parameter>j</parameter></paramdef>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </funcprototype>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <funcprototype>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <funcdef>int <function>sd_journal_add_conjunction</function></funcdef>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <paramdef>sd_journal* <parameter>j</parameter></paramdef>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </funcprototype>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <funcprototype>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <funcdef>void <function>sd_journal_flush_matches</function></funcdef>
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann <paramdef>sd_journal* <parameter>j</parameter></paramdef>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </funcprototype>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </funcsynopsis>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </refsynopsisdiv>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para><function>sd_journal_add_match()</function> adds
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann a match by which to filter the entries of the journal
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann file. Matches applied with this call will filter what
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann can be iterated through and read from the journal file
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann via calls like
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Matches
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann are of the form <literal>FIELD=value</literal>, where
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann the field part is a short uppercase string consisting
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann only of 0-9, A-Z and the underscore. It may not begin
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann with two underscores or be the empty string. The value
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann part may be any value, including binary. If a match is
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann applied only entries with this field set will be
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann iterated. Multiple matches may be active at the same
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann time: if they apply to different fields only entries
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann with both fields set like this will be iterated, if
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann they apply to the same fields only entries where the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann field takes one of the specified values will be
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann iterated. Well known fields are documented in
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Whenever
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann a new match is added the current entry position is
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> (or a similar call)
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann needs to be called before entries can be read
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann again.</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para><function>sd_journal_add_disjunction()</function>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann may be used to insert a disjunction (i.e. logical OR)
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann in the match list. If this call is invoked all
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann previously added matches since the last invocation of
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_disjunction()</function> or
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_conjunction()</function> are
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann combined in an OR with all matches added afterwards,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_disjunction()</function> or
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_conjunction()</function> is
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann invoked again to begin the next OR or AND
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann term. </para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para><function>sd_journal_add_conjunction()</function>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann may be used to insert a conjunction (i.e. logical AND)
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann in the match list. If this call is invoked all
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann previously added matches since the last invocation of
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_conjunction()</function> are
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann combined in an AND with all matches added afterwards,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_conjunction()</function> is
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann invoked again to begin the next AND term. The
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann combination of
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_match()</function>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_disjunction()</function> and
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_conjunction()</function> may
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann be used to build complex search terms, even though
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann full logical expressions are not available. Note that
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_conjunction()</function>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann operates one level 'higher' than
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_disjunction()</function>. It
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann is hence possible to build an expression of AND terms,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann consisting of OR terms, consisting of AND terms,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann consisting of OR terms of matches (the latter OR
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann expression is implicitly created for matches with the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann same field name, see above).</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para><function>sd_journal_flush_matches()</function>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann may be used to flush all matches, disjunction and
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann conjunction terms again. After this call all filtering
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann is removed and all entries in the journal will be
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann iterated again.</para>
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann <para>Note that filtering via matches only applies to
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann the way the journal is read, it has no effect on storage
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann on disk.</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para><function>sd_journal_add_match()</function>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_disjunction()</function> and
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_conjunction()</function>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann return 0 on success or a negative errno-style error
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann code. <function>sd_journal_flush_matches()</function>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann returns nothing.</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para>The <function>sd_journal_add_match()</function>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_disjunction()</function>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_add_conjunction()</function> and
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <function>sd_journal_flush_matches()</function>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann interfaces are available as shared library, which can
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann be compiled and linked to with the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <constant>libsystemd-journal</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para>The following example adds matches to a journal
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann context object to iterate only through messages
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann generated by the Avahi service at the four error log
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann levels, plus all messages of the message ID
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann service (this example lacks the necessary error
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann checking):</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <programlisting>...
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannint add_matches(sd_journal *j) {
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0);
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann sd_journal_add_match(j, "PRIORITY=0", 0);
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann sd_journal_add_match(j, "PRIORITY=1", 0);
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann sd_journal_add_match(j, "PRIORITY=2", 0);
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann sd_journal_add_match(j, "PRIORITY=3", 0);
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann sd_journal_add_disjunction(j);
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0);
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann}</programlisting>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>