diff options
Diffstat (limited to 'man/sd_journal_get_fd.xml')
| -rw-r--r-- | man/sd_journal_get_fd.xml | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml new file mode 100644 index 0000000000..189d21352b --- /dev/null +++ b/man/sd_journal_get_fd.xml @@ -0,0 +1,272 @@ +<?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_get_fd"> + + <refentryinfo> + <title>sd_journal_get_fd</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_get_fd</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_fd</refname> + <refname>sd_journal_reliable_fd</refname> + <refname>sd_journal_process</refname> + <refname>sd_journal_wait</refname> + <refname>SD_JOURNAL_NOP</refname> + <refname>SD_JOURNAL_APPEND</refname> + <refname>SD_JOURNAL_INVALIDATE</refname> + <refpurpose>Journal change notification + interface</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_fd</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_reliable_fd</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_process</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_wait</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_fd()</function> returns + a file descriptor that may be asynchronously polled in + an external event loop and is signaled readable as + soon as the journal changes, because new entries or + files were added, rotation took place, or files have + been deleted, and similar. The file descriptor is + suitable for usage in + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry> + where it will yield POLLIN on changes. The call takes + one argument: the journal context object. Note that + not all file systems are capable of generating the + necessary events for wakeups from this file descriptor + to be enirely reliable. In particular network files + systems do not generate suitable file change events in + all cases. In such a case an application should not + rely alone on wake-ups from this file descriptor but + wake up and recheck the journal in regular time + intervals, for example every 2s. To detect + cases where this is necessary, use + <function>sd_journal_reliable_fd()</function>, + below.</para> + + <para><function>sd_journal_reliable_fd()</function> + may be used to check whether the wakeup events from + the file descriptor returned by + <function>sd_journal_get_fd</function> are sufficient + to track changes to the journal. If this call returns + 0, it is necessary to regularly recheck for journal + changes (suggestion: every 2s). If this call returns a + positive integer this is not necessary, and wakeups + from the file descriptor returned by + <function>sd_journal_get_fd()</function> are + sufficient as only source for wake-ups.</para> + + <para>After each POLLIN wake-up + <function>sd_journal_process()</function> needs to be + called to process events and reset the readable state + of the file descriptor. This call will also indicate + what kind of change has been detected (see below; note + that spurious wake-ups are possible).</para> + + <para>A synchronous alternative for using + <function>sd_journal_get_fd()</function>, + <function>sd_journal_reliable_fd()</function> and + <function>sd_journal_process()</function> is + <function>sd_journal_wait()</function>. It will + synchronously wait until the journal gets changed, + possibly using a 2s time-out if this is necessary (see + above). In either way the maximum time this call + sleeps may be controlled with the + <parameter>timeout_usec</parameter> parameter. Pass + <literal>(uint64_t) -1</literal> to wait + indefinitely. Internally this call simply combines + <function>sd_journal_get_fd()</function>, + <function>sd_journal_reliable_fd()</function>, + <function>poll()</function> and + <function>sd_journal_process()</function> into + one.</para> + + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_fd()</function> returns a valid file descriptor on success or a negative errno-style error + code.</para> + + <para><function>sd_journal_reliable_fd()</function> + returns a positive integer if the file descriptor + returned by <function>sd_journal_get_fd()</function> + is sufficient as sole wake-up source for journal + change events. Returns 0 if it is not sufficient and + the journal needs to be checked manually in regular + time intervals for changes. Returns a negative + errno-style error code on failure.</para> + + <para><function>sd_journal_process()</function> and + <function>sd_journal_wait()</function> return one of + <literal>SD_JOURNAL_NOP</literal>, + <literal>SD_JOURNAL_APPEND</literal> or + <literal>SD_JOURNAL_INVALIDATE</literal> on success or + a negative errno-style error code. If + <literal>SD_JOURNAL_NOP</literal> is returned the + journal didn't change since the last invocation. If + <literal>SD_JOURNAL_APPEND</literal> is returned new + entries have been appended to the end of the + journal. If <literal>SD_JOURNAL_INVALIDATE</literal> + journal files were added or removed (possibly due to + rotation). In the latter event live-view UIs should + probably refresh their entire display while in the + case of <literal>SD_JOURNAL_APPEND</literal> it is + sufficient to simply continue reading at the previous + end of the journal.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_get_fd()</function>, + <function>sd_journal_reliable_fd()</function>, + <function>sd_journal_process()</function> and + <function>sd_journal_wait()</function> interfaces are + available as shared library, which can be compiled and + linked to with the + <literal>libsystemd-journal</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Iterating through the journal, in a live view tracking all changes:</para> + + <programlisting>#include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + int r; + sd_journal *j; + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + for (;;) { + const char *d; + size_t l; + r = sd_journal_next(j); + if (r < 0) { + fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r)); + break; + } + if (r == 0) { + /* Reached the end, let's wait for changes, and try again */ + r = sd_journal_wait(j, (uint64_t) -1); + if (r < 0) { + fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r)); + break; + } + continue; + } + r = sd_journal_get_data(j, "MESSAGE", &d, &l); + if (r < 0) { + fprintf(stderr, "Failed to read message field: %s\n", strerror(-r)); + continue; + } + printf("%.*s\n", (int) l, d); + } + sd_journal_close(j); + return 0; +}</programlisting> + + <para>Waiting with <function>poll()</function> (this + example lacks all error checking for the sake of + simplicity):</para> + + <programlisting>#include <sys/poll.h> +#include <systemd/sd-journal.h> + +int wait_for_changes(sd_journal *j) { + struct pollfd pollfd; + pollfd.fd = sd_journal_get_fd(); + pollfd.events = POLLIN; + poll(&pollfd, 1, sd_journal_reliable_fd() > 0 ? -1 : 2000); + return sd_journal_process(j); +} + </programlisting> + </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_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |