| <?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_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><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> |
| |
| </refentry> |