diff options
Diffstat (limited to 'man/sd_journal_add_match.xml')
| -rw-r--r-- | man/sd_journal_add_match.xml | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml new file mode 100644 index 0000000000..4aadf6cf00 --- /dev/null +++ b/man/sd_journal_add_match.xml @@ -0,0 +1,189 @@ +<?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"> + +<!-- + This file is part of systemd. + + Copyright 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<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_flush_matches</refname> + <refpurpose>Add or remove entry matches</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></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_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 are combined in an OR with + all matches added afterwards, until + <function>sd_journal_add_disjunction()</function> is + invoked again to begin the next OR term. The + combination of + <function>sd_journal_add_match()</function> and + <function>sd_journal_add_disjunction()</function> may + be used to build complex search terms, even though + full logical expressions are not available.</para> + + <para><function>sd_journal_flush_matches()</function> + may be used to flush all matches and disjunction 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 + 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> and + <function>sd_journal_add_disjunction()</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> and + <function>sd_journal_flush_matches()</function> interfaces are + available as shared library, which can be compiled and + linked to with the + <literal>libsystemd-journal</literal> + <citerefentry><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"); + sd_journal_add_match(j, "PRIORITY=0"); + sd_journal_add_match(j, "PRIORITY=1"); + sd_journal_add_match(j, "PRIORITY=2"); + sd_journal_add_match(j, "PRIORITY=3"); + sd_journal_add_disjunction(j); + sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964"); +}</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> |