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