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-or-later --> 5 6<refentry id="sd_journal_open" 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 9 <refentryinfo> 10 <title>sd_journal_open</title> 11 <productname>systemd</productname> 12 </refentryinfo> 13 14 <refmeta> 15 <refentrytitle>sd_journal_open</refentrytitle> 16 <manvolnum>3</manvolnum> 17 </refmeta> 18 19 <refnamediv> 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> 36 </refnamediv> 37 38 <refsynopsisdiv> 39 <funcsynopsis> 40 <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> 41 42 <funcprototype> 43 <funcdef>int <function>sd_journal_open</function></funcdef> 44 <paramdef>sd_journal **<parameter>ret</parameter></paramdef> 45 <paramdef>int <parameter>flags</parameter></paramdef> 46 </funcprototype> 47 48 <funcprototype> 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> 53 </funcprototype> 54 55 <funcprototype> 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> 60 </funcprototype> 61 62 <funcprototype> 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> 67 </funcprototype> 68 69 <funcprototype> 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> 74 </funcprototype> 75 76 <funcprototype> 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> 82 </funcprototype> 83 84 <funcprototype> 85 <funcdef>void <function>sd_journal_close</function></funcdef> 86 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 87 </funcprototype> 88 </funcsynopsis> 89 </refsynopsisdiv> 90 91 <refsect1> 92 <title>Description</title> 93 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> 113 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 124 namespaces see 125 <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> 126 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>. 135 </para> 136 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> 140 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> 147 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> 152 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. 157 </para> 158 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 163 resources.</para> 164 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> 168 169 <para>See 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> 173 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> 180 and 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 188 time) 189 <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> 190 191 <para>Notification of journal changes is available via 192 <function>sd_journal_get_fd()</function> and related calls.</para> 193 </refsect1> 194 195 <refsect1> 196 <title>Return Value</title> 197 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> 203 </refsect1> 204 205 <refsect1> 206 <title>Notes</title> 207 208 <xi:include href="threads-aware.xml" xpointer="strict"/> 209 210 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> 211 </refsect1> 212 213 <refsect1> 214 <title>See Also</title> 215 216 <para> 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> 222 </para> 223 </refsect1> 224 225</refentry> 226