<?xml version='1.0'?> <!--*-nxml-*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

<!ENTITY % entities SYSTEM "custom-entities.ent" >

%entities;

]>

<refentry id="sd_journal_add_match">

<refentryinfo>

<title>sd_journal_add_match</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>sd_journal_add_match</refentrytitle>

<manvolnum>3</manvolnum>

</refmeta>

<refnamediv>

<refname>sd_journal_add_match</refname>

<refname>sd_journal_add_disjunction</refname>

<refname>sd_journal_add_conjunction</refname>

<refname>sd_journal_flush_matches</refname>

<refpurpose>Add or remove entry matches</refpurpose>

</refnamediv>

<refsynopsisdiv>

<funcsynopsis>

<funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>

<funcprototype>

<funcdef>int <function>sd_journal_add_match</function></funcdef>

<paramdef>sd_journal *<parameter>j</parameter></paramdef>

<paramdef>const void *<parameter>data</parameter></paramdef>

<paramdef>size_t <parameter>size</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_journal_add_disjunction</function></funcdef>

<paramdef>sd_journal *<parameter>j</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_journal_add_conjunction</function></funcdef>

<paramdef>sd_journal *<parameter>j</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>void <function>sd_journal_flush_matches</function></funcdef>

<paramdef>sd_journal *<parameter>j</parameter></paramdef>

</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><function>sd_journal_add_match()</function> adds a match by

which to filter the entries of the journal file. Matches applied

with this call will filter what can be iterated through and read

from the journal file via calls like

<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>

and

<citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.

Matches are of the form <literal>FIELD=value</literal>, where the

field part is a short uppercase string consisting only of 0-9, A-Z

and the underscore. It may not begin with two underscores or be

the empty string. The value part may be any value, including

binary. If a match is applied, only entries with this field set

will be iterated. Multiple matches may be active at the same time:

If they apply to different fields, only entries with both fields

set like this will be iterated. If they apply to the same fields,

only entries where the field takes one of the specified values

will be iterated. Well known fields are documented in

<citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.

Whenever a new match is added the current entry position is reset,

and

<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>

(or a similar call) needs to be called before entries can be read

again.</para>

<para><function>sd_journal_add_disjunction()</function> may be

used to insert a disjunction (i.e. logical OR) in the match list.

If this call is invoked, all previously added matches since the

last invocation of

<function>sd_journal_add_disjunction()</function> or

<function>sd_journal_add_conjunction()</function> are combined in

an OR with all matches added afterwards, until

<function>sd_journal_add_disjunction()</function> or

<function>sd_journal_add_conjunction()</function> is invoked again

to begin the next OR or AND term. </para>

<para><function>sd_journal_add_conjunction()</function> may be

used to insert a conjunction (i.e. logical AND) in the match list.

If this call is invoked, all previously added matches since the

last invocation of

<function>sd_journal_add_conjunction()</function> are combined in

an AND with all matches added afterwards, until

<function>sd_journal_add_conjunction()</function> is invoked again

to begin the next AND term. The combination of

<function>sd_journal_add_match()</function>,

<function>sd_journal_add_disjunction()</function> and

<function>sd_journal_add_conjunction()</function> may be used to

build complex search terms, even though full logical expressions

are not available. Note that

<function>sd_journal_add_conjunction()</function> operates one

level 'higher' than

<function>sd_journal_add_disjunction()</function>. It is hence

possible to build an expression of AND terms, consisting of OR

terms, consisting of AND terms, consisting of OR terms of matches

(the latter OR expression is implicitly created for matches with

the same field name, see above).</para>

<para><function>sd_journal_flush_matches()</function> may be used

to flush all matches, disjunction and conjunction terms again.

After this call all filtering is removed and all entries in the

journal will be iterated again.</para>

<para>Note that filtering via matches only applies to the way the

journal is read, it has no effect on storage on disk.</para>

</refsect1>

<refsect1>

<title>Return Value</title>

<para><function>sd_journal_add_match()</function>,

<function>sd_journal_add_disjunction()</function> and

<function>sd_journal_add_conjunction()</function>

return 0 on success or a negative errno-style error

code. <function>sd_journal_flush_matches()</function>

returns nothing.</para>

</refsect1>

<refsect1>

<title>Notes</title>

<para>The <function>sd_journal_add_match()</function>,

<function>sd_journal_add_disjunction()</function>,

<function>sd_journal_add_conjunction()</function> and

<function>sd_journal_flush_matches()</function>

interfaces are available as a shared library, which can

be compiled and linked to with the

<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>

file.</para>

</refsect1>

<refsect1>

<title>Examples</title>

<para>The following example adds matches to a journal context

object to iterate only through messages generated by the Avahi

service at the four error log levels, plus all messages of the

message ID 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any

service (this example lacks the necessary error checking):</para>

<programlisting>...

int add_matches(sd_journal *j) {

sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0);

sd_journal_add_match(j, "PRIORITY=0", 0);

sd_journal_add_match(j, "PRIORITY=1", 0);

sd_journal_add_match(j, "PRIORITY=2", 0);

sd_journal_add_match(j, "PRIORITY=3", 0);

sd_journal_add_disjunction(j);

sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0);

}</programlisting>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>