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