2012-07-13 17:49:34 +04:00
<?xml version='1.0'?> <!-- * - nxml - * -->
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2015-02-04 05:14:13 +03:00
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
2012-07-13 17:49:34 +04:00
<!--
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: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
<refentry id= "sd_journal_open" >
2015-02-04 05:14:13 +03:00
<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_open_files</refname>
<refname > sd_journal_open_container</refname>
<refname > sd_journal_close</refname>
<refname > sd_journal</refname>
<refname > SD_JOURNAL_LOCAL_ONLY</refname>
<refname > SD_JOURNAL_RUNTIME_ONLY</refname>
<refname > SD_JOURNAL_SYSTEM</refname>
<refname > SD_JOURNAL_CURRENT_USER</refname>
<refpurpose > Open the system journal for reading</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-journal.h> </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_open_files</function> </funcdef>
<paramdef > sd_journal **<parameter > ret</parameter> </paramdef>
<paramdef > const char **<parameter > paths</parameter> </paramdef>
<paramdef > int <parameter > flags</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_journal_open_container</function> </funcdef>
<paramdef > sd_journal **<parameter > ret</parameter> </paramdef>
<paramdef > const char *<parameter > machine</parameter> </paramdef>
<paramdef > int <parameter > flags</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > void <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 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 <varname > sd_journal</varname> pointer, which
on success will contain a journal context object. The second
argument is a flags field, which may consist of the following
flags ORed together: <constant > SD_JOURNAL_LOCAL_ONLY</constant>
makes sure only journal files generated on the local machine will
be opened. <constant > SD_JOURNAL_RUNTIME_ONLY</constant> makes sure
only volatile journal files will be opened, excluding those which
are stored on persistent storage.
<constant > SD_JOURNAL_SYSTEM</constant> will cause journal files of
system services and the kernel (in opposition to user session
processes) to be opened.
<constant > SD_JOURNAL_CURRENT_USER</constant> will cause journal
files of the current user to be opened. If neither
<constant > SD_JOURNAL_SYSTEM</constant> nor
<constant > SD_JOURNAL_CURRENT_USER</constant> are specified, all
journal file types 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_open_files()</function> is similar to
<function > sd_journal_open()</function> but takes a
<constant > NULL</constant> -terminated list of file paths to open.
All files 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. Please note that in
the case of a live journal, this function is only useful for
debugging, because individual journal files can be rotated at any
moment, and the opening of specific files is inherently
racy.</para>
<para > <function > sd_journal_open_container()</function> is similar
to <function > sd_journal_open()</function> but opens the journal
files of a running OS container. The specified machine name refers
to a container that is registered with
<citerefentry > <refentrytitle > systemd-machined</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> .</para>
<para > <varname > sd_journal</varname> objects cannot be used in the
child after a fork. Functions which take a journal object as an
argument (<function > sd_journal_next()</function> and others) will
return <constant > -ECHILD</constant> after a fork.
</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>
<para > See
<citerefentry > <refentrytitle > sd_journal_next</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
for an example of how to iterate through the journal after opening
it with <function > sd_journal_open()</function> .</para>
<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>
<para > Notification of journal changes is available via
<function > sd_journal_get_fd()</function> and related calls.</para>
</refsect1>
<refsect1 >
<title > Return Value</title>
<para > The <function > sd_journal_open()</function> ,
<function > sd_journal_open_directory()</function> , and
<function > sd_journal_open_files()</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 a shared library, which can be compiled and linked to with the
<constant > libsystemd</constant> <citerefentry project= 'die-net' > <refentrytitle > pkg-config</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry>
file.</para>
</refsect1>
<refsect1 >
<title > History</title>
<para > <function > sd_journal_open()</function> ,
<function > sd_journal_close()</function> ,
<constant > SD_JOURNAL_LOCAL_ONLY</constant> ,
<constant > SD_JOURNAL_RUNTIME_ONLY</constant> ,
<constant > SD_JOURNAL_SYSTEM_ONLY</constant> were added in
systemd-38.</para>
<para > <function > sd_journal_open_directory()</function> was added
in systemd-187.</para>
<para > <constant > SD_JOURNAL_SYSTEM</constant> ,
<constant > SD_JOURNAL_CURRENT_USER</constant> , and
<function > sd_journal_open_files()</function> were added in
systemd-205. <constant > SD_JOURNAL_SYSTEM_ONLY</constant> was
deprecated.</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> ,
<citerefentry > <refentrytitle > systemd-machined</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry>
</para>
</refsect1>
2012-07-13 17:49:34 +04:00
</refentry>
