Debian Codegraph @

upstream/debian-unstable/man3/sd_journal_get_catalog.3

raw
1 '\" t
2 .TH "SD_JOURNAL_GET_CATALOG" "3" "" "systemd 261~rc3" "sd_journal_get_catalog"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_journal_get_catalog, sd_journal_get_catalog_for_message_id \- Retrieve message catalog entry
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-journal\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_journal_get_catalog('u
32 .BI "int sd_journal_get_catalog(sd_journal\ *" "j" ", char\ **" "ret" ");"
33 .HP \w'int\ sd_journal_get_catalog_for_message_id('u
34 .BI "int sd_journal_get_catalog_for_message_id(sd_id128_t\ " "id" ", char\ **" "ret" ");"
35 .SH "DESCRIPTION"
36 .PP
37 \fBsd_journal_get_catalog()\fR
38 retrieves a message catalog entry for the current journal entry\&. This will look up an entry in the message catalog by using the
39 "MESSAGE_ID="
40 field of the current journal entry\&. Before returning the entry all journal field names in the catalog entry text enclosed in "@" will be replaced by the respective field values of the current entry\&. If a field name referenced in the message catalog entry does not exist, in the current journal entry, the "@" will be removed, but the field name otherwise left untouched\&.
41 .PP
42 \fBsd_journal_get_catalog_for_message_id()\fR
43 works similar to
44 \fBsd_journal_get_catalog()\fR
45 but the entry is looked up by the specified message ID (no open journal context is necessary for this), and no field substitution is performed\&.
46 .PP
47 For more information about the journal message catalog please refer to the
48 \m[blue]\fBJournal Message Catalogs\fR\m[]\&\s-2\u[1]\d\s+2
49 documentation page\&.
50 .SH "RETURN VALUE"
51 .PP
52 \fBsd_journal_get_catalog()\fR
53 and
54 \fBsd_journal_get_catalog_for_message_id()\fR
55 return 0 on success or a negative errno\-style error code\&. If no matching message catalog entry is found, \-ENOENT is returned\&.
56 .PP
57 On successful return,
58 \fIret\fR
59 points to a new string, which must be freed with
60 \fBfree\fR(3)\&.
61 .SH "NOTES"
62 .PP
63 Function
64 \fBsd_journal_get_catalog()\fR
65 is thread\-agnostic and only a single thread may operate on a given object at any given time\&. Multiple independent objects may be used from different threads in parallel\&.
66 .PP
67 Function
68 \fBsd_journal_get_catalog_for_message_id()\fR
69 is thread\-safe and may be called from multiple threads in parallel\&.
70 .PP
71 Functions described here are available as a shared library, which can be compiled against and linked to with the
72 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
73 file\&.
74 .SH "HISTORY"
75 .PP
76 \fBsd_journal_get_catalog()\fR
77 and
78 \fBsd_journal_get_catalog_for_message_id()\fR
79 were added in version 196\&.
80 .SH "SEE ALSO"
81 .PP
82 \fBsystemd\fR(1), \fBsystemd.journal-fields\fR(7), \fBsd-journal\fR(3), \fBsd_journal_open\fR(3), \fBsd_journal_next\fR(3), \fBsd_journal_get_data\fR(3), \fBmalloc\fR(3)
83 .SH "NOTES"
84 .IP " 1." 4
85 Journal Message Catalogs
86 .RS 4
87 \%https://systemd.io/CATALOG
88 .RE