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 This file is part of systemd.
8 Copyright 2012 Lennart Poettering
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.
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.
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/>.
24 <refentry id="sd_journal_open">
27 <title>sd_journal_open</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>sd_journal_open</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_journal_open</refname>
47 <refname>sd_journal_open_directory</refname>
48 <refname>sd_journal_close</refname>
49 <refname>sd_journal</refname>
50 <refname>SD_JOURNAL_LOCAL_ONLY</refname>
51 <refname>SD_JOURNAL_RUNTIME_ONLY</refname>
52 <refname>SD_JOURNAL_SYSTEM</refname>
53 <refname>SD_JOURNAL_CURRENT_USER</refname>
54 <refpurpose>Open the system journal for reading</refpurpose>
59 <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
62 <funcdef>int <function>sd_journal_open</function></funcdef>
63 <paramdef>sd_journal** <parameter>ret</parameter></paramdef>
64 <paramdef>int <parameter>flags</parameter></paramdef>
68 <funcdef>int <function>sd_journal_open_directory</function></funcdef>
69 <paramdef>sd_journal** <parameter>ret</parameter></paramdef>
70 <paramdef>const char* <parameter>path</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
85 the log journal for reading. It will find all journal
86 files automatically and interleave them automatically
87 when reading. As first argument it takes a pointer to
88 a <literal>sd_journal</literal> pointer, which on
89 success will contain journal context object afterwards. The
90 second argument is a flags field, which may consist of
91 the following flags ORed together:
92 <literal>SD_JOURNAL_LOCAL_ONLY</literal> makes sure
93 only journal files generated on the local machine will
94 be opened. <literal>SD_JOURNAL_RUNTIME_ONLY</literal>
95 makes sure only volatile journal files will be opened,
96 excluding those which are stored on persistent
97 storage. <literal>SD_JOURNAL_SYSTEM</literal>
98 will cause journal files of system services and the
99 kernel (in opposition to user session processes) to
100 be opened. <literal>SD_JOURNAL_CURRENT_USER</literal>
101 will cause journal files of the current user to be
102 opened. If neither <literal>SD_JOURNAL_SYSTEM</literal>
103 nor <literal>SD_JOURNAL_CURRENT_USER</literal> are
104 specified, all journal file types will be opened.</para>
106 <para><function>sd_journal_open_directory()</function>
107 is similar to <function>sd_journal_open()</function>
108 but takes an absolute directory path as argument. All
109 journal files in this directory will be opened and
110 interleaved automatically. This call also takes a
111 flags argument, but it must be passed as 0 as no flags
112 are currently understood for this call.</para>
114 <para><function>sd_journal_close()</function> will
115 close the journal context allocated with
116 <function>sd_journal_open()</function> or
117 <function>sd_journal_open_directory()</function> and
118 free its resources.</para>
120 <para>When opening the journal only journal files
121 accessible to the calling user will be opened. If
122 journal files are not accessible to the caller this
123 will be silently ignored.</para>
126 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
127 for an example how to iterate through the journal
128 after opening it with
129 <function>sd_journal_open()</function>.</para>
131 <para>A journal context object returned by
132 <function>sd_journal_open()</function> references a
133 specific journal entry as <emphasis>current</emphasis> entry,
134 similar to a file seek index in a classic file system
135 file, but without absolute positions. It may be
137 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
139 <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
140 and related calls. The current entry position may be
141 exported in <emphasis>cursor</emphasis> strings, as accessible
143 <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Cursor
144 strings may be used to globally identify a specific
145 journal entry in a stable way and then later to seek
146 to it (or if the specific entry is not available
147 locally, to its closest entry in time)
148 <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
150 <para>Notification of journal changes is available via
151 <function>sd_journal_get_fd()</function> and related
156 <title>Return Value</title>
158 <para>The <function>sd_journal_open()</function> and
159 <function>sd_journal_open_directory()</function> calls
160 return 0 on success or a negative errno-style error
161 code. <function>sd_journal_close()</function> returns
168 <para>The <function>sd_journal_open()</function>,
169 <function>sd_journal_open_directory()</function> and
170 <function>sd_journal_close()</function> interfaces are
171 available as shared library, which can be compiled and
173 <literal>libsystemd-journal</literal>
174 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
179 <title>History</title>
181 <para><function>sd_journal_open()</function>,
182 <function>sd_journal_close()</function>,
183 <literal>SD_JOURNAL_LOCAL_ONLY</literal>,
184 <literal>SD_JOURNAL_RUNTIME_ONLY</literal>,
185 <literal>SD_JOURNAL_SYSTEM_ONLY</literal> were added
186 in systemd-38.</para>
188 <para><function>sd_journal_open_directory()</function>
189 was added in systemd-187.</para>
191 <para><literal>SD_JOURNAL_SYSTEM</literal> and
192 <literal>SD_JOURNAL_CURRENT_USER</literal> were added
194 <literal>SD_JOURNAL_SYSTEM_ONLY</literal>
195 was deprecated.</para>
199 <title>See Also</title>
202 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
203 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
204 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
205 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>