Update manual pages for 2.0.0-rc1

[babeltrace.git] / doc / man / babeltrace2-source.text.dmesg.7.txt

diff --git a/doc/man/babeltrace2-source.text.dmesg.7.txt b/doc/man/babeltrace2-source.text.dmesg.7.txt
index f24d4eece51ad2351f13a150fc2aedfa47528a86..9079fe4b4331890a85c016019187e4a3d84e5e5a 100644 (file)
--- a/doc/man/babeltrace2-source.text.dmesg.7.txt
+++ b/doc/man/babeltrace2-source.text.dmesg.7.txt
@@ -1,80 +1,105 @@
-babeltrace2-source.text.dmesg(7)
-===============================
+= babeltrace2-source.text.dmesg(7)

 :manpagetype: component class
 :manpagetype: component class

-:revdate: 5 October 2017
+:revdate: 14 September 2019

 
 
 
 

-NAME
-----
-babeltrace2-source.text.dmesg - Babeltrace's Linux kernel ring buffer
+== NAME
+
+babeltrace2-source.text.dmesg - Babeltrace 2's Linux kernel ring buffer

 source component class
 
 
 source component class
 
 

-DESCRIPTION
------------
-The Babeltrace compcls:source.text.dmesg component class, provided by
-the man:babeltrace2-plugin-text(7) plugin, once instantiated, reads the
+== DESCRIPTION
+
+A Babeltrace~2 compcls:source.text.dmesg message iterator reads the

 lines of a Linux kernel ring buffer, as printed by the man:dmesg(1)
 lines of a Linux kernel ring buffer, as printed by the man:dmesg(1)

-tool, and emits corresponding event notifications on its output port.
+tool, and emits corresponding event messages.
+
+----
+Linux kernel ring buffer
+lines (file or standard input)
+  |
+  |   +----------------+
+  |   | src.text.dmesg |
+  '-->|                |
+      |            out @--> Messages (single stream)
+      +----------------+
+----

 
 

-The events created by a compcls:source.text.dmesg component are named
-`string` and contain a single payload string field named `str` which
-contains the corresponding ring buffer line.
+include::common-see-babeltrace2-intro.txt[]

 
 

-By default, a compcls:source.text.dmesg component reads the lines of the
-standard input stream. You can make the component read the lines of a
-text file instead with the param:path parameter.
+A compcls:source.text.dmesg message iterator names the events it creates
+`string`. Each event contain a single payload string field named `str`
+which contains the corresponding ring buffer line.

 
 

-By default, the component tries to extract the timestamps of the kernel
-ring buffer lines and use them as the created events's timestamps. A
-typical man:dmesg(1) line looks like this:
+By default, a compcls:source.text.dmesg message iterator reads the lines
+of the standard input stream. You can make the message iterator read the
+lines of a text file instead with the param:path parameter.
+
+By default, the message iterator tries to extract the timestamps of the
+kernel ring buffer lines and use them as the created events's
+timestamps. A typical man:dmesg(1) line looks like this:

 
 ----
 [87166.510937] PM: Finishing wakeup.
 ----
 
 
 ----
 [87166.510937] PM: Finishing wakeup.
 ----
 

-In the last example, the `[87166.510937]` part is the timestamp to
-extract. You can make the component not extract timestamps from lines
-with the param:no-extract-timestamp parameter.
+The `[87166.510937]` part is the timestamp to extract. When this
+information is available, the component creates a clock class which does
+:not: have the Unix epoch as its origin.
+
+You can make the message iterator not extract timestamps from lines with
+the param:no-extract-timestamp parameter.

 
 

+[NOTE]
+====
+It is possible that the output of man:dmesg(1) contains unsorted lines,
+that is, their timestamps go back in time. You can see this with the
+nlopt:--show-delta option of man:dmesg(1): some time differences can be
+negative.

 
 

-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional.
+This is due to a https://lwn.net/Articles/780556/[2019 change] to the
+kernel's ring buffer API.

 
 

-param:no-extract-timestamp=`yes` (boolean)::
+As of this version, a compcls:source.text.dmesg message iterator
+requires that the input kernel ring buffer lines be sorted by timestamp
+(when they have timestamps), failing otherwise.
+====
+
+
+== INITIALIZATION PARAMETERS
+
+param:no-extract-timestamp=`yes` vtype:[optional boolean]::

     Do :not: extract timestamps from the kernel ring buffer lines: set
     the created event's payload's `str` field to the whole line,
     including any timestamp prefix.
 
     Do :not: extract timestamps from the kernel ring buffer lines: set
     the created event's payload's `str` field to the whole line,
     including any timestamp prefix.
 

-param:path='PATH' (string)::
+param:path='PATH' vtype:[optional string]::

     Read the kernel ring buffer lines from the file 'PATH' instead of
     the standard input stream.
 
 
     Read the kernel ring buffer lines from the file 'PATH' instead of
     the standard input stream.
 
 

-PORTS
------
-Output
-~~~~~~
-`out`::
-    Single output port to which the component sends the created
-    notifications.
+== PORTS

 
 

+----
++----------------+
+| src.text.dmesg |
+|                |
+|            out @
++----------------+
+----

 
 

-QUERY OBJECTS
--------------
-This component class has no objects to query.

 
 

+=== Output

 
 

-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
+`out`::
+    Single output port.

 
 
 include::common-footer.txt[]
 
 
 
 
 include::common-footer.txt[]
 
 

-SEE ALSO
---------
+== SEE ALSO
+

 man:babeltrace2-plugin-text(7),
 man:babeltrace2-intro(7)
 man:babeltrace2-plugin-text(7),
 man:babeltrace2-intro(7)