1<?xml version='1.0'?> <!--*-nxml-*--> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_journal_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_journal_get_fd</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_journal_get_fd</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_journal_get_fd</refname> 20 <refname>sd_journal_get_events</refname> 21 <refname>sd_journal_get_timeout</refname> 22 <refname>sd_journal_process</refname> 23 <refname>sd_journal_wait</refname> 24 <refname>sd_journal_reliable_fd</refname> 25 <refname>SD_JOURNAL_NOP</refname> 26 <refname>SD_JOURNAL_APPEND</refname> 27 <refname>SD_JOURNAL_INVALIDATE</refname> 28 <refpurpose>Journal change notification 29 interface</refpurpose> 30 </refnamediv> 31 32 <refsynopsisdiv> 33 <funcsynopsis> 34 <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> 35 36 <funcprototype> 37 <funcdef>int <function>sd_journal_get_fd</function></funcdef> 38 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 39 </funcprototype> 40 41 <funcprototype> 42 <funcdef>int <function>sd_journal_get_events</function></funcdef> 43 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 44 </funcprototype> 45 46 <funcprototype> 47 <funcdef>int <function>sd_journal_get_timeout</function></funcdef> 48 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 49 <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef> 50 </funcprototype> 51 52 <funcprototype> 53 <funcdef>int <function>sd_journal_process</function></funcdef> 54 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 55 </funcprototype> 56 57 <funcprototype> 58 <funcdef>int <function>sd_journal_wait</function></funcdef> 59 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 60 <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef> 61 </funcprototype> 62 63 <funcprototype> 64 <funcdef>int <function>sd_journal_reliable_fd</function></funcdef> 65 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 66 </funcprototype> 67 68 </funcsynopsis> 69 </refsynopsisdiv> 70 71 <refsect1> 72 <title>Description</title> 73 74 <para><function>sd_journal_get_fd()</function> returns a file 75 descriptor that may be asynchronously polled in an external event 76 loop and is signaled as soon as the journal changes, because new 77 entries or files were added, rotation took place, or files have 78 been deleted, and similar. The file descriptor is suitable for 79 usage in 80 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>. 81 Use <function>sd_journal_get_events()</function> for an events 82 mask to watch for. The call takes one argument: the journal 83 context object. Note that not all file systems are capable of 84 generating the necessary events for wakeups from this file 85 descriptor for changes to be noticed immediately. In particular 86 network files systems do not generate suitable file change events 87 in all cases. Cases like this can be detected with 88 <function>sd_journal_reliable_fd()</function>, below. 89 <function>sd_journal_get_timeout()</function> will ensure in these 90 cases that wake-ups happen frequently enough for changes to be 91 noticed, although with a certain latency.</para> 92 93 <para><function>sd_journal_get_events()</function> will return the 94 <function>poll()</function> mask to wait for. This function will 95 return a combination of <constant>POLLIN</constant> and 96 <constant>POLLOUT</constant> and similar to fill into the 97 <literal>.events</literal> field of <varname>struct 98 pollfd</varname>.</para> 99 100 <para><function>sd_journal_get_timeout()</function> will return a 101 timeout value for usage in <function>poll()</function>. This 102 returns a value in microseconds since the epoch of 103 <constant>CLOCK_MONOTONIC</constant> for timing out 104 <function>poll()</function> in <varname>timeout_usec</varname>. 105 See 106 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> 107 for details about <constant>CLOCK_MONOTONIC</constant>. If there 108 is no timeout to wait for, this will fill in <constant>(uint64_t) 109 -1</constant> instead. Note that <function>poll()</function> takes 110 a relative timeout in milliseconds rather than an absolute timeout 111 in microseconds. To convert the absolute 'us' timeout into 112 relative 'ms', use code like the following:</para> 113 114 <programlisting>uint64_t t; 115int msec; 116sd_journal_get_timeout(m, &t); 117if (t == (uint64_t) -1) 118 msec = -1; 119else { 120 struct timespec ts; 121 uint64_t n; 122 clock_gettime(CLOCK_MONOTONIC, &ts); 123 n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; 124 msec = t > n ? (int) ((t - n + 999) / 1000) : 0; 125}</programlisting> 126 127 <para>The code above does not do any error checking for brevity's 128 sake. The calculated <varname>msec</varname> integer can be passed 129 directly as <function>poll()</function>'s timeout 130 parameter.</para> 131 132 <para>After each <function>poll()</function> wake-up 133 <function>sd_journal_process()</function> needs to be called to 134 process events. This call will also indicate what kind of change 135 has been detected (see below; note that spurious wake-ups are 136 possible).</para> 137 138 <para>A synchronous alternative for using 139 <function>sd_journal_get_fd()</function>, 140 <function>sd_journal_get_events()</function>, 141 <function>sd_journal_get_timeout()</function> and 142 <function>sd_journal_process()</function> is 143 <function>sd_journal_wait()</function>. It will synchronously wait 144 until the journal gets changed. The maximum time this call sleeps 145 may be controlled with the <parameter>timeout_usec</parameter> 146 parameter. Pass <constant>(uint64_t) -1</constant> to wait 147 indefinitely. Internally this call simply combines 148 <function>sd_journal_get_fd()</function>, 149 <function>sd_journal_get_events()</function>, 150 <function>sd_journal_get_timeout()</function>, 151 <function>poll()</function> and 152 <function>sd_journal_process()</function> into one.</para> 153 154 <para><function>sd_journal_reliable_fd()</function> may be used to check whether the wake-up events from 155 the file descriptor returned by <function>sd_journal_get_fd()</function> are known to be quickly 156 triggered. On certain file systems where file change events from the OS are not available (such as NFS) 157 changes need to be polled for repeatedly, and hence are detected only with a considerable latency. This 158 call will return a positive value if the journal changes are detected quickly and zero when they need to 159 be polled for. Note that there is usually no need to invoke this function directly as 160 <function>sd_journal_get_timeout()</function> will request appropriate timeouts anyway.</para> 161 162 <para>Note that all of the above change notification interfaces do not report changes 163 instantly. Latencies are introduced for multiple reasons: as mentioned certain storage backends require 164 time-based polling, in other cases wake-ups are optimized by coalescing events, and the OS introduces 165 additional IO/CPU scheduling latencies.</para> 166 </refsect1> 167 168 <refsect1> 169 <title>Return Value</title> 170 171 <para><function>sd_journal_get_fd()</function> returns a valid 172 file descriptor on success or a negative errno-style error 173 code.</para> 174 175 <para><function>sd_journal_get_events()</function> returns a 176 combination of <constant>POLLIN</constant>, 177 <constant>POLLOUT</constant> and suchlike on success or a negative 178 errno-style error code.</para> 179 180 <para><function>sd_journal_reliable_fd()</function> returns a 181 positive integer if the file descriptor returned by 182 <function>sd_journal_get_fd()</function> will generate wake-ups 183 immediately for all journal changes. Returns 0 if there might be a 184 latency involved.</para> 185 186 <para><function>sd_journal_process()</function> and <function>sd_journal_wait()</function> return a negative 187 errno-style error code, or one of <constant>SD_JOURNAL_NOP</constant>, <constant>SD_JOURNAL_APPEND</constant> or 188 <constant>SD_JOURNAL_INVALIDATE</constant> on success:</para> 189 190 <itemizedlist> 191 <listitem><para>If <constant>SD_JOURNAL_NOP</constant> is returned, the journal did not change since the last 192 invocation.</para></listitem> 193 194 <listitem><para>If <constant>SD_JOURNAL_APPEND</constant> is returned, new entries have been appended to the end 195 of the journal. In this case it is sufficient to simply continue reading at the previous end location of the 196 journal, to read the newly added entries.</para></listitem> 197 198 <listitem><para>If <constant>SD_JOURNAL_INVALIDATE</constant>, journal files were added to or removed from the 199 set of journal files watched (e.g. due to rotation or vacuuming), and thus entries might have appeared or 200 disappeared at arbitrary places in the log stream, possibly before or after the previous end of the log 201 stream. If <constant>SD_JOURNAL_INVALIDATE</constant> is returned, live-view UIs that want to reflect on screen 202 the precise state of the log data on disk should probably refresh their entire display (relative to the cursor of 203 the log entry on the top of the screen). Programs only interested in a strictly sequential stream of log data may 204 treat <constant>SD_JOURNAL_INVALIDATE</constant> the same way as <constant>SD_JOURNAL_APPEND</constant>, thus 205 ignoring any changes to the log view earlier than the old end of the log stream.</para></listitem> 206 </itemizedlist> 207 </refsect1> 208 209 <refsect1> 210 <title>Signal safety</title> 211 212 <para>In general, <function>sd_journal_get_fd()</function>, <function>sd_journal_get_events()</function>, and 213 <function>sd_journal_get_timeout()</function> are <emphasis>not</emphasis> "async signal safe" in the meaning of 214 <citerefentry 215 project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>. 216 Nevertheless, only the first call to any of those three functions performs unsafe operations, so subsequent calls 217 <emphasis>are</emphasis> safe.</para> 218 219 <para><function>sd_journal_process()</function> and <function>sd_journal_wait()</function> are not 220 safe. <function>sd_journal_reliable_fd()</function> is safe.</para> 221 </refsect1> 222 223 <refsect1> 224 <title>Notes</title> 225 226 <xi:include href="threads-aware.xml" xpointer="strict"/> 227 228 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> 229 </refsect1> 230 231 <refsect1> 232 <title>Examples</title> 233 234 <para>Iterating through the journal, in a live view tracking all 235 changes:</para> 236 237 <programlisting><xi:include href="journal-iterate-wait.c" parse="text" /></programlisting> 238 239 <para>Waiting with <function>poll()</function> (this 240 example lacks all error checking for the sake of 241 simplicity):</para> 242 243 <programlisting><xi:include href="journal-iterate-poll.c" parse="text" /></programlisting> 244 </refsect1> 245 246 <refsect1> 247 <title>See Also</title> 248 249 <para> 250 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 251 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 252 <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 253 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 254 <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, 255 <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> 256 </para> 257 </refsect1> 258 259</refentry> 260