[systemd.git] / man / SD_JOURNAL_LOCAL_ONLY.html

<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>·
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 217</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="idm214171075312"></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
                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 <code class="varname">sd_journal</code> 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:
                <code class="constant">SD_JOURNAL_LOCAL_ONLY</code> makes sure
                only journal files generated on the local machine will
                be opened. <code class="constant">SD_JOURNAL_RUNTIME_ONLY</code>
                makes sure only volatile journal files will be opened,
                excluding those which are stored on persistent
                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>
                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
                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
                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
                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
                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
                journal files are not accessible to the caller, this
                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>
                for an example of how to iterate through the journal
                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
                calls.</p></div><div class="refsect1"><a name="idm214171040560"></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>,
                <code class="function">sd_journal_open_directory()</code>, and
                <code class="function">sd_journal_open_files()</code> calls
                return 0 on success or a negative errno-style error
                code. <code class="function">sd_journal_close()</code> returns
                nothing.</p></div><div class="refsect1"><a name="idm214171036352"></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>,
                <code class="function">sd_journal_open_directory()</code> and
                <code class="function">sd_journal_close()</code> interfaces are
                available as a shared library, which can be compiled and
                linked to with the
                <code class="constant">libsystemd</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
                file.</p></div><div class="refsect1"><a name="idm214166120416"></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>,
                <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>
                was deprecated.</p></div><div class="refsect1"><a name="idm214166114080"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
                        <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>,
                        <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>
                </p></div></div></body></html>
Commit	Line	Data
663996b3 MS	1	<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>
	2	a.headerlink {
	3	color: #c60f0f;
	4	font-size: 0.8em;
	5	padding: 0 4px 0 4px;
	6	text-decoration: none;
	7	visibility: hidden;
	8	}
	9
	10	a.headerlink:hover {
	11	background-color: #c60f0f;
	12	color: white;
	13	}
	14
	15	h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
	16	visibility: visible;
	17	}
	18	</style><a href="index.html">Index </a>·
	19	<a href="systemd.directives.html">Directives </a>·
	20	<a href="../python-systemd/index.html">Python </a>·
	21	<a href="../libudev/index.html">libudev </a>·
5eef597e	22	<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 217</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 <systemd/sd-journal.h></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="idm214171075312"></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
663996b3 MS	23	the log journal for reading. It will find all journal
	24	files automatically and interleave them automatically
	25	when reading. As first argument it takes a pointer to
14228c0d MB	26	a <code class="varname">sd_journal</code> pointer, which on
14228c0d MB	27	success will contain a journal context object. The
663996b3 MS	28	second argument is a flags field, which may consist of
663996b3 MS	29	the following flags ORed together:
14228c0d	30	<code class="constant">SD_JOURNAL_LOCAL_ONLY</code> makes sure
663996b3	31	only journal files generated on the local machine will
14228c0d	32	be opened. <code class="constant">SD_JOURNAL_RUNTIME_ONLY</code>
663996b3 MS	33	makes sure only volatile journal files will be opened,
663996b3 MS	34	excluding those which are stored on persistent
14228c0d MB	35	storage. <code class="constant">SD_JOURNAL_SYSTEM</code>
	36	will cause journal files of system services and the
	37	kernel (in opposition to user session processes) to
	38	be opened. <code class="constant">SD_JOURNAL_CURRENT_USER</code>
	39	will cause journal files of the current user to be
	40	opened. If neither <code class="constant">SD_JOURNAL_SYSTEM</code>
	41	nor <code class="constant">SD_JOURNAL_CURRENT_USER</code> are
	42	specified, all journal file types will be opened.</p><p><code class="function">sd_journal_open_directory()</code>
663996b3 MS	43	is similar to <code class="function">sd_journal_open()</code>
	44	but takes an absolute directory path as argument. All
	45	journal files in this directory will be opened and
	46	interleaved automatically. This call also takes a
	47	flags argument, but it must be passed as 0 as no flags
14228c0d MB	48	are currently understood for this call.</p><p><code class="function">sd_journal_open_files()</code>
	49	is similar to <code class="function">sd_journal_open()</code>
	50	but takes a <code class="constant">NULL</code>-terminated list
	51	of file paths to open. All files will be opened and
	52	interleaved automatically. This call also takes a
	53	flags argument, but it must be passed as 0 as no flags
	54	are currently understood for this call. Please note
	55	that in the case of a live journal, this function is only
	56	useful for debugging, because individual journal files
	57	can be rotated at any moment, and the opening of
