man/sd_journal_open.xml

   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">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_journal_open"
  10           xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>sd_journal_open</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>sd_journal_open</refentrytitle>
  19     <manvolnum>3</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>sd_journal_open</refname>
  24     <refname>sd_journal_open_directory</refname>
  25     <refname>sd_journal_open_directory_fd</refname>
  26     <refname>sd_journal_open_files</refname>
  27     <refname>sd_journal_open_files_fd</refname>
  28     <refname>sd_journal_close</refname>
  29     <refname>sd_journal</refname>
  30     <refname>SD_JOURNAL_LOCAL_ONLY</refname>
  31     <refname>SD_JOURNAL_RUNTIME_ONLY</refname>
  32     <refname>SD_JOURNAL_SYSTEM</refname>
  33     <refname>SD_JOURNAL_CURRENT_USER</refname>
  34     <refname>SD_JOURNAL_OS_ROOT</refname>
  35     <refpurpose>Open the system journal for reading</refpurpose>
  36   </refnamediv>
  37
  38   <refsynopsisdiv>
  39     <funcsynopsis>
  40       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</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_directory</function></funcdef>
  50         <paramdef>sd_journal **<parameter>ret</parameter></paramdef>
  51         <paramdef>const char *<parameter>path</parameter></paramdef>
  52         <paramdef>int <parameter>flags</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>int <function>sd_journal_open_directory_fd</function></funcdef>
  57         <paramdef>sd_journal **<parameter>ret</parameter></paramdef>
  58         <paramdef>int <parameter>fd</parameter></paramdef>
  59         <paramdef>int <parameter>flags</parameter></paramdef>
  60       </funcprototype>
  61
  62       <funcprototype>
  63         <funcdef>int <function>sd_journal_open_files</function></funcdef>
  64         <paramdef>sd_journal **<parameter>ret</parameter></paramdef>
  65         <paramdef>const char **<parameter>paths</parameter></paramdef>
  66         <paramdef>int <parameter>flags</parameter></paramdef>
  67       </funcprototype>
  68
  69       <funcprototype>
  70         <funcdef>int <function>sd_journal_open_files_fd</function></funcdef>
  71         <paramdef>sd_journal **<parameter>ret</parameter></paramdef>
  72         <paramdef>int <parameter>fds[]</parameter></paramdef>
  73         <paramdef>unsigned <parameter>n_fds</parameter></paramdef>
  74         <paramdef>int <parameter>flags</parameter></paramdef>
  75       </funcprototype>
  76
  77       <funcprototype>
  78         <funcdef>void <function>sd_journal_close</function></funcdef>
  79         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  80       </funcprototype>
  81     </funcsynopsis>
  82   </refsynopsisdiv>
  83
  84   <refsect1>
  85     <title>Description</title>
  86
  87     <para><function>sd_journal_open()</function> opens the log journal
  88     for reading. It will find all journal files automatically and
  89     interleave them automatically when reading. As first argument it
  90     takes a pointer to a <varname>sd_journal</varname> pointer, which,
  91     on success, will contain a journal context object. The second
  92     argument is a flags field, which may consist of the following
  93     flags ORed together: <constant>SD_JOURNAL_LOCAL_ONLY</constant>
  94     makes sure only journal files generated on the local machine will
  95     be opened. <constant>SD_JOURNAL_RUNTIME_ONLY</constant> makes sure
  96     only volatile journal files will be opened, excluding those which
  97     are stored on persistent storage.
  98     <constant>SD_JOURNAL_SYSTEM</constant> will cause journal files of
  99     system services and the kernel (in opposition to user session
 100     processes) to be opened.
 101     <constant>SD_JOURNAL_CURRENT_USER</constant> will cause journal
 102     files of the current user to be opened. If neither
 103     <constant>SD_JOURNAL_SYSTEM</constant> nor
 104     <constant>SD_JOURNAL_CURRENT_USER</constant> are specified, all
 105     journal file types will be opened.</para>
 106
 107     <para><function>sd_journal_open_directory()</function> is similar to <function>sd_journal_open()</function> but
 108     takes an absolute directory path as argument. All journal files in this directory will be opened and interleaved
 109     automatically. This call also takes a flags argument. The flags parameters accepted by this call are
 110     <constant>SD_JOURNAL_OS_ROOT</constant>, <constant>SD_JOURNAL_SYSTEM</constant>, and
 111     <constant>SD_JOURNAL_CURRENT_USER</constant>. If <constant>SD_JOURNAL_OS_ROOT</constant> is specified, journal
 112     files are searched for below the usual <filename>/var/log/journal</filename> and
 113     <filename>/run/log/journal</filename> relative to the specified path, instead of directly beneath it.
 114     The other two flags limit which files are opened, the same as for <function>sd_journal_open()</function>.
 115     </para>
 116
 117     <para><function>sd_journal_open_directory_fd()</function> is similar to
 118     <function>sd_journal_open_directory()</function>, but takes a file descriptor referencing a directory in the file
 119     system instead of an absolute file system path.</para>
 120
 121     <para><function>sd_journal_open_files()</function> is similar to <function>sd_journal_open()</function> but takes a
 122     <constant>NULL</constant>-terminated list of file paths to open.  All files will be opened and interleaved
 123     automatically. This call also takes a flags argument, but it must be passed as 0 as no flags are currently
 124     understood for this call. Please note that in the case of a live journal, this function is only useful for
 125     debugging, because individual journal files can be rotated at any moment, and the opening of specific files is
 126     inherently racy.</para>
 127
 128     <para><function>sd_journal_open_files_fd()</function> is similar to <function>sd_journal_open_files()</function>
 129     but takes an array of open file descriptors that must reference journal files, instead of an array of file system
 130     paths. Pass the array of file descriptors as second argument, and the number of array entries in the third. The
 131     flags parameter must be passed as 0.</para>
 132
 133     <para><varname>sd_journal</varname> objects cannot be used in the
 134     child after a fork. Functions which take a journal object as an
 135     argument (<function>sd_journal_next()</function> and others) will
 136     return <constant>-ECHILD</constant> after a fork.
 137     </para>
 138
 139     <para><function>sd_journal_close()</function> will close the
 140     journal context allocated with
 141     <function>sd_journal_open()</function> or
 142     <function>sd_journal_open_directory()</function> and free its
 143     resources.</para>
 144
 145     <para>When opening the journal only journal files accessible to
 146     the calling user will be opened. If journal files are not
 147     accessible to the caller, this will be silently ignored.</para>
 148
 149     <para>See
 150     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 151     for an example of how to iterate through the journal after opening
 152     it with <function>sd_journal_open()</function>.</para>
 153
 154     <para>A journal context object returned by
 155     <function>sd_journal_open()</function> references a specific
 156     journal entry as <emphasis>current</emphasis> entry, similar to a
 157     file seek index in a classic file system file, but without
 158     absolute positions. It may be altered with
 159     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 160     and
 161     <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 162     and related calls. The current entry position may be exported in
 163     <emphasis>cursor</emphasis> strings, as accessible via
 164     <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 165     Cursor strings may be used to globally identify a specific journal
 166     entry in a stable way and then later to seek to it (or if the
 167     specific entry is not available locally, to its closest entry in
 168     time)
 169     <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 170
 171     <para>Notification of journal changes is available via
 172     <function>sd_journal_get_fd()</function> and related calls.</para>
 173   </refsect1>
 174
 175   <refsect1>
 176     <title>Return Value</title>
 177
 178     <para>The <function>sd_journal_open()</function>,
 179     <function>sd_journal_open_directory()</function>, and
 180     <function>sd_journal_open_files()</function> calls return 0 on
 181     success or a negative errno-style error code.
 182     <function>sd_journal_close()</function> returns nothing.</para>
 183   </refsect1>
 184
 185   <refsect1>
 186     <title>Notes</title>
 187
 188     <xi:include href="threads-aware.xml" xpointer="strict"/>
 189
 190     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 191   </refsect1>
 192
 193   <refsect1>
 194     <title>See Also</title>
 195
 196     <para>
 197       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 198       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 199       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 200       <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 201       <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 202     </para>
 203   </refsect1>
 204
 205 </refentry>