document more syntax for shared library probing

* NEWS:  Add process("..").library("..")
* langref.tex:  Likewise.
* stapprobes.3stap:  Likewise.

diff --git a/NEWS b/NEWS
index 65d1b95f81e611e5d5ff46ec3f0bd03e35e3bdaa..6b9f563cfc6c2698ddcb8fff968aaceaba236e40 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,10 @@
 * What's new in version 1.5
 
+- process("...").library("...") probes are now supported.  Wildcards
+  are supported in the library-name part, to refer to any shared
+  library that is required by process-name, which matches the glob
+  pattern and the rest of the probe point.
+
 - The "--remote USER@HOST" functionality can now be specified multiple times
   to fan out on multiple targets.  If the targets have distinct kernel and
   architecture configurations, stap will automatically build the script

diff --git a/doc/langref.tex b/doc/langref.tex
index 5985b45f5ff43ad97c376780311150ba04eee898..2ff5a4024cebfc431bb63293bfa27537c6888753 100644 (file)
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -1135,6 +1135,14 @@ This command probes all threads that call into that library.  Typing
 the target command and descendants only.  You can use
 \texttt{\$\$vars} and others. You can provide the location of debug
 information to the stap command with the \texttt{-d DIRECTORY} option.
+To qualify a probe point to a location in a library required by a
+particular process try using a command with this syntax:
+\begin{vindent}
+\begin{verbatim}
+probe process("...").library("...").function("....") { ... }
+\end{verbatim}
+\end{vindent}
+The library name may use wildcards.
 
 \subsubsection{Instruction probes}
 \label{sec:insnprobes}

diff --git a/stapprobes.3stap b/stapprobes.3stap
index 5e7b73e2d37bcb7951727fc88090d53b31d6079e..1eb657e58e8ab5dcdc2e5317a16897f41056dbde 100644 (file)
--- a/stapprobes.3stap
+++ b/stapprobes.3stap
@@ -332,6 +332,10 @@ process("PATH").function("NAME")
 .br
 process("PATH").statement("*@FILE.c:123")
 .br
+process("PATH").library("PATH").function("NAME")
+.br
+process("PATH").library("PATH").statement("*@FILE.c:123")
+.br
 process("PATH").function("*").return
 .br
 process("PATH").function("myfun").label("foo")
@@ -642,6 +646,8 @@ and expose similar contextual $variables.
 .SAMPLE
 process("PATH").function("NAME")
 process("PATH").statement("*@FILE.c:123")
+process("PATH").library("PATH").function("NAME")
+process("PATH").library("PATH").statement("*@FILE.c:123")
 process("PATH").function("*").return
 process("PATH").function("myfun").label("foo")
 .ESAMPLE
@@ -654,8 +660,11 @@ to the working directory if they contain a "/" character, otherwise in
 .BR $PATH .
 If PATH names refer to scripts, the actual interpreters (specified in the
 script in the first line after the #! characters) are probed.
-PATH may also refer to shared libraries, in which case all proceses that
-map it at runtime would be selected for probing.
+If PATH is a process component parameter referring to shared libraries
+then all processes that map it at runtime would be selected for
+probing.  If PATH is a library component parameter referring to shared
+libraries then the process specified by the process component would be
+selected.
 If the PATH string contains wildcards as in the MPATTERN case, then
 standard globbing is performed to find all matching paths.  In this
 case, the