picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

man: say more explicitly what to do in the SD_JOURNAL_INVALIDATE event 

This rewords the section, explicitly distuingishing the cases of clients
that only want a continious log stream (which can simply treat
SD_JOURNAL_INVALIDATE the same way as SD_JOURNAL_APPEND) and those which
want to represent on screen the full state of the log data on disk.

This is an alternative to a part of PR #9060, but keeps an explanation
of the destinction of handling depending on the type of client.

Fixes: #8963
This commit is contained in:
Lennart Poettering 2018-05-29 16:55:46 +02:00 committed by Zbigniew Jędrzejewski-Szmek
parent 642b59ff40
commit aafcd2523b
1 changed files with 21 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
man/sd_journal_get_fd.xml
View File

@ -199,22 +199,27 @@ else {
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>
<para><function>sd_journal_process()</function> and <function>sd_journal_wait()</function> return a negative
errno-style error code, or one of <constant>SD_JOURNAL_NOP</constant>, <constant>SD_JOURNAL_APPEND</constant> or
<constant>SD_JOURNAL_INVALIDATE</constant> on success:</para>
<itemizedlist>
<listitem><para>If <constant>SD_JOURNAL_NOP</constant> is returned, the journal did not change since the last
invocation.</para></listitem>
<listitem><para>If <constant>SD_JOURNAL_APPEND</constant> is returned, new entries have been appended to the end
of the journal. In this case it is sufficient to simply continue reading at the previous end location of the
journal, to read the newly added entries.</para></listitem>
<listitem><para>If <constant>SD_JOURNAL_INVALIDATE</constant>, journal files were added to or removed from the
set of of journal files watched (e.g. due to rotation or vacuuming), and thus entries might have appeared or
disappeared at arbitrary places in the log stream, possibly before or after the previous end of the log
stream. If <constant>SD_JOURNAL_INVALIDATE</constant> is returned, live-view UIs that want to reflect on screen
the precise state of the log data on disk should probably refresh their entire display (relative to the cursor of
the log entry on the top of the screen). Programs only interested in a strictly sequencial stream of log data may
treat <constant>SD_JOURNAL_INVALIDATE</constant> the same way as <constant>SD_JOURNAL_APPEND</constant>, thus
ignoring any changes to the log view earlier than the old end of the log stream.</para></listitem>
</itemizedlist>
</refsect1>
<refsect1>