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_close
</refname>
26 <refname>sd_journal
</refname>
27 <refname>SD_JOURNAL_LOCAL_ONLY
</refname>
28 <refname>SD_JOURNAL_RUNTIME_ONLY
</refname>
29 <refname>SD_JOURNAL_SYSTEM
</refname>
30 <refname>SD_JOURNAL_CURRENT_USER
</refname>
31 <refname>SD_JOURNAL_OS_ROOT
</refname>
32 <refpurpose>Open the system journal for reading
</refpurpose>
37 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
40 <funcdef>int
<function>sd_journal_open
</function></funcdef>
41 <paramdef>sd_journal **
<parameter>ret
</parameter></paramdef>
42 <paramdef>int
<parameter>flags
</parameter></paramdef>
46 <funcdef>int
<function>sd_journal_open_directory
</function></funcdef>
47 <paramdef>sd_journal **
<parameter>ret
</parameter></paramdef>
48 <paramdef>const char *
<parameter>path
</parameter></paramdef>
49 <paramdef>int
<parameter>flags
</parameter></paramdef>
53 <funcdef>int
<function>sd_journal_open_directory_fd
</function></funcdef>
54 <paramdef>sd_journal **
<parameter>ret
</parameter></paramdef>
55 <paramdef>int
<parameter>fd
</parameter></paramdef>
56 <paramdef>int
<parameter>flags
</parameter></paramdef>
60 <funcdef>int
<function>sd_journal_open_files
</function></funcdef>
61 <paramdef>sd_journal **
<parameter>ret
</parameter></paramdef>
62 <paramdef>const char **
<parameter>paths
</parameter></paramdef>
63 <paramdef>int
<parameter>flags
</parameter></paramdef>
67 <funcdef>int
<function>sd_journal_open_files_fd
</function></funcdef>
68 <paramdef>sd_journal **
<parameter>ret
</parameter></paramdef>
69 <paramdef>int
<parameter>fds[]
</parameter></paramdef>
70 <paramdef>unsigned
<parameter>n_fds
</parameter></paramdef>
71 <paramdef>int
<parameter>flags
</parameter></paramdef>
75 <funcdef>void
<function>sd_journal_close
</function></funcdef>
76 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
82 <title>Description
</title>
84 <para><function>sd_journal_open()
</function> opens the log journal
85 for reading. It will find all journal files automatically and
86 interleave them automatically when reading. As first argument it
87 takes a pointer to a
<varname>sd_journal
</varname> pointer, which,
88 on success, will contain a journal context object. The second
89 argument is a flags field, which may consist of the following
90 flags ORed together:
<constant>SD_JOURNAL_LOCAL_ONLY
</constant>
91 makes sure only journal files generated on the local machine will
92 be opened.
<constant>SD_JOURNAL_RUNTIME_ONLY
</constant> makes sure
93 only volatile journal files will be opened, excluding those which
94 are stored on persistent storage.
95 <constant>SD_JOURNAL_SYSTEM
</constant> will cause journal files of
96 system services and the kernel (in opposition to user session
97 processes) to be opened.
98 <constant>SD_JOURNAL_CURRENT_USER
</constant> will cause journal
99 files of the current user to be opened. If neither
100 <constant>SD_JOURNAL_SYSTEM
</constant> nor
101 <constant>SD_JOURNAL_CURRENT_USER
</constant> are specified, all
102 journal file types will be opened.
</para>
104 <para><function>sd_journal_open_directory()
</function> is similar to
<function>sd_journal_open()
</function> but
105 takes an absolute directory path as argument. All journal files in this directory will be opened and interleaved
106 automatically. This call also takes a flags argument. The flags parameters accepted by this call are
107 <constant>SD_JOURNAL_OS_ROOT
</constant>,
<constant>SD_JOURNAL_SYSTEM
</constant>, and
108 <constant>SD_JOURNAL_CURRENT_USER
</constant>. If
<constant>SD_JOURNAL_OS_ROOT
</constant> is specified, journal
109 files are searched for below the usual
<filename>/var/log/journal
</filename> and
110 <filename>/run/log/journal
</filename> relative to the specified path, instead of directly beneath it.
111 The other two flags limit which files are opened, the same as for
<function>sd_journal_open()
</function>.
114 <para><function>sd_journal_open_directory_fd()
</function> is similar to
115 <function>sd_journal_open_directory()
</function>, but takes a file descriptor referencing a directory in the file
116 system instead of an absolute file system path.
</para>
118 <para><function>sd_journal_open_files()
</function> is similar to
<function>sd_journal_open()
</function> but takes a
119 <constant>NULL
</constant>-terminated list of file paths to open. All files will be opened and interleaved
120 automatically. This call also takes a flags argument, but it must be passed as
0 as no flags are currently
121 understood for this call. Please note that in the case of a live journal, this function is only useful for
122 debugging, because individual journal files can be rotated at any moment, and the opening of specific files is
123 inherently racy.
</para>
125 <para><function>sd_journal_open_files_fd()
</function> is similar to
<function>sd_journal_open_files()
</function>
126 but takes an array of open file descriptors that must reference journal files, instead of an array of file system
127 paths. Pass the array of file descriptors as second argument, and the number of array entries in the third. The
128 flags parameter must be passed as
0.
</para>
130 <para><varname>sd_journal
</varname> objects cannot be used in the
131 child after a fork. Functions which take a journal object as an
132 argument (
<function>sd_journal_next()
</function> and others) will
133 return
<constant>-ECHILD
</constant> after a fork.
136 <para><function>sd_journal_close()
</function> will close the
137 journal context allocated with
138 <function>sd_journal_open()
</function> or
139 <function>sd_journal_open_directory()
</function> and free its
142 <para>When opening the journal only journal files accessible to
143 the calling user will be opened. If journal files are not
144 accessible to the caller, this will be silently ignored.
</para>
147 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
148 for an example of how to iterate through the journal after opening
149 it with
<function>sd_journal_open()
</function>.
</para>
151 <para>A journal context object returned by
152 <function>sd_journal_open()
</function> references a specific
153 journal entry as
<emphasis>current
</emphasis> entry, similar to a
154 file seek index in a classic file system file, but without
155 absolute positions. It may be altered with
156 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
158 <citerefentry><refentrytitle>sd_journal_seek_head
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
159 and related calls. The current entry position may be exported in
160 <emphasis>cursor
</emphasis> strings, as accessible via
161 <citerefentry><refentrytitle>sd_journal_get_cursor
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
162 Cursor strings may be used to globally identify a specific journal
163 entry in a stable way and then later to seek to it (or if the
164 specific entry is not available locally, to its closest entry in
166 <citerefentry><refentrytitle>sd_journal_seek_cursor
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
168 <para>Notification of journal changes is available via
169 <function>sd_journal_get_fd()
</function> and related calls.
</para>
173 <title>Return Value
</title>
175 <para>The
<function>sd_journal_open()
</function>,
176 <function>sd_journal_open_directory()
</function>, and
177 <function>sd_journal_open_files()
</function> calls return
0 on
178 success or a negative errno-style error code.
179 <function>sd_journal_close()
</function> returns nothing.
</para>
185 <xi:include href=
"threads-aware.xml" xpointer=
"strict"/>
187 <xi:include href=
"libsystemd-pkgconfig.xml" xpointer=
"pkgconfig-text"/>
191 <title>See Also
</title>
194 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
195 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
196 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
197 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
198 <citerefentry><refentrytitle>systemd-machined
</refentrytitle><manvolnum>8</manvolnum></citerefentry>