diff options
author | Luca Boccassi <bluca@debian.org> | 2023-02-15 19:58:58 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-02-15 19:58:58 +0000 |
commit | 6f97aae029c0fe44d64dc5ff202ab0125571211f (patch) | |
tree | ea5f4f3fc2803ef8b982f7eee426f490091dfe5b /man | |
parent | 8dcfecc8337a2e5d5f014e1ad272f982e9ac97cd (diff) | |
parent | f28ed2c1be77c2aab7ebf488ac095cd796294172 (diff) | |
download | systemd-6f97aae029c0fe44d64dc5ff202ab0125571211f.tar.gz |
Merge pull request #26213 from poettering/journal-rework-seqnum
journal sequence number rework
Diffstat (limited to 'man')
-rw-r--r-- | man/rules/meson.build | 1 | ||||
-rw-r--r-- | man/sd_journal_get_realtime_usec.xml | 1 | ||||
-rw-r--r-- | man/sd_journal_get_seqnum.xml | 105 | ||||
-rw-r--r-- | man/systemd.journal-fields.xml | 10 |
4 files changed, 117 insertions, 0 deletions
diff --git a/man/rules/meson.build b/man/rules/meson.build index c5b457bd7f..dcae4442ea 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 025b6a1a5a..f5096f8db8 100644 --- a/man/sd_journal_get_realtime_usec.xml +++ b/man/sd_journal_get_realtime_usec.xml @@ -103,6 +103,7 @@ <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry> diff --git a/man/sd_journal_get_seqnum.xml b/man/sd_journal_get_seqnum.xml new file mode 100644 index 0000000000..732f660763 --- /dev/null +++ b/man/sd_journal_get_seqnum.xml @@ -0,0 +1,105 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="sd_journal_get_seqnum" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_journal_get_seqnum</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_get_seqnum</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_seqnum</refname> + <refpurpose>Read sequence number from the current journal entry</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_seqnum</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>uint64_t *<parameter>ret_seqnum</parameter></paramdef> + <paramdef>sd_id128_t *<parameter>ret_seqnum_id</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_seqnum()</function> 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.</para> + + <para>When writing journal entries to disk each <command>systemd-journald</command> 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 <command>systemd-journal</command> initialization. Thus, while multiple instances of + <command>systemd-journald</command> 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 + <filename>/run/log/</filename> are flushed to <filename>/var/log/</filename> via + <filename>systemd-journald-flush.service</filename>) they will get new sequence numbers assigned.</para> + + <para>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 <varname>SplitMode=</varname> 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.</para> + + <para>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 <varname>SplitMode=</varname>.</para> + + <para>The <varname>ret_seqnum</varname> and <varname>ret_seqnum_id</varname> parameters may be specified + as <constant>NULL</constant> in which case the relevant data is not returned (but the call will otherwise + succeed).</para> + + <para>Note that these functions will not work before + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + (or related call) has been called at least + once, in order to position the read pointer at a valid entry.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_seqnum()</function> returns 0 on success or a negative errno-style error + code..</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="threads-aware.xml" xpointer="strict"/> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + </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>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index d9e3d5760c..9eaa4ce1fc 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -596,6 +596,16 @@ </para> </listitem> </varlistentry> + + <varlistentry> + <term><varname>__SEQNUM=</varname></term> + <term><varname>__SEQNUM_ID=</varname></term> + + <listitem><para>The sequence number (and associated sequence number ID) of this journal entry in the + journal file it originates from. See + <citerefentry><refentrytitle>sd_journal_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> </variablelist> </refsect1> |