diff options
Diffstat (limited to 'man/sd_journal_get_fd.xml')
| -rw-r--r-- | man/sd_journal_get_fd.xml | 272 |
1 files changed, 0 insertions, 272 deletions
diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml deleted file mode 100644 index 189d21352b..0000000000 --- a/man/sd_journal_get_fd.xml +++ /dev/null @@ -1,272 +0,0 @@ -<?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> |