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