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_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 &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_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>