man/sd_journal_open.xml

   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     <refname>SD_JOURNAL_TAKE_DIRECTORY_FD</refname>
  36     <refpurpose>Open the system journal for reading</refpurpose>
  37   </refnamediv>
  38
  39   <refsynopsisdiv>
  40     <funcsynopsis>
  41       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  42
  43       <funcprototype>
  44         <funcdef>int <function>sd_journal_open</function></funcdef>
  45         <paramdef>sd_journal **<parameter>ret</parameter></paramdef>
  46         <paramdef>int <parameter>flags</parameter></paramdef>
  47       </funcprototype>
  48
  49       <funcprototype>
  50         <funcdef>int <function>sd_journal_open_namespace</function></funcdef>
  51         <paramdef>sd_journal **<parameter>ret</parameter></paramdef>
  52         <paramdef>const char *<parameter>namespace</parameter></paramdef>
  53         <paramdef>int <parameter>flags</parameter></paramdef>
  54       </funcprototype>
  55
  56       <funcprototype>
  57         <funcdef>int <function>sd_journal_open_directory</function></funcdef>
  58         <paramdef>sd_journal **<parameter>ret</parameter></paramdef>
  59         <paramdef>const char *<parameter>path</parameter></paramdef>
  60         <paramdef>int <parameter>flags</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>int <function>sd_journal_open_directory_fd</function></funcdef>
  65         <paramdef>sd_journal **<parameter>ret</parameter></paramdef>
  66         <paramdef>int <parameter>fd</parameter></paramdef>
  67         <paramdef>int <parameter>flags</parameter></paramdef>
  68       </funcprototype>
  69
  70       <funcprototype>
  71         <funcdef>int <function>sd_journal_open_files</function></funcdef>
  72         <paramdef>sd_journal **<parameter>ret</parameter></paramdef>
  73         <paramdef>const char **<parameter>paths</parameter></paramdef>
  74         <paramdef>int <parameter>flags</parameter></paramdef>
  75       </funcprototype>
  76
  77       <funcprototype>
  78         <funcdef>int <function>sd_journal_open_files_fd</function></funcdef>
  79         <paramdef>sd_journal **<parameter>ret</parameter></paramdef>
  80         <paramdef>int <parameter>fds[]</parameter></paramdef>
  81         <paramdef>unsigned <parameter>n_fds</parameter></paramdef>
  82         <paramdef>int <parameter>flags</parameter></paramdef>
  83       </funcprototype>
  84
  85       <funcprototype>
  86         <funcdef>void <function>sd_journal_close</function></funcdef>
  87         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  88       </funcprototype>
  89     </funcsynopsis>
  90   </refsynopsisdiv>
  91
  92   <refsect1>
  93     <title>Description</title>
  94
  95     <para><function>sd_journal_open()</function> opens the log journal
  96     for reading. It will find all journal files automatically and
  97     interleave them automatically when reading. As first argument it
  98     takes a pointer to a <varname>sd_journal</varname> pointer, which,
  99     on success, will contain a journal context object. The second
 100     argument is a flags field, which may consist of the following
 101     flags ORed together: <constant>SD_JOURNAL_LOCAL_ONLY</constant>
 102     makes sure only journal files generated on the local machine will
 103     be opened. <constant>SD_JOURNAL_RUNTIME_ONLY</constant> makes sure
 104     only volatile journal files will be opened, excluding those which
 105     are stored on persistent storage.
 106     <constant>SD_JOURNAL_SYSTEM</constant> will cause journal files of
 107     system services and the kernel (in opposition to user session
 108     processes) to be opened.
 109     <constant>SD_JOURNAL_CURRENT_USER</constant> will cause journal
 110     files of the current user to be opened. If neither
 111     <constant>SD_JOURNAL_SYSTEM</constant> nor
 112     <constant>SD_JOURNAL_CURRENT_USER</constant> are specified, all
 113     journal file types will be opened.</para>
 114
 115     <para><function>sd_journal_open_namespace()</function> is similar to
 116     <function>sd_journal_open()</function> but takes an additional <parameter>namespace</parameter> parameter
 117     that specifies which journal namespace to operate on. If specified as <constant>NULL</constant> the call
 118     is identical to <function>sd_journal_open()</function>. If non-<constant>NULL</constant> only data from
 119     the namespace identified by the specified parameter is accessed. This call understands two additional
 120     flags: if <constant>SD_JOURNAL_ALL_NAMESPACES</constant> is specified the
 121     <parameter>namespace</parameter> parameter is ignored and all defined namespaces are accessed
 122     simultaneously; if <constant>SD_JOURNAL_INCLUDE_DEFAULT_NAMESPACE</constant> the specified namespace and
 123     the default namespace are accessed but no others (this flag has no effect when
 124     <parameter>namespace</parameter> is passed as <constant>NULL</constant>). For details about journal
 125     namespaces see
 126     <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 127
 128     <para><function>sd_journal_open_directory()</function> is similar to <function>sd_journal_open()</function> but
 129     takes an absolute directory path as argument. All journal files in this directory will be opened and interleaved
 130     automatically. This call also takes a flags argument. The flags parameters accepted by this call are
 131     <constant>SD_JOURNAL_OS_ROOT</constant>, <constant>SD_JOURNAL_SYSTEM</constant>, and
 132     <constant>SD_JOURNAL_CURRENT_USER</constant>. If <constant>SD_JOURNAL_OS_ROOT</constant> is specified, journal
 133     files are searched for below the usual <filename>/var/log/journal</filename> and
 134     <filename>/run/log/journal</filename> relative to the specified path, instead of directly beneath it.
 135     The other two flags limit which files are opened, the same as for <function>sd_journal_open()</function>.
 136     </para>
 137
 138     <para><function>sd_journal_open_directory_fd()</function> is similar to
 139     <function>sd_journal_open_directory()</function>, but takes a file descriptor referencing a directory in the file
 140     system instead of an absolute file system path. In addition to the flags accepted by
 141     <function>sd_journal_open_directory()</function>, this function also accepts
 142     <constant>SD_JOURNAL_TAKE_DIRECTORY_FD</constant>. If <constant>SD_JOURNAL_TAKE_DIRECTORY_FD</constant> is
 143     specified, the function will take the ownership of the specified file descriptor on success, and it will be
 144     closed by <function>sd_journal_close()</function>, hence the caller of the function must not close the file
 145     descriptor. When the flag is not specified, <function>sd_journal_close()</function> will not close the file
 146     descriptor, so the caller should close it after <function>sd_journal_close()</function>.</para>
 147
 148     <para><function>sd_journal_open_files()</function> is similar to <function>sd_journal_open()</function> but takes a
 149     <constant>NULL</constant>-terminated list of file paths to open.  All files will be opened and interleaved
 150     automatically. This call also takes a flags argument, but it must be passed as 0 as no flags are currently
 151     understood for this call. Please note that in the case of a live journal, this function is only useful for
 152     debugging, because individual journal files can be rotated at any moment, and the opening of specific files is
 153     inherently racy.</para>
 154
 155     <para><function>sd_journal_open_files_fd()</function> is similar to <function>sd_journal_open_files()</function>
 156     but takes an array of open file descriptors that must reference journal files, instead of an array of file system
 157     paths. Pass the array of file descriptors as second argument, and the number of array entries in the third. The
 158     flags parameter must be passed as 0.</para>
 159
 160     <para><varname>sd_journal</varname> objects cannot be used in the
 161     child after a fork. Functions which take a journal object as an
 162     argument (<function>sd_journal_next()</function> and others) will
 163     return <constant>-ECHILD</constant> after a fork.
 164     </para>
 165
 166     <para><function>sd_journal_close()</function> will close the
 167     journal context allocated with
 168     <function>sd_journal_open()</function> or
 169     <function>sd_journal_open_directory()</function> and free its
 170     resources.</para>
 171
 172     <para>When opening the journal only journal files accessible to
 173     the calling user will be opened. If journal files are not
 174     accessible to the caller, this will be silently ignored.</para>
 175
 176     <para>See
 177     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 178     for an example of how to iterate through the journal after opening
 179     it with <function>sd_journal_open()</function>.</para>
 180
 181     <para>A journal context object returned by
 182     <function>sd_journal_open()</function> references a specific
 183     journal entry as <emphasis>current</emphasis> entry, similar to a
 184     file seek index in a classic file system file, but without
 185     absolute positions. It may be altered with
 186     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 187     and
 188     <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 189     and related calls. The current entry position may be exported in
 190     <emphasis>cursor</emphasis> strings, as accessible via
 191     <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 192     Cursor strings may be used to globally identify a specific journal
 193     entry in a stable way and then later to seek to it (or if the
 194     specific entry is not available locally, to its closest entry in
 195     time)
 196     <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 197
 198     <para>Notification of journal changes is available via
 199     <function>sd_journal_get_fd()</function> and related calls.</para>
 200   </refsect1>
 201
 202   <refsect1>
 203     <title>Return Value</title>
 204
 205     <para>The <function>sd_journal_open()</function>,
 206     <function>sd_journal_open_directory()</function>, and
 207     <function>sd_journal_open_files()</function> calls return 0 on
 208     success or a negative errno-style error code.
 209     <function>sd_journal_close()</function> returns nothing.</para>
 210   </refsect1>
 211
 212   <refsect1>
 213     <title>Notes</title>
 214
 215     <xi:include href="threads-aware.xml" xpointer="strict"/>
 216
 217     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 218   </refsect1>
 219
 220   <refsect1>
 221     <title>History</title>
 222     <para><function>sd_journal_open()</function>,
 223     <function>sd_journal_open_directory()</function>, and
 224     <function>sd_journal_close()</function> were added in version 187.</para>
 225     <para><function>sd_journal_open_files()</function> was added in version 205.</para>
 226     <para><function>sd_journal_open_directory_fd()</function> and
 227     <function>sd_journal_open_files_fd()</function> were added in version 230.</para>
 228     <para><function>sd_journal_open_namespace()</function> was added in version 245.</para>
 229   </refsect1>
 230
 231   <refsect1>
 232     <title>See Also</title>
 233
 234     <para>
 235       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 236       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 237       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 238       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 239       <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 240     </para>
 241   </refsect1>
 242
 243 </refentry>