X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3.txt;h=21e0f7364e48d9150fb3c6adfb8d68b89634ed87;hb=5490b085142c3c6ba72e120378d1ac765bd96b02;hp=ff0e14f75ca6b86002c979ecbb2d86c228f884fd;hpb=468589da1a60b5288b5ffa75b0f21a91dcb5bc8b;p=lttng-ust.git diff --git a/doc/man/lttng-ust.3.txt b/doc/man/lttng-ust.3.txt index ff0e14f7..21e0f736 100644 --- a/doc/man/lttng-ust.3.txt +++ b/doc/man/lttng-ust.3.txt @@ -571,9 +571,9 @@ source: Create the tracepoint provider object file: [role="term"] --------------- -cc -c -I. tp.c --------------- +---- +$ cc -c -I. tp.c +---- NOTE: Although an application instrumented with LTTng-UST tracepoints can be compiled with a C++ compiler, tracepoint probes should be @@ -584,9 +584,9 @@ possibly with other object files of your application or with other tracepoint provider object files, as a static library: [role="term"] ---------------- -ar rc tp.a tp.o ---------------- +---- +$ ar rc tp.a tp.o +---- Using a static library does have the advantage of centralising the tracepoint providers objects so they can be shared between multiple @@ -601,9 +601,9 @@ library containing it) and with `liblttng-ust` and `libdl` (`libc` on a BSD system): [role="term"] -------------------------------------- -cc -o app tp.o app.o -llttng-ust -ldl -------------------------------------- +---- +$ cc -o app tp.o app.o -llttng-ust -ldl +---- [[build-dynamic]] @@ -644,16 +644,16 @@ built like it is using the static linking method, but with the nloption:-fpic option: [role="term"] --------------------- -cc -c -fpic -I. tp.c --------------------- +---- +$ cc -c -fpic -I. tp.c +---- It is then linked as a shared library like this: [role="term"] -------------------------------------------------------- -cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust -------------------------------------------------------- +---- +$ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust +---- This tracepoint provider shared object isn't linked with the user application: it must be loaded manually. This is why the application is @@ -661,9 +661,9 @@ built with no mention of this tracepoint provider, but still needs libdl: [role="term"] --------------------------------- -cc -o app app.o tp-define.o -ldl --------------------------------- +---- +$ cc -o app app.o tp-define.o -ldl +---- There are two ways to dynamically load the tracepoint provider shared object: @@ -839,44 +839,44 @@ You can compile the source files and link them together statically like this: [role="term"] -------------------------------------- -cc -c -I. tp.c -cc -c app.c -cc -o app tp.o app.o -llttng-ust -ldl -------------------------------------- +---- +$ cc -c -I. tp.c +$ cc -c app.c +$ cc -o app tp.o app.o -llttng-ust -ldl +---- Using the man:lttng(1) tool, create an LTTng tracing session, enable all the events of this tracepoint provider, and start tracing: [role="term"] ----------------------------------------------- -lttng create my-session -lttng enable-event --userspace 'my_provider:*' -lttng start ----------------------------------------------- +---- +$ lttng create my-session +$ lttng enable-event --userspace 'my_provider:*' +$ lttng start +---- You may also enable specific events: [role="term"] ----------------------------------------------------------- -lttng enable-event --userspace my_provider:big_event -lttng enable-event --userspace my_provider:event_instance2 ----------------------------------------------------------- +---- +$ lttng enable-event --userspace my_provider:big_event +$ lttng enable-event --userspace my_provider:event_instance2 +---- Run the application: [role="term"] --------------------- -./app some arguments --------------------- +---- +$ ./app some arguments +---- Stop the current tracing session and inspect the recorded events: [role="term"] ----------- -lttng stop -lttng view ----------- +---- +$ lttng stop +$ lttng view +---- Tracepoint provider header file @@ -1088,23 +1088,24 @@ int main(int argc, char* argv[]) ENVIRONMENT VARIABLES --------------------- -`LTTNG_UST_DEBUG`:: - Activate `liblttng-ust` debug and error output. - -`LTTNG_UST_REGISTER_TIMEOUT`:: - Specify how long the applications should wait for the - _registration done_ session daemon command before proceeding to - execute the main program (milliseconds). -+ -The value 0 means _do not wait_. The value -1 means _wait forever_. -Setting this environment variable to 0 is recommended for applications -with time constraints on the process startup time. +`LTTNG_HOME`:: + Alternative user's home directory. This variable is useful when the + user running the instrumented application has a non-writable home + directory. + -Default: {lttng_ust_register_timeout}. +Unix sockets used for the communication between `liblttng-ust` and the +LTTng session and consumer daemons (part of the LTTng-tools project) +are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if +`$LTTNG_HOME` is not set). -`LTTNG_UST_WITHOUT_BADDR_STATEDUMP`:: - Prevent `liblttng-ust` from performing a base address state dump - (see the <> section above). +`LTTNG_UST_CLOCK_PLUGIN`:: + Path to the shared object which acts as the clock override plugin. + An example of such a plugin can be found in the LTTng-UST + documentation under + https://github.com/lttng/lttng-ust/tree/master/doc/examples/clock-override[`examples/clock-override`]. + +`LTTNG_UST_DEBUG`:: + If set, enable `liblttng-ust`'s debug and error output. `LTTNG_UST_GETCPU_PLUGIN`:: Path to the shared object which acts as the `getcpu()` override @@ -1112,11 +1113,19 @@ Default: {lttng_ust_register_timeout}. documentation under https://github.com/lttng/lttng-ust/tree/master/doc/examples/getcpu-override[`examples/getcpu-override`]. -`LTTNG_UST_CLOCK_PLUGIN`:: - Path to the shared object which acts as the clock override plugin. - An example of such a plugin can be found in the LTTng-UST - documentation under - https://github.com/lttng/lttng-ust/tree/master/doc/examples/clock-override[`examples/clock-override`]. +`LTTNG_UST_REGISTER_TIMEOUT`:: + Waiting time for the _registration done_ session daemon command + before proceeding to execute the main program (milliseconds). ++ +The value `0` means _do not wait_. The value `-1` means _wait forever_. +Setting this environment variable to `0` is recommended for applications +with time constraints on the process startup time. ++ +Default: {lttng_ust_register_timeout}. + +`LTTNG_UST_WITHOUT_BADDR_STATEDUMP`:: + If set, prevents `liblttng-ust` from performing a base address state + dump (see the <> section above). include::common-footer.txt[]