From 798b845ce1c4b701190d34d6793bffca946b0fc9 Mon Sep 17 00:00:00 2001
From: PKEuS <kloke@uni-bonn.de>
Date: Sun, 28 Sep 2014 22:20:28 +0200
Subject: [PATCH] Added <use-retval/> to manual.docbook

---
 man/manual.docbook | 35 ++++++++++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/man/manual.docbook b/man/manual.docbook
index 4aebf0246..16027a9cf 100644
--- a/man/manual.docbook
+++ b/man/manual.docbook
@@ -5,7 +5,7 @@
   <bookinfo>
     <title>Cppcheck 1.67 dev</title>
 
-    <date>2013-12-23</date>
+    <date>2014-09-28</date>
   </bookinfo>
 
   <chapter>
@@ -846,6 +846,39 @@ Checking noreturn.c...
 &lt;/def&gt;</programlisting>
     </section>
 
+    <section>
+      <title>use-retval</title>
+
+      <para>Per default, cppcheck assumes that ignoring the return value of a function is ok:</para>
+
+      <programlisting>bool test(const char* a, const char* b)
+{
+    strcmp(a, b);  // &lt;- bug: The call of strcmp does not have side-effects, but the return value is ignored.
+    return true;
+}</programlisting>
+
+      <para>In case <literal>strcmp</literal> has side effects, such as assigning the result to one of the parameters passed to it, nothing bad would happen:</para>
+
+      <programlisting># cppcheck useretval.c 
+Checking useretval.c...</programlisting>
+
+      <para>If a proper <literal>lib.cfg</literal> is provided, the bug is
+      detected:</para>
+
+      <programlisting># cppcheck --library=lib.cfg --enable=warning useretval.c 
+Checking useretval.c...
+[noreturn.c:3]: (warning) Return value of function strcmp() is not used.</programlisting>
+
+      <para>Here is a minimal <literal>lib.cfg</literal> file:</para>
+
+      <programlisting>&lt;?xml version="1.0"?&gt;
+&lt;def&gt;
+  &lt;function name="strcmp"&gt;
+    &lt;use-retval/&gt;
+  &lt;/function&gt;
+&lt;/def&gt;</programlisting>
+    </section>
+
     <section>
       <title>Example configuration for strcpy()</title>