From 206184022e7902933575abf693ff5b9b4a540ab2 Mon Sep 17 00:00:00 2001
From: Serguei Makarov <smakarov@redhat.com>
Date: Mon, 10 Sep 2012 12:44:49 -0400
Subject: [PATCH] langref.tex: document various embedded-C pragmas

---
 doc/langref.tex | 31 +++++++++++++++++++++++++++++++
 stap.1          |  6 ++++--
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/doc/langref.tex b/doc/langref.tex
index 38229cc06..7f0962dc9 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -734,6 +734,37 @@ embedded-C. Note that all SystemTap functions and probes run with interrupts
 disabled, thus you cannot call functions that might sleep within the embedded
 C.
 
+\subsection{Embedded C pragma comments}
+
+Embedded C blocks may contain various markers to assert optimization
+and safety properties.
+
+\begin{itemize}
+\item \verb+/* pure */+ means that the C code has no side effects and
+  may be elided entirely if its value is not used by script code.
+\item \verb+/* unprivileged */+ means that the C code is so safe that
+  even unprivileged users are permitted to use it. (This is useful, in
+  particular, to define an embedded-C function inside a tapset that
+  may be used by unprivileged code.)
+\item \verb+/* myproc-unprivileged */+ means that the C code is so
+  safe that even unprivileged users are permitted to use it, provided
+  that the target of the current probe is within the user's own
+  process.
+\item \verb+/* guru */+ means that the C code is so unsafe that a
+  systemtap user must specify \verb+-g+ (guru mode) to use this, even
+  if the C code is being exported from a tapset.
+\item \verb+/* unmangled */+, used in an embedded-C function, means
+  that the legacy (pre-1.8) argument access syntax should be made
+  available inside the function. Hence, in addition to
+  \verb+STAP_ARG_foo+ and \verb+STAP_RETVALUE+ one can use
+  \verb+THIS->foo+ and \verb+THIS->__retvalue+ respectively inside the
+  function. This is useful for quickly migrating code written for
+  SystemTap version 1.7 and earlier.
+\item \verb+/* string */+ in embedded-C expressions only, means that
+  the expression has \verb+const char *+ type and should be treated as
+  a string value, instead of the default long numeric.
+\end{itemize}
+
 \section{Probe points\label{sec:Probe-Points}}
 \index{probe points}
 \subsection{General syntax}
diff --git a/stap.1 b/stap.1
index 25653c41c..bffb1e7fc 100644
--- a/stap.1
+++ b/stap.1
@@ -1404,7 +1404,9 @@ means that the C code is so unsafe that a systemtap user must specify
 (guru mode) to use this.
 .TP
 .I /* unmangled */
-means that the legacy (pre-1.8) argument access syntax should be made available inside the function. Hence, in addition to
+in an embedded-C function, means that the legacy (pre-1.8) argument
+access syntax should be made available inside the function. Hence, in
+addition to
 .I STAP_ARG_foo
 and
 .I STAP_RETVALUE
@@ -1412,7 +1414,7 @@ one can use
 .I THIS->foo
 and
 .I THIS->__retvalue
-respectively in side the function. This is useful for quickly migrating code written for SystemTap version 1.7 and earlier.
+respectively inside the function. This is useful for quickly migrating code written for SystemTap version 1.7 and earlier.
 .TP
 .I /* string */
 in embedded-C expressions only, means that the expression has
-- 
2.43.5