baddr: add ust_baddr and ust_baddr_statedump doc

[lttng-ust.git] / doc / man / lttng-ust.3

diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
index de4271c2dd037969a6fdfdd6a3dac2d6268b56c1..55de9fd2d88cea5de0cd1fa04f6eba46c4371efd 100644 (file)
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -33,9 +33,13 @@ script, through an example:
 .nf
 
 To create a tracepoint provider, within a build tree similar to
 .nf
 
 To create a tracepoint provider, within a build tree similar to

-examples/easy-ust installed with lttng-ust documentation, a
-sample_component_provider.h for the general layout. This manpage will
-focus on the various types that can be recorded into a trace event:
+examples/easy-ust installed with lttng-ust documentation, see
+sample_component_provider.h for the general layout. You will need to
+define TRACEPOINT_CREATE_PROBES before including your tracepoint
+provider probe in one source file of your application. See tp.c from
+easy-ust for an example of a tracepoint probe source file. This manpage
+will focus on the various types that can be recorded into a trace
+event:

 
 TRACEPOINT_EVENT(
        /*
 
 TRACEPOINT_EVENT(
        /*


@@ -342,6 +346,13 @@ Virtual process ID: process ID as seen from the point of view of the
 process namespace.
 .PP
 
 process namespace.
 .PP
 

+.PP
+.IP "ip"
+Instruction pointer: Enables recording of the exact location where a tracepoint
+was emitted. Can be used to reverse-lookup the source location that caused the
+event to be emitted.
+.PP
+

 .PP
 .IP "procname"
 Thread name, as set by exec() or prctl(). It is recommended that
 .PP
 .IP "procname"
 Thread name, as set by exec() or prctl(). It is recommended that


@@ -355,6 +366,28 @@ Pthread identifier. Can be used on architectures where pthread_t maps
 nicely to an unsigned long type.
 .PP
 
 nicely to an unsigned long type.
 .PP
 

+.SH "BASE ADDRESS STATEDUMP"
+
+.PP
+If an application that uses liblttng-ust.so becomes part of a session,
+information about its currently loaded shared objects will be traced to the
+session at session-enable time. To record this information, the following event
+needs to be enabled:
+.PP
+.IP "ust_baddr_statedump:soinfo"
+This event is used to trace a currently loaded shared object. The base address
+(where the dynamic linker has placed the shared object) is recorded in the
+baddr-field. The path to the shared object gets recorded in the sopath-field
+(as string). The file size of the loaded object (in bytes) is recorded to the
+size-field and its time of last modification (in seconds since Epoch) is
+recorded in the mtime-field.
+.PP
+If the event above is enabled, a series of ust_baddr_statedump:soinfo events is
+recorded at session-enable time, that represents the state of currently loaded
+shared objects (of the traced application). If this information gets combined
+with the lttng-ust-dl(3) instrumentation, all aspects of dynamic loading that
+are relevant for symbol and linenumber-lookup are traced by LTTng.
+.PP

 .SH "ENVIRONMENT VARIABLES"
 
 .PP
 .SH "ENVIRONMENT VARIABLES"
 
 .PP


@@ -371,19 +404,22 @@ specified in milliseconds. The value 0 means "don't wait". The value
 recommended for applications with time constraints on the process
 startup time.
 .PP
 recommended for applications with time constraints on the process
 startup time.
 .PP

+.IP "LTTNG_UST_WITHOUT_BADDR_STATEDUMP"
+Prevent liblttng-ust to perform a base-address statedump on session-enable.
+.PP

 
 .SH "SEE ALSO"
 
 .PP
 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3),
 
 .SH "SEE ALSO"
 
 .PP
 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3),

-lttng-sessiond(8)
+lttng-ust-dl(3), lttng-sessiond(8)

 .PP
 
 .SH "COMPATIBILITY"
 
 .PP
 Older lttng-ust libraries reject more recent, and incompatible, probe
 .PP
 
 .SH "COMPATIBILITY"
 
 .PP
 Older lttng-ust libraries reject more recent, and incompatible, probe

-providers. Newer lttng-ust librairies accept older probe providers, even
+providers. Newer lttng-ust libraries accept older probe providers, even

 though some newer features might not be available with those providers.
 .PP
 
 though some newer features might not be available with those providers.
 .PP