diff options
| -rw-r--r-- | man/sd_journal_get_fd.xml | 37 |
1 files changed, 21 insertions, 16 deletions
diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml index ec1ba37f1e..c396c6a79b 100644 --- a/man/sd_journal_get_fd.xml +++ b/man/sd_journal_get_fd.xml @@ -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> |