diff options
Diffstat (limited to 'man/sd_journal_get_fd.xml')
| -rw-r--r-- | man/sd_journal_get_fd.xml | 332 |
1 files changed, 0 insertions, 332 deletions
diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml deleted file mode 100644 index 61293f7f99..0000000000 --- a/man/sd_journal_get_fd.xml +++ /dev/null @@ -1,332 +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_get_events</refname> - <refname>sd_journal_get_timeout</refname> - <refname>sd_journal_process</refname> - <refname>sd_journal_wait</refname> - <refname>sd_journal_reliable_fd</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_get_events</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_get_timeout</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>uint64_t *<parameter>timeout_usec</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> - - <funcprototype> - <funcdef>int <function>sd_journal_reliable_fd</function></funcdef> - <paramdef>sd_journal *<parameter>j</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 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>. - Use <function>sd_journal_get_events()</function> for an events - mask to watch for. 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 for changes to be noticed immediately. In particular - network files systems do not generate suitable file change events - in all cases. Cases like this can be detected with - <function>sd_journal_reliable_fd()</function>, below. - <function>sd_journal_get_timeout()</function> will ensure in these - cases that wake-ups happen frequently enough for changes to be - noticed, although with a certain latency.</para> - - <para><function>sd_journal_get_events()</function> will return the - <function>poll()</function> mask to wait for. This function will - return a combination of <constant>POLLIN</constant> and - <constant>POLLOUT</constant> and similar to fill into the - <literal>.events</literal> field of <varname>struct - pollfd</varname>.</para> - - <para><function>sd_journal_get_timeout()</function> will return a - timeout value for usage in <function>poll()</function>. This - returns a value in microseconds since the epoch of - <constant>CLOCK_MONOTONIC</constant> for timing out - <function>poll()</function> in <varname>timeout_usec</varname>. - See - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details about <constant>CLOCK_MONOTONIC</constant>. If there - is no timeout to wait for, this will fill in <constant>(uint64_t) - -1</constant> instead. Note that <function>poll()</function> takes - a relative timeout in milliseconds rather than an absolute timeout - in microseconds. To convert the absolute 'us' timeout into - relative 'ms', use code like the following:</para> - - <programlisting>uint64_t t; -int msec; -sd_journal_get_timeout(m, &t); -if (t == (uint64_t) -1) - msec = -1; -else { - struct timespec ts; - uint64_t n; - clock_getttime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; -}</programlisting> - - <para>The code above does not do any error checking for brevity's - sake. The calculated <varname>msec</varname> integer can be passed - directly as <function>poll()</function>'s timeout - parameter.</para> - - <para>After each <function>poll()</function> wake-up - <function>sd_journal_process()</function> needs to be called to - process events. 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_get_events()</function>, - <function>sd_journal_get_timeout()</function> and - <function>sd_journal_process()</function> is - <function>sd_journal_wait()</function>. It will synchronously wait - until the journal gets changed. The maximum time this call sleeps - may be controlled with the <parameter>timeout_usec</parameter> - parameter. Pass <constant>(uint64_t) -1</constant> to wait - indefinitely. Internally this call simply combines - <function>sd_journal_get_fd()</function>, - <function>sd_journal_get_events()</function>, - <function>sd_journal_get_timeout()</function>, - <function>poll()</function> and - <function>sd_journal_process()</function> into one.</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 known to be - immediately triggered. On certain file systems where file change - events from the OS are not available (such as NFS) changes need to - be polled for repeatedly, and hence are detected only with a - certain latency. This call will return a positive value if the - journal changes are detected immediately and zero when they need - to be polled for and hence might be noticed only with a certain - latency. Note that there is usually no need to invoke this function - directly as <function>sd_journal_get_timeout()</function> on these - file systems will ask for timeouts explicitly anyway.</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_get_events()</function> returns a - combination of <constant>POLLIN</constant>, - <constant>POLLOUT</constant> and suchlike 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> will generate wake-ups - immediately for all journal changes. Returns 0 if there might be a - latency involved.</para> - - <para><function>sd_journal_process()</function> and - <function>sd_journal_wait()</function> return one of - <constant>SD_JOURNAL_NOP</constant>, - <constant>SD_JOURNAL_APPEND</constant> or - <constant>SD_JOURNAL_INVALIDATE</constant> on success or a - negative errno-style error code. If - <constant>SD_JOURNAL_NOP</constant> is returned, the journal did - not change since the last invocation. If - <constant>SD_JOURNAL_APPEND</constant> is returned, new entries - have been appended to the end of the journal. If - <constant>SD_JOURNAL_INVALIDATE</constant>, 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 <constant>SD_JOURNAL_APPEND</constant>, 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_get_events()</function>, - <function>sd_journal_reliable_fd()</function>, - <function>sd_journal_process()</function> and - <function>sd_journal_wait()</function> interfaces are available as - a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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 void *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, (const char*) 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 <poll.h> -#include <systemd/sd-journal.h> - -int wait_for_changes(sd_journal *j) { - struct pollfd pollfd; - int msec; - - sd_journal_get_timeout(m, &t); - if (t == (uint64_t) -1) - msec = -1; - else { - struct timespec ts; - uint64_t n; - clock_getttime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; - } - - pollfd.fd = sd_journal_get_fd(j); - pollfd.events = sd_journal_get_events(j); - poll(&pollfd, 1, msec); - 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>, - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> |