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