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">
6 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2012 Lennart Poettering
13 <refentry id=
"sd_journal_get_catalog">
16 <title>sd_journal_get_catalog
</title>
17 <productname>systemd
</productname>
21 <contrib>Developer
</contrib>
22 <firstname>Lennart
</firstname>
23 <surname>Poettering
</surname>
24 <email>lennart@poettering.net
</email>
30 <refentrytitle>sd_journal_get_catalog
</refentrytitle>
31 <manvolnum>3</manvolnum>
35 <refname>sd_journal_get_catalog
</refname>
36 <refname>sd_journal_get_catalog_for_message_id
</refname>
37 <refpurpose>Retrieve message catalog entry
</refpurpose>
42 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
45 <funcdef>int
<function>sd_journal_get_catalog
</function></funcdef>
46 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
47 <paramdef>char **
<parameter>ret
</parameter></paramdef>
51 <funcdef>int
<function>sd_journal_get_catalog_for_message_id
</function></funcdef>
52 <paramdef>sd_id128_t
<parameter>id
</parameter></paramdef>
53 <paramdef>char **
<parameter>ret
</parameter></paramdef>
60 <title>Description
</title>
62 <para><function>sd_journal_get_catalog()
</function> retrieves a
63 message catalog entry for the current journal entry. This will
64 look up an entry in the message catalog by using the
65 <literal>MESSAGE_ID=
</literal> field of the current journal entry.
66 Before returning the entry all journal field names in the catalog
67 entry text enclosed in
"@" will be replaced by the respective
68 field values of the current entry. If a field name referenced in
69 the message catalog entry does not exist, in the current journal
70 entry, the
"@" will be removed, but the field name otherwise left
73 <para><function>sd_journal_get_catalog_for_message_id()
</function>
74 works similar to
<function>sd_journal_get_catalog()
</function> but
75 the entry is looked up by the specified message ID (no open
76 journal context is necessary for this), and no field substitution
79 <para>For more information about the journal message catalog
80 please refer to the
<ulink
81 url=
"https://www.freedesktop.org/wiki/Software/systemd/catalog">Journal
82 Message Catalogs
</ulink> documentation page.
</para>
86 <title>Return Value
</title>
88 <para><function>sd_journal_get_catalog()
</function> and
89 <function>sd_journal_get_catalog_for_message_id()
</function>
90 return
0 on success or a negative errno-style error code. If no
91 matching message catalog entry is found, -ENOENT is
94 <para>On successful return,
<parameter>ret
</parameter> points to a
95 new string, which must be freed with
96 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
103 <para>Function
<function>sd_journal_get_catalog()
</function> is thread-agnostic and only a
104 single thread may operate on a given
<structname>sd_journal
</structname> object. Function
105 <function>sd_journal_get_catalog_for_message_id()
</function> is thread-safe.
</para>
107 <para>The
<function>sd_journal_get_catalog()
</function> and
108 <function>sd_journal_get_catalog_for_message_id()
</function>
109 interfaces are available as a shared library, which can be
110 compiled and linked to with the
111 <constant>libsystemd
</constant> <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
116 <title>See Also
</title>
119 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
120 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
121 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
122 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
123 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
124 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
125 <citerefentry project='man-pages'
><refentrytitle>malloc
</refentrytitle><manvolnum>3</manvolnum></citerefentry>