60f067b4 JS	58	specific files is inherently racy.</p><p><code class="function">sd_journal_open_container()</code>
	59	is similar to <code class="function">sd_journal_open()</code>
	60	but opens the journal files of a running
	61	OS container. The specified machine name refers to a
	62	container that is registered with
	63	<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
14228c0d MB	64	used in the child after a fork. Functions which take a
	65	journal object as an argument
	66	(<code class="function">sd_journal_next()</code> and others)
	67	will return <code class="constant">-ECHILD</code> after a fork.
	68	</p><p><code class="function">sd_journal_close()</code> will
663996b3 MS	69	close the journal context allocated with
	70	<code class="function">sd_journal_open()</code> or
	71	<code class="function">sd_journal_open_directory()</code> and
	72	free its resources.</p><p>When opening the journal only journal files
	73	accessible to the calling user will be opened. If
14228c0d	74	journal files are not accessible to the caller, this
663996b3 MS	75	will be silently ignored.</p><p>See
663996b3 MS	76	<a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>
14228c0d	77	for an example of how to iterate through the journal
663996b3 MS	78	after opening it with
	79	<code class="function">sd_journal_open()</code>.</p><p>A journal context object returned by
	80	<code class="function">sd_journal_open()</code> references a
	81	specific journal entry as <span class="emphasis"><em>current</em></span> entry,
	82	similar to a file seek index in a classic file system
	83	file, but without absolute positions. It may be
	84	altered with
	85	<a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>
	86	and
	87	<a href="sd_journal_seek_head.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_seek_head</span>(3)</span></a>
	88	and related calls. The current entry position may be
	89	exported in <span class="emphasis"><em>cursor</em></span> strings, as accessible
	90	via
	91	<a href="sd_journal_get_cursor.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_cursor</span>(3)</span></a>. Cursor
	92	strings may be used to globally identify a specific
	93	journal entry in a stable way and then later to seek
	94	to it (or if the specific entry is not available
	95	locally, to its closest entry in time)
	96	<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
	97	<code class="function">sd_journal_get_fd()</code> and related
5eef597e	98	calls.</p></div><div class="refsect1"><a name="idm214171040560"></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>,
14228c0d MB	99	<code class="function">sd_journal_open_directory()</code>, and
14228c0d MB	100	<code class="function">sd_journal_open_files()</code> calls
663996b3 MS	101	return 0 on success or a negative errno-style error
663996b3 MS	102	code. <code class="function">sd_journal_close()</code> returns
5eef597e	103	nothing.</p></div><div class="refsect1"><a name="idm214171036352"></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>,
663996b3 MS	104	<code class="function">sd_journal_open_directory()</code> and
663996b3 MS	105	<code class="function">sd_journal_close()</code> interfaces are
14228c0d	106	available as a shared library, which can be compiled and
663996b3	107	linked to with the
5eef597e MP	108	<code class="constant">libsystemd</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
5eef597e MP	109	file.</p></div><div class="refsect1"><a name="idm214166120416"></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>,
14228c0d MB	110	<code class="function">sd_journal_close()</code>,
	111	<code class="constant">SD_JOURNAL_LOCAL_ONLY</code>,
	112	<code class="constant">SD_JOURNAL_RUNTIME_ONLY</code>,
	113	<code class="constant">SD_JOURNAL_SYSTEM_ONLY</code> were added
	114	in systemd-38.</p><p><code class="function">sd_journal_open_directory()</code>
	115	was added in systemd-187.</p><p><code class="constant">SD_JOURNAL_SYSTEM</code>,
	116	<code class="constant">SD_JOURNAL_CURRENT_USER</code>,
	117	and <code class="function">sd_journal_open_files()</code>
	118	were added in systemd-205.
	119	<code class="constant">SD_JOURNAL_SYSTEM_ONLY</code>
5eef597e	120	was deprecated.</p></div><div class="refsect1"><a name="idm214166114080"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
663996b3 MS	121	<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
	122	<a href="sd-journal.html"><span class="citerefentry"><span class="refentrytitle">sd-journal</span>(3)</span></a>,
	123	<a href="sd_journal_next.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_next</span>(3)</span></a>,
60f067b4 JS	124	<a href="sd_journal_get_data.html"><span class="citerefentry"><span class="refentrytitle">sd_journal_get_data</span>(3)</span></a>,
60f067b4 JS	125	<a href="systemd-machined.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined</span>(8)</span></a>
663996b3	126	</p></div></div></body></html>