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