PR10300: document STAP_RETURN()

diff --git a/NEWS b/NEWS
index 353de8de93d8e00fe05fc5cd01aaeffad1489966..7de5fbb63ebf15dfa2053a890581ae89c5da3dfe 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -3,6 +3,10 @@
 - SystemTap now reports more accurate and succinct errors on type
   mismatches.
 
+- Embedded-C functions may use STAP_RETURN(value) instead of the
+  more wordy STAP_RETVALUE assignment followed by a "goto out".
+  The macro supports numeric or string values as appropriate.
+
 * What's new in version 2.4, 2013-11-06
 
 - Better suggestions are given in many of the semantic errors in which

diff --git a/doc/langref.tex b/doc/langref.tex
index bf862318b1cc42134fd5806ffec5d9aad5a04483..bdaf829d7e5c9799a7d7e88fac8d928e13643083 100644 (file)
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -660,7 +660,7 @@ Here is an example of the various permitted methods of embedded C code inclusion
 
 /* Reads the char value stored at a given address: */ 
 function __read_char:long(addr:long) %{ /* pure */
-         STAP_RETVALUE = kderef(sizeof(char), STAP_ARG_addr);
+         STAP_RETURN(kderef(sizeof(char), STAP_ARG_addr));
          CATCH_DEREF_FAULT ();
 %} /* <-- function body */
 
@@ -713,28 +713,39 @@ name = kread(&(dev->name));
 The memory locations reserved for input and output values are provided
 to a function using macros named
 \texttt{STAP\_ARG\_foo}\index{STAP_ARG_} (for arguments named
-\texttt{foo}) and \texttt{STAP\_RETVALUE}\index{STAP_RETVALUE}. The
-following are examples.
+\texttt{foo}) and \texttt{STAP\_RETVALUE}\index{STAP_RETVALUE}.
+Errors may be signalled with \texttt{STAP\_ERROR}.  The function may return                       early with \texttt{STAP\_RETURN}.  Here are some examples:
 
 \begin{vindent}
 \begin{verbatim}
-function add_one (val:long) %{
-    STAP_RETVALUE = STAP_ARG_val + 1;
+function integer_ops:long (val) %{
+  STAP_RETVALUE = STAP_ARG_val + 1;
+  if (STAP_RETVALUE == 4)
+      STAP_ERROR("wrong guess: %d", (int) STAP_RETVALUE);
+  if (STAP_RETVALUE == 3)
+      STAP_RETURN(0);
+  STAP_RETVALUE ++;
 %}
-function add_one_str:string (val:string) %{
-    strlcpy (STAP_RETVALUE, STAP_ARG_val, MAXSTRINGLEN);
-    strlcat (STAP_RETVALUE, "one", MAXSTRINGLEN);
+function string_ops:string (val) %{
+  strlcpy (STAP_RETVALUE, STAP_ARG_val, MAXSTRINGLEN);
+  strlcat (STAP_RETVALUE, "one", MAXSTRINGLEN);
+  if (strcmp (STAP_RETVALUE, "three-two-one"))
+      STAP_RETURN("parameter should be three-two-");
+%}
+function no_ops () %{
+    STAP_RETURN(); /* function inferred with no return value */
 %}
 \end{verbatim}
 \end{vindent}
 
-The function argument and return value types should be stated;
-the translator does not analyze the embedded C code within the function.
-You should examine
-C code generated for ordinary script language functions to write compatible
-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.
+The function argument and return value types should be stated if the
+translator cannot infer them from usage.  The translator does not
+analyze the embedded C code within the function.
+
+You should examine C code generated for ordinary script language
+functions to write compatible embedded-C.  Usually, 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}
 

diff --git a/man/stap.1 b/man/stap.1
index 2e4f504198dab73e1d5af64a946cca015e20105a..4ffe3a58b4afbb5fbf302f7e96e43b96612fe7d3 100644 (file)
--- a/man/stap.1
+++ b/man/stap.1
@@ -1442,18 +1442,29 @@ are made available to it using macros
 .IR STAP_ARG_*
 and
 .IR STAP_RETVALUE .
-Here are some examples:
+Errors may be signalled with STAP_ERROR.  The function may return
+early with STAP_RETURN.  Here are some examples:
 .SAMPLE
-function add_one (val) %{
+function integer_ops (val) %{
   STAP_RETVALUE = STAP_ARG_val + 1;
+  if (STAP_RETVALUE == 4)
+      STAP_ERROR("wrong guess: %d", (int) STAP_RETVALUE);
+  if (STAP_RETVALUE == 3)
+      STAP_RETURN(0);
+  STAP_RETVALUE ++;
 %}
-function add_one_str (val) %{
+function string_ops (val) %{
   strlcpy (STAP_RETVALUE, STAP_ARG_val, MAXSTRINGLEN);
   strlcat (STAP_RETVALUE, "one", MAXSTRINGLEN);
+  if (strcmp (STAP_RETVALUE, "three-two-one"))
+      STAP_RETURN("parameter should be three-two-");
+%}
+function no_ops () %{
+    STAP_RETURN(); /* function inferred with no return value */
 %}
 .ESAMPLE
 The function argument and return value types have to be inferred by
-the translator from the call sites in order for this to work.  The
+the translator from the call sites in order for this to work. The
 user should examine C code generated for ordinary script-language
 functions in order to write compatible embedded-C ones.
 .PP