From: Lennart Poettering Date: Thu, 26 Jan 2023 10:04:44 +0000 (+0100) Subject: man: document the new sd_journal_get_seqnum() call X-Git-Tag: v254-rc1~1277^2~2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=37a40afcfe2b446c84d21e3b769b0d40993b0b81;p=thirdparty%2Fsystemd.git man: document the new sd_journal_get_seqnum() call --- diff --git a/man/rules/meson.build b/man/rules/meson.build index c5b457bd7f9..dcae4442eaa 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -720,6 +720,7 @@ manpages = [ 'sd_journal_wait'], ''], ['sd_journal_get_realtime_usec', '3', ['sd_journal_get_monotonic_usec'], ''], + ['sd_journal_get_seqnum', '3', [], ''], ['sd_journal_get_usage', '3', [], ''], ['sd_journal_has_runtime_files', '3', ['sd_journal_has_persistent_files'], ''], ['sd_journal_next', diff --git a/man/sd_journal_get_realtime_usec.xml b/man/sd_journal_get_realtime_usec.xml index 025b6a1a5aa..f5096f8db8f 100644 --- a/man/sd_journal_get_realtime_usec.xml +++ b/man/sd_journal_get_realtime_usec.xml @@ -103,6 +103,7 @@ sd_journal_open3, sd_journal_next3, sd_journal_get_data3, + sd_journal_get_seqnum3, sd_id128_get_boot3, clock_gettime2, sd_journal_get_cutoff_realtime_usec3 diff --git a/man/sd_journal_get_seqnum.xml b/man/sd_journal_get_seqnum.xml new file mode 100644 index 00000000000..732f6607633 --- /dev/null +++ b/man/sd_journal_get_seqnum.xml @@ -0,0 +1,105 @@ + + + + + + + + sd_journal_get_seqnum + systemd + + + + sd_journal_get_seqnum + 3 + + + + sd_journal_get_seqnum + Read sequence number from the current journal entry + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_get_seqnum + sd_journal *j + uint64_t *ret_seqnum + sd_id128_t *ret_seqnum_id + + + + + + Description + + sd_journal_get_seqnum() returns the sequence number of the current journal + entry. It takes three arguments: the journal context object, a pointer to a 64-bit unsigned integer to + store the sequence number in, and a buffer to return the 128bit sequence number ID in. + + When writing journal entries to disk each systemd-journald instance will number + them sequentially, starting from 1 for the first entry written after subsystem intialization. Each such + series of sequence numbers is associated with a 128bit sequence number ID which is initialized randomly, + once at systemd-journal initialization. Thus, while multiple instances of + systemd-journald will assign the same sequence numbers to their written journal + entries, they will have a distinct sequence number IDs. The sequence number is assigned at the moment of + writing the entry to disk. If log entries are rewritten (for example because the volatile logs from + /run/log/ are flushed to /var/log/ via + systemd-journald-flush.service) they will get new sequence numbers assigned. + + Sequence numbers may be used to order entries (entries associated with the same sequence number ID + and lower sequence numbers should be ordered chronologically before those with higher sequence numbers), + and to detect lost entries. Note that journal service instances typically write to multiple journal files + in parallel (for example because SplitMode= is used), in which case each journal file + will only contain a subset of the sequence numbers. To recover the full stream of journal entries the + files must be combined ("interleaved"), a process that primarily relies on the sequence numbers. When + journal files are rotated (due to size or time limits), the series of sequence numbers is continued in + the replacement files. All journal files generated from the same journal instance will carry the same + sequence number ID. + + As the sequence numbers are assigned at the moment of writing the journal entries to disk they do + not exist if storage is disabled via SplitMode=. + + The ret_seqnum and ret_seqnum_id parameters may be specified + as NULL in which case the relevant data is not returned (but the call will otherwise + succeed). + + Note that these functions will not work before + sd_journal_next3 + (or related call) has been called at least + once, in order to position the read pointer at a valid entry. + + + + Return Value + + sd_journal_get_seqnum() returns 0 on success or a negative errno-style error + code.. + + + + Notes + + + + + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_next3, + sd_journal_get_data3, + sd_journal_get_monotonic_usec3 + + + +