man/sd_journal_get_catalog.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_get_catalog">
  25
  26         <refentryinfo>
  27                 <title>sd_journal_get_catalog</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_get_catalog</refentrytitle>
  42                 <manvolnum>3</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>sd_journal_get_catalog</refname>
  47                 <refname>sd_journal_get_catalog_for_message_id</refname>
  48                 <refpurpose>Retrieve message catalog entry</refpurpose>
  49         </refnamediv>
  50
  51         <refsynopsisdiv>
  52                 <funcsynopsis>
  53                         <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  54
  55                         <funcprototype>
  56                                 <funcdef>int <function>sd_journal_get_catalog</function></funcdef>
  57                                 <paramdef>sd_journal* <parameter>j</parameter></paramdef>
  58                                 <paramdef>char** <parameter>ret</parameter></paramdef>
  59                         </funcprototype>
  60
  61                         <funcprototype>
  62                                 <funcdef>int <function>sd_journal_get_catalog_for_message_id</function></funcdef>
  63                                 <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
  64                                 <paramdef>char** <parameter>ret</parameter></paramdef>
  65                         </funcprototype>
  66
  67
  68                 </funcsynopsis>
  69         </refsynopsisdiv>
  70
  71         <refsect1>
  72                 <title>Description</title>
  73
  74                 <para><function>sd_journal_get_catalog()</function>
  75                 retrieves a message catalog entry for the current
  76                 journal entry. This will look up an entry in the
  77                 message catalog by using the
  78                 <literal>MESSAGE_ID=</literal> field of the current
  79                 journal entry. Before returning the entry all journal
  80                 field names in the catalog entry text enclosed in "@"
  81                 will be replaced by the respective field values of the
  82                 current entry. If a field name referenced in the
  83                 message catalog entry does not exist, in the current
  84                 journal entry, the "@" will be removed, but the field
  85                 name otherwise left untouched.</para>
  86
  87                 <para><function>sd_journal_get_catalog_for_message_id()</function>
  88                 works similar to
  89                 <function>sd_journal_get_catalog()</function> but the
  90                 entry is looked up by the specified message ID (no
  91                 open journal context is necessary for this), and no
  92                 field substitution is performed.</para>
  93
  94                 <para>For more information about the journal message
  95                 catalog please refer to the <ulink
  96                 url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Journal
  97                 Message Catalogs</ulink> documentation page.</para>
  98         </refsect1>
  99
 100         <refsect1>
 101                 <title>Return Value</title>
 102
 103                 <para><function>sd_journal_get_catalog()</function>
 104                 and
 105                 <function>sd_journal_get_catalog_for_message_id()</function>
 106                 return 0 on success or a negative errno-style error
 107                 code. If no matching message catalog entry is found,
 108                 -ENOENT is returned.</para>
 109
 110                 <para>On successful return, <parameter>ret</parameter>
 111                 points to a new string, which must be freed with
 112                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 113                 </para>
 114         </refsect1>
 115
 116         <refsect1>
 117                 <title>Notes</title>
 118
 119                 <para>The <function>sd_journal_get_catalog()</function> and
 120                 <function>sd_journal_get_catalog_for_message_id()</function>
 121                 interfaces are available as shared library, which can
 122                 be compiled and linked to with the
 123                 <constant>libsystemd-journal</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 124                 file.</para>
 125         </refsect1>
 126
 127         <refsect1>
 128                 <title>See Also</title>
 129
 130                 <para>
 131                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 132                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 133                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 134                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 135                         <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 136                         <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 137                         <citerefentry><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 138                 </para>
 139         </refsect1>
 140
 141 </refentry>