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
 101                 the log journal for reading. It will find all journal
 102                 files automatically and interleave them automatically
 103                 when reading. As first argument it takes a pointer to
 104                 a <varname>sd_journal</varname> pointer, which on
 105                 success will contain a journal context object. The
 106                 second argument is a flags field, which may consist of
 107                 the following flags ORed together:
 108                 <constant>SD_JOURNAL_LOCAL_ONLY</constant> makes sure
 109                 only journal files generated on the local machine will
 110                 be opened. <constant>SD_JOURNAL_RUNTIME_ONLY</constant>
 111                 makes sure only volatile journal files will be opened,
 112                 excluding those which are stored on persistent
 113                 storage. <constant>SD_JOURNAL_SYSTEM</constant>
 114                 will cause journal files of system services and the
 115                 kernel (in opposition to user session processes) to
 116                 be opened. <constant>SD_JOURNAL_CURRENT_USER</constant>
 117                 will cause journal files of the current user to be
 118                 opened. If neither <constant>SD_JOURNAL_SYSTEM</constant>
 119                 nor <constant>SD_JOURNAL_CURRENT_USER</constant> are
 120                 specified, all journal file types will be opened.</para>
 121
 122                 <para><function>sd_journal_open_directory()</function>
 123                 is similar to <function>sd_journal_open()</function>
 124                 but takes an absolute directory path as argument. All
 125                 journal files in this directory will be opened and
 126                 interleaved automatically. This call also takes a
 127                 flags argument, but it must be passed as 0 as no flags
 128                 are currently understood for this call.</para>
 129
 130                 <para><function>sd_journal_open_files()</function>
 131                 is similar to <function>sd_journal_open()</function>
 132                 but takes a <constant>NULL</constant>-terminated list
 133                 of file paths to open. All files will be opened and
 134                 interleaved automatically. This call also takes a
 135                 flags argument, but it must be passed as 0 as no flags
 136                 are currently understood for this call. Please note
 137                 that in the case of a live journal, this function is only
 138                 useful for debugging, because individual journal files
 139                 can be rotated at any moment, and the opening of
 140                 specific files is inherently racy.</para>
 141
 142                 <para><function>sd_journal_open_container()</function>
 143                 is similar to <function>sd_journal_open()</function>
 144                 but opens the journal files of a running
 145                 OS container. The specified machine name refers to a
 146                 container that is registered with
 147                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 148
 149                 <para><varname>sd_journal</varname> objects cannot be
 150                 used in the child after a fork. Functions which take a
 151                 journal object as an argument
 152                 (<function>sd_journal_next()</function> and others)
 153                 will return <constant>-ECHILD</constant> after a fork.
 154                 </para>
 155
 156                 <para><function>sd_journal_close()</function> will
 157                 close the journal context allocated with
 158                 <function>sd_journal_open()</function> or
 159                 <function>sd_journal_open_directory()</function> and
 160                 free its resources.</para>
 161
 162                 <para>When opening the journal only journal files
 163                 accessible to the calling user will be opened. If
 164                 journal files are not accessible to the caller, this
 165                 will be silently ignored.</para>
 166
 167                 <para>See
 168                 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 169                 for an example of how to iterate through the journal
 170                 after opening it with
 171                 <function>sd_journal_open()</function>.</para>
 172
 173                 <para>A journal context object returned by
 174                 <function>sd_journal_open()</function> references a
 175                 specific journal entry as <emphasis>current</emphasis> entry,
 176                 similar to a file seek index in a classic file system
 177                 file, but without absolute positions. It may be
 178                 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
 183                 exported in <emphasis>cursor</emphasis> strings, as accessible
 184                 via
 185                 <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Cursor
 186                 strings may be used to globally identify a specific
 187                 journal entry in a stable way and then later to seek
 188                 to it (or if the specific entry is not available
 189                 locally, to its closest entry in time)
 190                 <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 191
 192                 <para>Notification of journal changes is available via
 193                 <function>sd_journal_get_fd()</function> and related
 194                 calls.</para>
 195         </refsect1>
 196
 197         <refsect1>
 198                 <title>Return Value</title>
 199
 200                 <para>The <function>sd_journal_open()</function>,
 201                 <function>sd_journal_open_directory()</function>, and
 202                 <function>sd_journal_open_files()</function> calls
 203                 return 0 on success or a negative errno-style error
 204                 code. <function>sd_journal_close()</function> returns
 205                 nothing.</para>
 206         </refsect1>
 207
 208         <refsect1>
 209                 <title>Notes</title>
 210
 211                 <para>The <function>sd_journal_open()</function>,
 212                 <function>sd_journal_open_directory()</function> and
 213                 <function>sd_journal_close()</function> interfaces are
 214                 available as a shared library, which can be compiled and
 215                 linked to with the
 216                 <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 217                 file.</para>
 218         </refsect1>
 219
 220         <refsect1>
 221                 <title>History</title>
 222
 223                 <para><function>sd_journal_open()</function>,
 224                 <function>sd_journal_close()</function>,
 225                 <constant>SD_JOURNAL_LOCAL_ONLY</constant>,
 226                 <constant>SD_JOURNAL_RUNTIME_ONLY</constant>,
 227                 <constant>SD_JOURNAL_SYSTEM_ONLY</constant> were added
 228                 in systemd-38.</para>
 229
 230                 <para><function>sd_journal_open_directory()</function>
 231                 was added in systemd-187.</para>
 232
 233                 <para><constant>SD_JOURNAL_SYSTEM</constant>,
 234                 <constant>SD_JOURNAL_CURRENT_USER</constant>,
 235                 and <function>sd_journal_open_files()</function>
 236                 were added in systemd-205.
 237                 <constant>SD_JOURNAL_SYSTEM_ONLY</constant>
 238                 was deprecated.</para>
 239         </refsect1>
 240
 241         <refsect1>
 242                 <title>See Also</title>
 243
 244                 <para>
 245                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 246                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 247                         <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 248                         <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 249                         <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 250                 </para>
 251         </refsect1>
 252
 253 </refentry>