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