sd_journal_open_files.html 12.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_journal_open</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
    a.headerlink {
      color: #c60f0f;
      font-size: 0.8em;
      padding: 0 4px 0 4px;
      text-decoration: none;
      visibility: hidden;
    }

    a.headerlink:hover {
      background-color: #c60f0f;
      color: white;
    }

    h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
      visibility: visible;
    }
  </style><a href="index.html">Index </a>·
  <a href="systemd.directives.html">Directives </a>·
  <a href="../python-systemd/index.html">Python </a>·
  <a href="../libudev/index.html">libudev </a>·
Michael Biebl's avatar
Michael Biebl committed
22
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 215</span><hr><div class="refentry"><a name="sd_journal_open"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_journal_open, sd_journal_open_directory, sd_journal_open_files, sd_journal_open_container, sd_journal_close, sd_journal, SD_JOURNAL_LOCAL_ONLY, SD_JOURNAL_RUNTIME_ONLY, SD_JOURNAL_SYSTEM, SD_JOURNAL_CURRENT_USER — Open the system journal for reading</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;systemd/sd-journal.h&gt;</pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_open</b>(</code></td><td>sd_journal **<var class="pdparam">ret</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_open_directory</b>(</code></td><td>sd_journal **<var class="pdparam">ret</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">path</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_open_files</b>(</code></td><td>sd_journal **<var class="pdparam">ret</var>, </td></tr><tr><td> </td><td>const char **<var class="pdparam">paths</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_journal_open_container</b>(</code></td><td>sd_journal **<var class="pdparam">ret</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">machine</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">sd_journal_close</b>(</code></td><td>sd_journal *<var class="pdparam">j</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm214202620928"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description"></a></h2><p><code class="function">sd_journal_open()</code> opens
23 24 25
                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
Michael Biebl's avatar
Michael Biebl committed
26 27
                a <code class="varname">sd_journal</code> pointer, which on
                success will contain a journal context object. The
28 29
                second argument is a flags field, which may consist of
                the following flags ORed together:
Michael Biebl's avatar
Michael Biebl committed
30
                <code class="constant">SD_JOURNAL_LOCAL_ONLY</code> makes sure
31
                only journal files generated on the local machine will
Michael Biebl's avatar
Michael Biebl committed
32
                be opened. <code class="constant">SD_JOURNAL_RUNTIME_ONLY</code>
33 34
                makes sure only volatile journal files will be opened,
                excluding those which are stored on persistent
Michael Biebl's avatar
Michael Biebl committed
35 36 37 38 39 40 41 42
                storage. <code class="constant">SD_JOURNAL_SYSTEM</code>
                will cause journal files of system services and the
                kernel (in opposition to user session processes) to
                be opened. <code class="constant">SD_JOURNAL_CURRENT_USER</code>
                will cause journal files of the current user to be
                opened. If neither <code class="constant">SD_JOURNAL_SYSTEM</code>
                nor <code class="constant">SD_JOURNAL_CURRENT_USER</code> are
                specified, all journal file types will be opened.</p><p><code class="function">sd_journal_open_directory()</code>
43 44 45 46 47
                is similar to <code class="function">sd_journal_open()</code>
                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
Michael Biebl's avatar
Michael Biebl committed
48 49 50 51 52 53 54 55 56 57
                are currently understood for this call.</p><p><code class="function">sd_journal_open_files()</code>
                is similar to <code class="function">sd_journal_open()</code>
                but takes a <code class="constant">NULL</code>-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
58 59 60 61 62 63
                specific files is inherently racy.</p><p><code class="function">sd_journal_open_container()</code>
                is similar to <code class="function">sd_journal_open()</code>
                but opens the journal files of a running
                OS container. The specified machine name refers to a
                container that is registered with
                <a href="systemd-machined.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined</span>(8)</span></a>.</p><p><code class="varname">sd_journal</code> objects cannot be
Michael Biebl's avatar
Michael Biebl committed
64 65 66 67 68
                used in the child after a fork. Functions which take a
                journal object as an argument
                (<code class="function">sd_journal_next()</code> and others)
                will return <code class="constant">-ECHILD</code> after a fork.
                </p><p><code class="function">sd_journal_close()</code> will
69 70 71 72 73
                close the journal context allocated with
                <code class="function">sd_journal_open()</code> or
                <code class="function">sd_journal_open_directory()</code> and
                free its resources.</p><p>When opening the journal only journal files
                accessible to the calling user will be opened. If
Michael Biebl's avatar
Michael Biebl committed
74
                journal files are not accessible to the caller, this
75 76
                will be silently ignored.</p><p>See
                <a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>
Michael Biebl's avatar
Michael Biebl committed
77
                for an example of how to iterate through the journal
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
                after opening it with
                <code class="function">sd_journal_open()</code>.</p><p>A journal context object returned by
                <code class="function">sd_journal_open()</code> references a
                specific journal entry as <span class="emphasis"><em>current</em></span> entry,
                similar to a file seek index in a classic file system
                file, but without absolute positions. It may be
                altered with
                <a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>
                and
                <a href="sd_journal_seek_head.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_seek_head</span>(3)</span></a>
                and related calls. The current entry position may be
                exported in <span class="emphasis"><em>cursor</em></span> strings, as accessible
                via
                <a href="sd_journal_get_cursor.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_cursor</span>(3)</span></a>. 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)
                <a href="sd_journal_seek_cursor.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_seek_cursor</span>(3)</span></a>.</p><p>Notification of journal changes is available via
                <code class="function">sd_journal_get_fd()</code> and related
Michael Biebl's avatar
Michael Biebl committed
98
                calls.</p></div><div class="refsect1"><a name="idm214202586464"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value"></a></h2><p>The <code class="function">sd_journal_open()</code>,
Michael Biebl's avatar
Michael Biebl committed
99 100
                <code class="function">sd_journal_open_directory()</code>, and
                <code class="function">sd_journal_open_files()</code> calls
101 102
                return 0 on success or a negative errno-style error
                code. <code class="function">sd_journal_close()</code> returns
Michael Biebl's avatar
Michael Biebl committed
103
                nothing.</p></div><div class="refsect1"><a name="idm214202582256"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes"></a></h2><p>The <code class="function">sd_journal_open()</code>,
104 105
                <code class="function">sd_journal_open_directory()</code> and
                <code class="function">sd_journal_close()</code> interfaces are
Michael Biebl's avatar
Michael Biebl committed
106
                available as a shared library, which can be compiled and
107
                linked to with the
108
                <code class="constant">libsystemd</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
Michael Biebl's avatar
Michael Biebl committed
109
                file.</p></div><div class="refsect1"><a name="idm214197661808"></a><h2 id="History">History<a class="headerlink" title="Permalink to this headline" href="#History"></a></h2><p><code class="function">sd_journal_open()</code>,
Michael Biebl's avatar
Michael Biebl committed
110 111 112 113 114 115 116 117 118 119
                <code class="function">sd_journal_close()</code>,
                <code class="constant">SD_JOURNAL_LOCAL_ONLY</code>,
                <code class="constant">SD_JOURNAL_RUNTIME_ONLY</code>,
                <code class="constant">SD_JOURNAL_SYSTEM_ONLY</code> were added
                in systemd-38.</p><p><code class="function">sd_journal_open_directory()</code>
                was added in systemd-187.</p><p><code class="constant">SD_JOURNAL_SYSTEM</code>,
                <code class="constant">SD_JOURNAL_CURRENT_USER</code>,
                and <code class="function">sd_journal_open_files()</code>
                were added in systemd-205.
                <code class="constant">SD_JOURNAL_SYSTEM_ONLY</code>
Michael Biebl's avatar
Michael Biebl committed
120
                was deprecated.</p></div><div class="refsect1"><a name="idm214197655472"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
121 122 123
                        <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
                        <a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
                        <a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>,
124 125
                        <a href="sd_journal_get_data.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_data</span>(3)</span></a>,
                        <a href="systemd-machined.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined</span>(8)</span></a>
126
                </p></div></div></body></html>