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:
parent
642b59ff40
commit
aafcd2523b
|
@ -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>
|
||||
|
|
Loading…
Reference in a new issue