Merge from trunk, r11508 (fix bogus documentation for

VALGRIND_CREATE_BLOCK)

git-svn-id: svn://svn.valgrind.org/valgrind/branches/VALGRIND_3_6_BRANCH@11544

diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml
index 8fd88b487bf0cee4b6ccfc6eb8b844f103f2283a..a590d585a74083da7b88ff35f9bb4a374a6443c7 100644 (file)
--- a/memcheck/docs/mc-manual.xml
+++ b/memcheck/docs/mc-manual.xml
@@ -1288,10 +1288,7 @@ arguments.</para>
     <varname>VALGRIND_MAKE_MEM_DEFINED</varname>.
     These mark address ranges as completely inaccessible,
     accessible but containing undefined data, and accessible and
-    containing defined data, respectively.  Subsequent errors may
-    have their faulting addresses described in terms of these
-    blocks.  Returns a "block handle".  Returns zero when not run
-    on Valgrind.</para>
+    containing defined data, respectively.</para>
   </listitem>
 
   <listitem>
@@ -1300,21 +1297,6 @@ arguments.</para>
     affects those bytes that are already addressable.</para>
   </listitem>
 
-  <listitem>
-    <para><varname>VALGRIND_DISCARD</varname>: At some point you may
-    want Valgrind to stop reporting errors in terms of the blocks
-    defined by the previous three macros.  To do this, the above macros
-    return a small-integer "block handle".  You can pass this block
-    handle to <varname>VALGRIND_DISCARD</varname>.  After doing so,
-    Valgrind will no longer be able to relate addressing errors to the
-    user-defined block associated with the handle.  The permissions
-    settings associated with the handle remain in place; this just
-    affects how errors are reported, not whether they are reported.
-    Returns 1 for an invalid handle and 0 for a valid handle (although
-    passing invalid handles is harmless).  Always returns 0 when not run
-    on Valgrind.</para>
-  </listitem>
-
   <listitem>
     <para><varname>VALGRIND_CHECK_MEM_IS_ADDRESSABLE</varname> and
     <varname>VALGRIND_CHECK_MEM_IS_DEFINED</varname>: check immediately
@@ -1372,6 +1354,30 @@ arguments.</para>
     know what they are doing.</para>
   </listitem>
 
+  <listitem>
+    <para><varname>VALGRIND_CREATE_BLOCK</varname> and 
+    <varname>VALGRIND_DISCARD</varname>.  <varname>VALGRIND_CREATE_BLOCK</varname>
+    takes an address, a number of bytes and a character string.  The
+    specified address range is then associated with that string.  When
+    Memcheck reports an invalid access to an address in the range, it
+    will describe it in terms of this block rather than in terms of
+    any other block it knows about.  Note that the use of this macro
+    does not actually change the state of memory in any way -- it
+    merely gives a name for the range.
+    </para>
+
+    <para>At some point you may want Memcheck to stop reporting errors
+    in terms of the block named
+    by <varname>VALGRIND_CREATE_BLOCK</varname>.  To make this
+    possible, <varname>VALGRIND_CREATE_BLOCK</varname> returns a
+    "block handle", which is a C <varname>int</varname> value.  You
+    can pass this block handle to <varname>VALGRIND_DISCARD</varname>.
+    After doing so, Valgrind will no longer relate addressing errors
+    in the specified range to the block.  Passing invalid handles to
+    <varname>VALGRIND_DISCARD</varname> is harmless.
+   </para>
+  </listitem>
+
 </itemizedlist>
 
 </sect1>