sd_journal_open.xml 8.82 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2012 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="sd_journal_open">

        <refentryinfo>
                <title>sd_journal_open</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>sd_journal_open</refentrytitle>
                <manvolnum>3</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>sd_journal_open</refname>
                <refname>sd_journal_open_directory</refname>
                <refname>sd_journal_close</refname>
49 50 51 52
                <refname>sd_journal</refname>
                <refname>SD_JOURNAL_LOCAL_ONLY</refname>
                <refname>SD_JOURNAL_RUNTIME_ONLY</refname>
                <refname>SD_JOURNAL_SYSTEM_ONLY</refname>
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
                <refpurpose>Open the system journal for reading</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>

                        <funcprototype>
                                <funcdef>int <function>sd_journal_open</function></funcdef>
                                <paramdef>sd_journal** <parameter>ret</parameter></paramdef>
                                <paramdef>int <parameter>flags</parameter></paramdef>
                        </funcprototype>

                        <funcprototype>
                                <funcdef>int <function>sd_journal_open_directory</function></funcdef>
                                <paramdef>sd_journal** <parameter>ret</parameter></paramdef>
                                <paramdef>const char* <parameter>path</parameter></paramdef>
                                <paramdef>int <parameter>flags</parameter></paramdef>
                        </funcprototype>

                        <funcprototype>
                                <funcdef>int <function>sd_journal_close</function></funcdef>
                                <paramdef>sd_journal* <parameter>j</parameter></paramdef>
                        </funcprototype>
                </funcsynopsis>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para><function>sd_journal_open()</function> opens the
                the log journal for reading. It will find all journal
                files automatically and interleave them automatically
                when reading. As first argument it takes a pointer to
                a <literal>sd_journal</literal> pointer, which on
88
                success will contain journal context object afterwards. The
89 90 91 92 93 94 95
                second argument is a flags field, which may consist of
                the following flags ORed together:
                <literal>SD_JOURNAL_LOCAL_ONLY</literal> makes sure
                only journal files generated on the local machine will
                be opened. <literal>SD_JOURNAL_RUNTIME_ONLY</literal>
                makes sure only volatile journal files will be opened,
                excluding those which are stored on persistant
96
                storage. <literal>SD_JOURNAL_SYSTEM_ONLY</literal>
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
                will ensure that only journal files of system services
                and the kernel (in opposition to user session processes) will
                be opened.</para>

                <para><function>sd_journal_open_directory()</function>
                is similar to <function>sd_journal_open()</function>
                but takes an absolute directory path as argument. All
                journal files in this directory will be opened and
                interleaved automatically. This call also takes a
                flags argument, but it must be passed as 0 as no flags
                are currently understood for this call.</para>

                <para><function>sd_journal_close()</function> will
                close the journal context allocated with
                <function>sd_journal_open()</function> or
                <function>sd_journal_open_directory()</function> and
                free its resources.</para>

                <para>When opening the journal only journal files
                accessible to the calling user will be opened. If
                journal files are not accessible to the caller this
                will be silently ignored.</para>
119 120 121 122 123 124

                <para>See
                <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                for an example how to iterate through the journal
                after opening it it with
                <function>sd_journal_open()</function>.</para>
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143

                <para>A journal context object returned by
                <function>sd_journal_open()</function> references a
                specific journal entry as <emphasis>current</emphasis> entry,
                similar to a file seek index in a classic file system
                file, but without absolute positions. It may be
                altered with
                <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                and
                <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                and related calls. The current entry position may be
                exported in <emphasis>cursor</emphasis> strings, as accessible
                via
                <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Cursor
                strings may be used to globally identify a specific
                journal entry in a stable way and then later to seek
                to it (or if the specific entry is not available
                locally, to its closest entry in time)
                <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
144 145 146 147

                <para>Notification of journal changes is available via
                <function>sd_journal_get_fd()</function> and related
                calls.</para>
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
        </refsect1>

        <refsect1>
                <title>Return Value</title>

                <para>The <function>sd_journal_open()</function> and
                <function>sd_journal_open_directory()</function> calls
                return 0 on success or a negative errno-style error
                code. <function>sd_journal_close()</function> returns
                nothing.</para>
        </refsect1>

        <refsect1>
                <title>Notes</title>

                <para>The <function>sd_journal_open()</function>,
                <function>sd_journal_open_directory()</function> and
                <function>sd_journal_close()</function> interfaces are
                available as shared library, which can be compiled and
                linked to with the
                <literal>libsystemd-journal</literal>
                <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                file.</para>
        </refsect1>

        <refsect1>
                <title>See Also</title>

                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>