sd_journal_get_catalog.xml revision d4873485cf4fb223598f3b2fcf81e22cc8bb9456
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok This file is part of systemd.
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok Copyright 2012 Lennart Poettering
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok systemd is free software; you can redistribute it and/or modify it
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok under the terms of the GNU Lesser General Public License as published by
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok the Free Software Foundation; either version 2.1 of the License, or
5797606612b5b37dbba5d90b39665cdf7f7a1b11William Giokas (at your option) any later version.
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok systemd is distributed in the hope that it will be useful, but
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok WITHOUT ANY WARRANTY; without even the implied warranty of
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok Lesser General Public License for more details.
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok You should have received a copy of the GNU Lesser General Public License
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok along with systemd; If not, see <http://www.gnu.org/licenses/>.
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <refentryinfo>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok </authorgroup>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok </refentryinfo>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <refentrytitle>sd_journal_get_catalog</refentrytitle>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <refnamediv>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <refname>sd_journal_get_catalog_for_message_id</refname>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <refpurpose>Retrieve message catalog entry</refpurpose>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok </refnamediv>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <refsynopsisdiv>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <funcsynopsis>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <funcprototype>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <funcdef>int <function>sd_journal_get_catalog</function></funcdef>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <paramdef>sd_journal *<parameter>j</parameter></paramdef>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <paramdef>char **<parameter>ret</parameter></paramdef>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek </funcprototype>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_journal_get_catalog_for_message_id</function></funcdef>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <paramdef>char **<parameter>ret</parameter></paramdef>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek </funcprototype>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek </refsynopsisdiv>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <para><function>sd_journal_get_catalog()</function>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek retrieves a message catalog entry for the current
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek journal entry. This will look up an entry in the
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek message catalog by using the
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <literal>MESSAGE_ID=</literal> field of the current
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek journal entry. Before returning the entry all journal
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek field names in the catalog entry text enclosed in "@"
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek will be replaced by the respective field values of the
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek current entry. If a field name referenced in the
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek message catalog entry does not exist, in the current
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek journal entry, the "@" will be removed, but the field
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek name otherwise left untouched.</para>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <para><function>sd_journal_get_catalog_for_message_id()</function>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek works similar to
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <function>sd_journal_get_catalog()</function> but the
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek entry is looked up by the specified message ID (no
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek open journal context is necessary for this), and no
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek field substitution is performed.</para>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <para>For more information about the journal message
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek catalog please refer to the <ulink
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Journal
e7ecdfc15cee7a90da23d89c228ada5560ebb3a4Zbigniew Jędrzejewski-Szmek Message Catalogs</ulink> documentation page.</para>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <para><function>sd_journal_get_catalog()</function>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <function>sd_journal_get_catalog_for_message_id()</function>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok return 0 on success or a negative errno-style error
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok code. If no matching message catalog entry is found,
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok -ENOENT is returned.</para>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <para>On successful return, <parameter>ret</parameter>
ccc9a4f9ffdab069b0b785627c48962fdadf6d46Zbigniew Jędrzejewski-Szmek points to a new string, which must be freed with
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <para>The <function>sd_journal_get_catalog()</function> and
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <function>sd_journal_get_catalog_for_message_id()</function>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok interfaces are available as a shared library, which can
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok be compiled and linked to with the
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f1c24fea94e19cf2108abbeed1d36ded7102ab98Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok <citerefentry><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry>
83fdc450aa8f79941bec84488ffd5bf8eadab18eAuke Kok </refsect1>