lttng-enable-event.1.txt: uprobe: update style and content

[lttng-tools.git] / doc / man / lttng-enable-event.1.txt

diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt
index 3e137a9dcd8d8db2e6ebb3917117da621d43e787..538a3b96b699ee00be5dba33f23cdd764b301e99 100644 (file)
--- a/doc/man/lttng-enable-event.1.txt
+++ b/doc/man/lttng-enable-event.1.txt
@@ -410,8 +410,10 @@ Dynamic user space probes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 With the option:--userspace-probe option, you can instrument function
 entries of any user space binary (application or library) using either
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 With the option:--userspace-probe option, you can instrument function
 entries of any user space binary (application or library) using either

-an available symbol name or a SystemTap SDT probe's provider and probe
-names.
+an available symbol name or a SystemTap Statically Defined Tracepoints
+(SDT, a DTrace-style marker) probe's provider and probe names. As of
+this version, only SDT probes that are :not: surrounded by a reference
+counter (semaphore).

 
 The option:--userspace-probe option must be specified with the
 option:--kernel option because it uses Linux's uprobe feature to
 
 The option:--userspace-probe option must be specified with the
 option:--kernel option because it uses Linux's uprobe feature to


@@ -420,12 +422,73 @@ dynamically instrument a user space application or library.
 As of this version, dynamic probe events do not record any payload
 field.
 
 As of this version, dynamic probe events do not record any payload
 field.
 

-The two available option:--userspace-probe option's argument formats
-are:

 
 

-option:--userspace-probe=`[elf:]PATH:SYMBOL`::
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-j, option:--jul::
+    Create or enable event rules in the `java.util.logging`
+    (JUL) domain.
+
+option:-k, option:--kernel::
+    Create or enable event rules in the Linux kernel domain.
+
+option:-l, option:--log4j::
+    Create or enable event rules in the Apache log4j domain.
+
+option:-p, option:--python::
+    Create or enable event rules in the Python domain.
+
+option:-u, option:--userspace::
+    Create or enable event rules in the user space domain.
+
+
+Target
+~~~~~~
+option:-c 'CHANNEL', option:--channel='CHANNEL'::
+    Create or enable event rules in the channel named 'CHANNEL' instead
+    of the default channel name `channel0`.
+
+option:-s 'SESSION', option:--session='SESSION'::
+    Create or enable event rules in the tracing session named 'SESSION'
+    instead of the current tracing session.
+
+
+Event source type
+~~~~~~~~~~~~~~~~~
+One of:
+
+option:--function='SOURCE'::
+    Dynamic kernel return probe (kretprobe). Only available with the
+    option:--kernel domain option. 'SOURCE' is one of:
++
+* Function address (`0x` prefix supported)
+* Function symbol name
+* Function symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
+
+option:--probe='SOURCE'::
+    Dynamic kernel probe (kprobe). Only available with the
+    option:--kernel domain option. 'SOURCE' is one of:
++
+* Address (`0x` prefix supported)
+* Symbol nane
+* Symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
+
+option:--userspace-probe='SOURCE'::
+    Dynamic user space probe (uprobe). Only available with the
+    option:--kernel domain option. See the
+    <<userspace-probe,Dynamic user space probes>> section.
++
+'SOURCE' is one of:
++
+--
+\[++elf:++]__PATH__++:++__SYMBOL__::

     Dynamically instrument an available symbol within a user space
     Dynamically instrument an available symbol within a user space

-    executable.
+    application or library.

 +
 --
 'PATH'::
 +
 --
 'PATH'::


@@ -435,7 +498,7 @@ This can be:
 +
 * An absolute path.
 * A relative path.
 +
 * An absolute path.
 * A relative path.

-* An executable's name as found in the directories listed in the
+* An application's name as found in the directories listed in the

   `PATH` environment variable.
 
 'SYMBOL'::
   `PATH` environment variable.
 
 'SYMBOL'::


@@ -455,8 +518,9 @@ Examples:
 * `--userspace-probe=./myapp:createUser`
 * `--userspace-probe=httpd:ap_run_open_htaccess`
 
 * `--userspace-probe=./myapp:createUser`
 * `--userspace-probe=httpd:ap_run_open_htaccess`
 

-option:--userspace-probe=`sdt:PATH:PROVIDER:NAME`::
-    Dynamically instrument an SDT probe within a user space executable.
+++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
+    Dynamically instrument an SDT probe within a user space application
+    or library.

 +
 --
 'PATH'::
 +
 --
 'PATH'::


@@ -466,10 +530,10 @@ This can be:
 +
 * An absolute path.
 * A relative path.
 +
 * An absolute path.
 * A relative path.

-* An executable's name as found in the directories listed in the
+* An application's name as found in the directories listed in the

   `PATH` environment variable.
 
   `PATH` environment variable.
 

-__PROVIDER__:__NAME__::
+__PROVIDER__++:++__NAME__::

     SDT provider and probe names.
 +
 For example, with the following SDT probe:
     SDT provider and probe names.
 +
 For example, with the following SDT probe:


@@ -486,69 +550,7 @@ The provider/probe name pair is `server:accept_request`.
 Example:
 +
 * `--userspace-probe=sdt:./build/server:server:accept_request`
 Example:
 +
 * `--userspace-probe=sdt:./build/server:server:accept_request`

-
-
-include::common-cmd-options-head.txt[]
-
-
-Domain
-~~~~~~
-One of:
-
-option:-j, option:--jul::
-    Create or enable event rules in the `java.util.logging`
-    (JUL) domain.
-
-option:-k, option:--kernel::
-    Create or enable event rules in the Linux kernel domain.
-
-option:-l, option:--log4j::
-    Create or enable event rules in the Apache log4j domain.
-
-option:-p, option:--python::
-    Create or enable event rules in the Python domain.
-
-option:-u, option:--userspace::
-    Create or enable event rules in the user space domain.
-
-
-Target
-~~~~~~
-option:-c 'CHANNEL', option:--channel='CHANNEL'::
-    Create or enable event rules in the channel named 'CHANNEL' instead
-    of the default channel name `channel0`.
-
-option:-s 'SESSION', option:--session='SESSION'::
-    Create or enable event rules in the tracing session named 'SESSION'
-    instead of the current tracing session.
-
-
-Event source type
-~~~~~~~~~~~~~~~~~
-One of:
-
-option:--function='SOURCE'::
-    Linux kernel kretprobe. Only available with the option:--kernel
-    domain option. 'SOURCE' is one of:
-+
-* Function address (`0x` prefix supported)
-* Function symbol
-* Function symbol and offset (`SYMBOL+OFFSET` format)
-
-option:--probe='SOURCE'::
-    Linux kernel kprobe. Only available with the option:--kernel
-    domain option. 'SOURCE' is one of:
-+
-* Address (`0x` prefix supported)
-* Symbol
-* Symbol and offset (`SYMBOL+OFFSET` format)
-
-option:--userspace-probe='SOURCE'::
-    Linux kernel uprobe. Only available with the option:--kernel
-    domain option.
-+
-See the <<userspace-probe,Dynamic user space probes>> section for more
-information about the option's argument 'SOURCE'.
+--

 
 option:--syscall::
     Linux kernel system call. Only available with the option:--kernel
 
 option:--syscall::
     Linux kernel system call. Only available with the option:--kernel