sd_journal_open.xml revision 3bb55eee6aecdab6bfdbb670299fa59801145cb6
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering This file is part of systemd.
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering Copyright 2012 Lennart Poettering
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering systemd is free software; you can redistribute it and/or modify it
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering under the terms of the GNU Lesser General Public License as published by
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering the Free Software Foundation; either version 2.1 of the License, or
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering (at your option) any later version.
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering systemd is distributed in the hope that it will be useful, but
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering Lesser General Public License for more details.
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering You should have received a copy of the GNU Lesser General Public License
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <refentryinfo>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering </authorgroup>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering </refentryinfo>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <refentrytitle>sd_journal_open</refentrytitle>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <refname>sd_journal_open_directory</refname>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <refpurpose>Open the system journal for reading</refpurpose>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <refsynopsisdiv>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <funcsynopsis>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <funcprototype>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <funcdef>int <function>sd_journal_open</function></funcdef>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <paramdef>sd_journal** <parameter>ret</parameter></paramdef>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <paramdef>int <parameter>flags</parameter></paramdef>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering </funcprototype>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <funcprototype>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <funcdef>int <function>sd_journal_open_directory</function></funcdef>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <paramdef>sd_journal** <parameter>ret</parameter></paramdef>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <paramdef>const char* <parameter>path</parameter></paramdef>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <paramdef>int <parameter>flags</parameter></paramdef>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering </funcprototype>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <funcprototype>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <funcdef>int <function>sd_journal_close</function></funcdef>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <paramdef>sd_journal* <parameter>j</parameter></paramdef>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering </funcprototype>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering </funcsynopsis>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering </refsynopsisdiv>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <para><function>sd_journal_open()</function> opens the
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering the log journal for reading. It will find all journal
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering files automatically and interleave them automatically
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering when reading. As first argument it takes a pointer to
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering a <literal>sd_journal</literal> pointer, which on
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering success will contain journal context afterwards. The
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering second argument is a flags field, which may consist of
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering the following flags ORed together:
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <literal>SD_JOURNAL_LOCAL_ONLY</literal> makes sure
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering only journal files generated on the local machine will
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering be opened. <literal>SD_JOURNAL_RUNTIME_ONLY</literal>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering makes sure only volatile journal files will be opened,
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering excluding those which are stored on persistant
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering storage. <literal>SD_JOURNAL_RUNTIME_ONLY</literal>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering will ensure that only journal files of system services
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering and the kernel (in opposition to user session processes) will
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering be opened.</para>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <para><function>sd_journal_open_directory()</function>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering is similar to <function>sd_journal_open()</function>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering but takes an absolute directory path as argument. All
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering journal files in this directory will be opened and
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering interleaved automatically. This call also takes a
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering flags argument, but it must be passed as 0 as no flags
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering are currently understood for this call.</para>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <para><function>sd_journal_close()</function> will
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering close the journal context allocated with
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <function>sd_journal_open()</function> or
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <function>sd_journal_open_directory()</function> and
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering free its resources.</para>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <para>When opening the journal only journal files
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering accessible to the calling user will be opened. If
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering journal files are not accessible to the caller this
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering will be silently ignored.</para>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <para>The <function>sd_journal_open()</function> and
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <function>sd_journal_open_directory()</function> calls
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering return 0 on success or a negative errno-style error
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering code. <function>sd_journal_close()</function> returns
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering nothing.</para>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <para>The <function>sd_journal_open()</function>,
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <function>sd_journal_open_directory()</function> and
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <function>sd_journal_close()</function> interfaces are
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering available as shared library, which can be compiled and
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering linked to with the
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
c52f663bfa4f420044e6cd25bf84cec3c26ebf6fLennart Poettering <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>