1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"sd_journal_open"
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>sd_journal_open
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>sd_journal_open
</refentrytitle>
16 <manvolnum>3</manvolnum>
20 <refname>sd_journal_open
</refname>
21 <refname>sd_journal_open_directory
</refname>
22 <refname>sd_journal_open_directory_fd
</refname>
23 <refname>sd_journal_open_files
</refname>
24 <refname>sd_journal_open_files_fd
</refname>
25 <refname>sd_journal_open_namespace
</refname>
26 <refname>sd_journal_close
</refname>
27 <refname>sd_journal
</refname>
28 <refname>SD_JOURNAL_LOCAL_ONLY
</refname>
29 <refname>SD_JOURNAL_RUNTIME_ONLY
</refname>
30 <refname>SD_JOURNAL_SYSTEM
</refname>
31 <refname>SD_JOURNAL_CURRENT_USER
</refname>
32 <refname>SD_JOURNAL_OS_ROOT
</refname>
33 <refname>SD_JOURNAL_ALL_NAMESPACES
</refname>
34 <refname>SD_JOURNAL_INCLUDE_DEFAULT_NAMESPACE
</refname>
35 <refpurpose>Open the system journal for reading
</refpurpose>
40 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
43 <funcdef>int
<function>sd_journal_open
</function></funcdef>
44 <paramdef>sd_journal **
<parameter>ret
</parameter></paramdef>
45 <paramdef>int
<parameter>flags
</parameter></paramdef>
49 <funcdef>int
<function>sd_journal_open_namespace
</function></funcdef>
50 <paramdef>sd_journal **
<parameter>ret
</parameter></paramdef>
51 <paramdef>const char *
<parameter>namespace
</parameter></paramdef>
52 <paramdef>int
<parameter>flags
</parameter></paramdef>
56 <funcdef>int
<function>sd_journal_open_directory
</function></funcdef>
57 <paramdef>sd_journal **
<parameter>ret
</parameter></paramdef>
58 <paramdef>const char *
<parameter>path
</parameter></paramdef>
59 <paramdef>int
<parameter>flags
</parameter></paramdef>
63 <funcdef>int
<function>sd_journal_open_directory_fd
</function></funcdef>
64 <paramdef>sd_journal **
<parameter>ret
</parameter></paramdef>
65 <paramdef>int
<parameter>fd
</parameter></paramdef>
66 <paramdef>int
<parameter>flags
</parameter></paramdef>
70 <funcdef>int
<function>sd_journal_open_files
</function></funcdef>
71 <paramdef>sd_journal **
<parameter>ret
</parameter></paramdef>
72 <paramdef>const char **
<parameter>paths
</parameter></paramdef>
73 <paramdef>int
<parameter>flags
</parameter></paramdef>
77 <funcdef>int
<function>sd_journal_open_files_fd
</function></funcdef>
78 <paramdef>sd_journal **
<parameter>ret
</parameter></paramdef>
79 <paramdef>int
<parameter>fds[]
</parameter></paramdef>
80 <paramdef>unsigned
<parameter>n_fds
</parameter></paramdef>
81 <paramdef>int
<parameter>flags
</parameter></paramdef>
85 <funcdef>void
<function>sd_journal_close
</function></funcdef>
86 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
92 <title>Description
</title>
94 <para><function>sd_journal_open()
</function> opens the log journal
95 for reading. It will find all journal files automatically and
96 interleave them automatically when reading. As first argument it
97 takes a pointer to a
<varname>sd_journal
</varname> pointer, which,
98 on success, will contain a journal context object. The second
99 argument is a flags field, which may consist of the following
100 flags ORed together:
<constant>SD_JOURNAL_LOCAL_ONLY
</constant>
101 makes sure only journal files generated on the local machine will
102 be opened.
<constant>SD_JOURNAL_RUNTIME_ONLY
</constant> makes sure
103 only volatile journal files will be opened, excluding those which
104 are stored on persistent storage.
105 <constant>SD_JOURNAL_SYSTEM
</constant> will cause journal files of
106 system services and the kernel (in opposition to user session
107 processes) to be opened.
108 <constant>SD_JOURNAL_CURRENT_USER
</constant> will cause journal
109 files of the current user to be opened. If neither
110 <constant>SD_JOURNAL_SYSTEM
</constant> nor
111 <constant>SD_JOURNAL_CURRENT_USER
</constant> are specified, all
112 journal file types will be opened.
</para>
114 <para><function>sd_journal_open_namespace()
</function> is similar to
115 <function>sd_journal_open()
</function> but takes an additional
<parameter>namespace
</parameter> parameter
116 that specifies which journal namespace to operate on. If specified as
<constant>NULL
</constant> the call
117 is identical to
<function>sd_journal_open()
</function>. If non-
<constant>NULL
</constant> only data from
118 the namespace identified by the specified parameter is accessed. This call understands two additional
119 flags: if
<constant>SD_JOURNAL_ALL_NAMESPACES
</constant> is specified the
120 <parameter>namespace
</parameter> parameter is ignored and all defined namespaces are accessed
121 simultaneously; if
<constant>SD_JOURNAL_INCLUDE_DEFAULT_NAMESPACE
</constant> the specified namespace and
122 the default namespace are accessed but no others (this flag has no effect when
123 <parameter>namespace
</parameter> is passed as
<constant>NULL
</constant>). For details about journal
125 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
127 <para><function>sd_journal_open_directory()
</function> is similar to
<function>sd_journal_open()
</function> but
128 takes an absolute directory path as argument. All journal files in this directory will be opened and interleaved
129 automatically. This call also takes a flags argument. The flags parameters accepted by this call are
130 <constant>SD_JOURNAL_OS_ROOT
</constant>,
<constant>SD_JOURNAL_SYSTEM
</constant>, and
131 <constant>SD_JOURNAL_CURRENT_USER
</constant>. If
<constant>SD_JOURNAL_OS_ROOT
</constant> is specified, journal
132 files are searched for below the usual
<filename>/var/log/journal
</filename> and
133 <filename>/run/log/journal
</filename> relative to the specified path, instead of directly beneath it.
134 The other two flags limit which files are opened, the same as for
<function>sd_journal_open()
</function>.
137 <para><function>sd_journal_open_directory_fd()
</function> is similar to
138 <function>sd_journal_open_directory()
</function>, but takes a file descriptor referencing a directory in the file
139 system instead of an absolute file system path.
</para>
141 <para><function>sd_journal_open_files()
</function> is similar to
<function>sd_journal_open()
</function> but takes a
142 <constant>NULL
</constant>-terminated list of file paths to open. All files will be opened and interleaved
143 automatically. This call also takes a flags argument, but it must be passed as
0 as no flags are currently
144 understood for this call. Please note that in the case of a live journal, this function is only useful for
145 debugging, because individual journal files can be rotated at any moment, and the opening of specific files is
146 inherently racy.
</para>
148 <para><function>sd_journal_open_files_fd()
</function> is similar to
<function>sd_journal_open_files()
</function>
149 but takes an array of open file descriptors that must reference journal files, instead of an array of file system
150 paths. Pass the array of file descriptors as second argument, and the number of array entries in the third. The
151 flags parameter must be passed as
0.
</para>
153 <para><varname>sd_journal
</varname> objects cannot be used in the
154 child after a fork. Functions which take a journal object as an
155 argument (
<function>sd_journal_next()
</function> and others) will
156 return
<constant>-ECHILD
</constant> after a fork.
159 <para><function>sd_journal_close()
</function> will close the
160 journal context allocated with
161 <function>sd_journal_open()
</function> or
162 <function>sd_journal_open_directory()
</function> and free its
165 <para>When opening the journal only journal files accessible to
166 the calling user will be opened. If journal files are not
167 accessible to the caller, this will be silently ignored.
</para>
170 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
171 for an example of how to iterate through the journal after opening
172 it with
<function>sd_journal_open()
</function>.
</para>
174 <para>A journal context object returned by
175 <function>sd_journal_open()
</function> references a specific
176 journal entry as
<emphasis>current
</emphasis> entry, similar to a
177 file seek index in a classic file system file, but without
178 absolute positions. It may be altered with
179 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
181 <citerefentry><refentrytitle>sd_journal_seek_head
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
182 and related calls. The current entry position may be exported in
183 <emphasis>cursor
</emphasis> strings, as accessible via
184 <citerefentry><refentrytitle>sd_journal_get_cursor
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
185 Cursor strings may be used to globally identify a specific journal
186 entry in a stable way and then later to seek to it (or if the
187 specific entry is not available locally, to its closest entry in
189 <citerefentry><refentrytitle>sd_journal_seek_cursor
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
191 <para>Notification of journal changes is available via
192 <function>sd_journal_get_fd()
</function> and related calls.
</para>
196 <title>Return Value
</title>
198 <para>The
<function>sd_journal_open()
</function>,
199 <function>sd_journal_open_directory()
</function>, and
200 <function>sd_journal_open_files()
</function> calls return
0 on
201 success or a negative errno-style error code.
202 <function>sd_journal_close()
</function> returns nothing.
</para>
208 <xi:include href=
"threads-aware.xml" xpointer=
"strict"/>
210 <xi:include href=
"libsystemd-pkgconfig.xml" xpointer=
"pkgconfig-text"/>
214 <title>See Also
</title>
217 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
218 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
219 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
220 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
221 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>