Merge branch 'master' of ssh://sources.redhat.com/git/systemtap

5 files changed, 156 insertions, 39 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
index d8a93302..23d43673 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -6,3 +6,5 @@
 *.out
 *.pdf
 *.toc
+*.dvi
+_region_.*
diff --git a/doc/Makefile.in b/doc/Makefile.in
index 996700ec..949faec9 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -132,6 +132,7 @@ PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
 PACKAGE_NAME = @PACKAGE_NAME@
 PACKAGE_STRING = @PACKAGE_STRING@
 PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
 PACKAGE_VERSION = @PACKAGE_VERSION@
 PATH_SEPARATOR = @PATH_SEPARATOR@
 PIECFLAGS = @PIECFLAGS@
diff --git a/doc/SystemTap_Tapset_Reference/Makefile.am b/doc/SystemTap_Tapset_Reference/Makefile.am
index 30c4ffef..4adba34e 100644
--- a/doc/SystemTap_Tapset_Reference/Makefile.am
+++ b/doc/SystemTap_Tapset_Reference/Makefile.am
@@ -57,3 +57,7 @@ endif
 	$(MKDIR_P)  $(HTML_INSTALL_DIR)
 	$(INSTALL_DATA) tapsets/* $(HTML_INSTALL_DIR)
 endif
+
+CLEANFILES=tapsets.xml stamp-* $(PDFDOCS)
+clean-local:
+	rm -rf man3 tapsets
diff --git a/doc/SystemTap_Tapset_Reference/Makefile.in b/doc/SystemTap_Tapset_Reference/Makefile.in
index 2368ccad..018b8333 100644
--- a/doc/SystemTap_Tapset_Reference/Makefile.in
+++ b/doc/SystemTap_Tapset_Reference/Makefile.in
@@ -108,6 +108,7 @@ PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
 PACKAGE_NAME = @PACKAGE_NAME@
 PACKAGE_STRING = @PACKAGE_STRING@
 PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
 PACKAGE_VERSION = @PACKAGE_VERSION@
 PATH_SEPARATOR = @PATH_SEPARATOR@
 PIECFLAGS = @PIECFLAGS@
@@ -186,6 +187,7 @@ HTML_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap/tapsets
 SRCTREE = $(abs_top_srcdir)/
 DOCPROC = $(abs_builddir)/docproc
 @BUILD_PDFREFDOCS_TRUE@PDFDOCS = tapsets.pdf
+CLEANFILES = tapsets.xml stamp-* $(PDFDOCS)
 all: all-am
 
 .SUFFIXES:
@@ -352,6 +354,7 @@ install-strip:
 mostlyclean-generic:
 
 clean-generic:
+	-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
 
 distclean-generic:
 	-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
@@ -363,7 +366,8 @@ maintainer-clean-generic:
 @BUILD_REFDOCS_FALSE@install-data-hook:
 clean: clean-am
 
-clean-am: clean-generic clean-noinstPROGRAMS mostlyclean-am
+clean-am: clean-generic clean-local clean-noinstPROGRAMS \
+	mostlyclean-am
 
 distclean: distclean-am
 	-rm -rf ./$(DEPDIR)
@@ -434,17 +438,17 @@ uninstall-am:
 .MAKE: install-am install-data-am install-strip
 
 .PHONY: CTAGS GTAGS all all-am check check-am clean clean-generic \
-	clean-noinstPROGRAMS ctags distclean distclean-compile \
-	distclean-generic distclean-tags distdir dvi dvi-am html \
-	html-am info info-am install install-am install-data \
-	install-data-am install-data-hook install-dvi install-dvi-am \
-	install-exec install-exec-am install-html install-html-am \
-	install-info install-info-am install-man install-pdf \
-	install-pdf-am install-ps install-ps-am install-strip \
-	installcheck installcheck-am installdirs maintainer-clean \
-	maintainer-clean-generic mostlyclean mostlyclean-compile \
-	mostlyclean-generic pdf pdf-am ps ps-am tags uninstall \
-	uninstall-am
+	clean-local clean-noinstPROGRAMS ctags distclean \
+	distclean-compile distclean-generic distclean-tags distdir dvi \
+	dvi-am html html-am info info-am install install-am \
+	install-data install-data-am install-data-hook install-dvi \
+	install-dvi-am install-exec install-exec-am install-html \
+	install-html-am install-info install-info-am install-man \
+	install-pdf install-pdf-am install-ps install-ps-am \
+	install-strip installcheck installcheck-am installdirs \
+	maintainer-clean maintainer-clean-generic mostlyclean \
+	mostlyclean-compile mostlyclean-generic pdf pdf-am ps ps-am \
+	tags uninstall uninstall-am
 
 
 @BUILD_REFDOCS_TRUE@all: $(PDFDOCS) stamp-htmldocs stamp-mandocs
@@ -478,6 +482,8 @@ uninstall-am:
 @BUILD_REFDOCS_TRUE@	$(INSTALL_DATA) man3/* $(MAN_INSTALL_DIR)
 @BUILD_REFDOCS_TRUE@	$(MKDIR_P)  $(HTML_INSTALL_DIR)
 @BUILD_REFDOCS_TRUE@	$(INSTALL_DATA) tapsets/* $(HTML_INSTALL_DIR)
+clean-local:
+	rm -rf man3 tapsets
 
 # Tell versions [3.59,3.63) of GNU make to not export all variables.
 # Otherwise a system limit (for SysV at least) may be exceeded.
diff --git a/doc/langref.tex b/doc/langref.tex
index 3d08234d..aa583c2e 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -911,26 +911,46 @@ function, use \textbf{.statement} probes. Do not use wildcards in
 to not register. Also, run statement probes in guru mode only.
 
 
-\begin{comment}
 \subsection{Marker probes}
+\index{marker probes}
+This family of probe points connects to static probe markers inserted
+into the kernel or a module. These markers are special macro calls in
+the kernel that make probing faster and more reliable than with
+DWARF-based probes.  DWARF debugging information is not required to
+use probe markers.
+
+Marker probe points begin with a \texttt{kernel} prefix which
+identifies the source of the symbol table used for finding
+markers. The suffix names the marker itself:
+\texttt{mark.("MARK")}. The marker name string, which can contain
+wildcard characters, is matched against the names given to the marker
+macros when the kernel or module is compiled.  Optionally, you can
+specify \texttt{format("FORMAT")}.  Specifying the marker format
+string allows differentiation between two markers with the same name
+but different marker format strings.
+
+The handler associated with a marker probe reads any optional
+parameters specified at the macro call site named \texttt{\$arg1}
+through \texttt{\$argNN}, where \texttt{NN} is the number of
+parameters supplied by the macro. Number and string parameters are
+passed in a type-safe manner.
+
+The marker format string associated with a marker is available in
+\texttt{\$format}. The marker name string is available in
+\texttt{\$name}.
+
+Here are the marker probe constructs:
+\begin{vindent}
+\begin{verbatim}
+kernel.mark("MARK")
+kernel.mark("MARK").format("FORMAT")
+\end{verbatim}
+\end{vindent}
+
+For more information about marker probes, see
+\url{http://sourceware.org/systemtap/wiki/UsingMarkers}.
+
 
-This family of probe points connects to static probe markers inserted into
-the kernel or a module. These markers are special macro calls in the kernel
-that make probing faster and more reliable than with DWARF-based probes.
-DWARF debugging information is not required to use probe markers.
-
-Marker probe points begin with a kernel or module(\char`\"{}\emph{name}\char`\"{})
-prefix, the same as DWARF probes. This prefix identifies the source of the
-symbol table used for finding markers. The suffix names the marker itself:
-mark(\char`\"{}\emph{name}\char`\"{}). The marker name string, which may
-contain wildcard characters, is matched against the names given to the marker
-macros when the kernel or module was compiled.
-
-The handler associated with a marker probe reads any optional parameters
-specified at the macro call site named \$arg1 through \$argNN, where NN is
-the number of parameters supplied by the macro. Number and string parameters
-are passed in a type-safe manner.
-\end{comment}
 
 \subsection{Timer probes}
 \index{timer probes}
@@ -1031,14 +1051,33 @@ of an \texttt{exit} function call, or an interruption from the user. In the
 case of an shutdown triggered by error, \texttt{end} probes are not run.
 
 
-\subsubsection{begin and end probe sequence}
-\index{sequence}
-\texttt{begin} and \texttt{end} probes are specified with an optional sequence
-number that controls the order in which they are run. If no sequence number
-is provided, the sequence number defaults to zero and probes are run in the
-order that they occur in the script file. Sequence numbers may be either
-positive or negative, and are especially useful for tapset writers who want
-to do initialization in a \texttt{begin} probe. The following are examples.
+\subsubsection{error}
+\index{error}
+The \emph{error} probe point is similar to the end
+probe, except the probe handler runs when the session ends if an error
+occurred.  In this case, an \texttt{end} probe is skipped, but each
+\texttt{error} probe is still attempted.  You can use an
+\texttt{error} probe to clean up or perform a final action on script
+termination.
+
+Here is a simple example:
+\begin{vindent}
+\begin{verbatim}
+probe error { println ("Oops, errors occurred. Here's a report anyway.")
+              foreach (coin in mint) { println (coin) } }
+\end{verbatim}
+\end{vindent}
+
+
+\subsubsection{begin, end, and error probe sequence}
+\index{probe sequence}
+\texttt{begin}, \texttt{end}, and \texttt{error} probes can be
+specified with an optional sequence number that controls the order in
+which they are run. If no sequence number is provided, the sequence
+number defaults to zero and probes are run in the order that they
+occur in the script file. Sequence numbers may be either positive or
+negative, and are especially useful for tapset writers who want to do
+initialization in a \texttt{begin} probe. The following are examples.
 
 \begin{vindent}
 \begin{verbatim}
@@ -1088,9 +1127,74 @@ read\_counter is a function passed to the handle for a perfmon probe. It
 returns the current count for the event.
 \end{comment}
 
-\section{Language elements\label{sec:Language-Elements}}
+\subsection{Pointer typecasting}
+\index{Pointer typecasting}
+
+\emph{Typecasting} is supported using the \texttt{@cast()} operator. A
+script can define a pointer type for a \emph{long} value, then access
+type members using the same syntax as with \texttt{\$target}
+variables. After a pointer is saved into a script integer variable,
+the translator loses the necessary type information to access members
+from that pointer.  The \texttt{@cast()} operator tells the translator
+how to read a pointer.
+
+The following statement interprets \texttt{p} as a pointer to a struct
+or union named \texttt{type\_name} and dereferences the
+\texttt{member} value:
+\begin{vindent}
+\begin{verbatim}
+@cast(p, "type_name"[, "module"])->member
+\end{verbatim}
+\end{vindent}
+
+The optional \texttt{module} parameter tells the translator where to
+look for information about that type. You can specify multiple modules
+as a list with colon (\texttt{:}) separators. If you do not specify
+the module parameter, the translator defaults to either the probe
+module for dwarf probes or to \textit{kernel} for functions and all
+other probe types.
 
+The following statement retrieves the parent PID from a kernel
+task\_struct:
+\begin{vindent}
+\begin{verbatim}
+@cast(pointer, "task_struct", "kernel")->parent->tgid
+\end{verbatim}
+\end{vindent}
 
+The translator can create its own module with type information from a
+header surrounded by angle brackets (\texttt{< >}) if normal debugging
+information is not available.  For kernel headers, prefix it with
+\texttt{kernel} to use the appropriate build system.  All other
+headers are built with default GCC parameters into a user module. The
+following statements are examples.
+\begin{vindent}
+\begin{verbatim}
+@cast(tv, "timeval", "<sys/time.h>")->tv_sec
+@cast(task, "task_struct", "kernel<linux/sched.h>")->tgid
+\end{verbatim}
+\end{vindent}
+
+In guru mode, the translator allows scripts to assign new values to
+members of typecasted pointers.
+
+Typecasting is also useful in the case of \texttt{void*} members whose
+type might be determinable at run time.
+\begin{vindent}
+\begin{verbatim}
+probe foo {
+   if ($var->type == 1) {
+      value = @cast($var->data, "type1")->bar
+   } else {
+      value = @cast($var->data, "type2")->baz
+   }
+   print(value)
+}
+\end{verbatim}
+\end{vindent}
+
+
+\section{Language elements\label{sec:Language-Elements}}
 \subsection{Identifiers}
 \index{identifiers}
 \emph{Identifiers} are used to name variables and functions. They are an