[Secure Coding] master: C++: Warn about functions that deal with unpaired iterators (2067762)

Repository : http://git.fedorahosted.org/git/?p=secure-coding.git

On branch  : master

> ---------------------------------------------------------------
commit 2067762b472676ef892b55a5263bcf3dd0f16040
Author: Florian Weimer <fweimer(a)redhat.com&gt;
Date:   Tue Sep 17 13:51:27 2013 +0200

    C++: Warn about functions that deal with unpaired iterators


> ---------------------------------------------------------------
 defensive-coding/en-US/CXX-Std.xml |   60 ++++++++++++++++++++++++++++++++++++
 1 files changed, 60 insertions(+), 0 deletions(-)

diff --git a/defensive-coding/en-US/CXX-Std.xml b/defensive-coding/en-US/CXX-Std.xml
index 88fa803..b221949 100644
--- a/defensive-coding/en-US/CXX-Std.xml
+++ b/defensive-coding/en-US/CXX-Std.xml
@@ -7,6 +7,61 @@
     The C++ standard library includes most of its C counterpart
     by reference, see <xref linkend="sect-Defensive_Coding-C-Libc"/>.
   </para>
+  <section id="sect-Defensive_Coding-CXX-Std-Functions">
+    <title>Functions that are difficult to use</title>
+    <para>
+      This section collects functions and function templates which are
+      part of the standard library and are difficult to use.
+    </para>
+    <section
id="sect-Defensive_Coding-CXX-Std-Functions-Unpaired_Iterators">
+      <title>Unpaired iterators</title>
+      <para>
+	Functions which use output operators or iterators which do not
+	come in pairs (denoting ranges) cannot perform iterator range
+	checking.
+	(See <xref linkend="sect-Defensive_Coding-CXX-Std-Iterators"/>)
+	Function templates which involve output iterators are
+	particularly dangerous:
+      </para>
+      <itemizedlist>
+	<listitem><para><function>std::copy</function></para></listitem>
+	<listitem><para><function>std::copy_backward</function></para></listitem>
+	<listitem><para><function>std::copy_if</function></para></listitem>
+	<listitem><para><function>std::move</function> (three-argument
variant)</para></listitem>
+	<listitem><para><function>std::move_backward</function></para></listitem>
+	<listitem><para><function>std::partition_copy_if</function></para></listitem>
+	<listitem><para><function>std::remove_copy</function></para></listitem>
+	<listitem><para><function>std::remove_copy_if</function></para></listitem>
+	<listitem><para><function>std::replace_copy</function></para></listitem>
+	<listitem><para><function>std::replace_copy_if</function></para></listitem>
+	<listitem><para><function>std::swap_ranges</function></para></listitem>
+	<listitem><para><function>std::transform</function></para></listitem>
+      </itemizedlist>
+      <para>
+	In addition, <function>std::copy_n</function>,
+	<function>std::fill_n</function> and
+	<function>std::generate_n</function> do not perform iterator
+	checking, either, but there is an explicit count which has to be
+	supplied by the caller, as opposed to an implicit length
+	indicator in the form of a pair of forward iterators.
+      </para>
+      <para>
+	These output-iterator-expecting functions should only be used
+	with unlimited-range output iterators, such as iterators
+	obtained with the <function>std::back_inserter</function>
+	function.
+      </para>
+      <para>
+	Other functions use single input or forward iterators, which can
+	read beyond the end of the input range if the caller is not careful:
+      </para>
+      <itemizedlist>
+	<listitem><para><function>std::equal</function></para></listitem>
+	<listitem><para><function>std::is_permutation</function></para></listitem>
+	<listitem><para><function>std::mismatch</function></para></listitem>
+      </itemizedlist>
+    </section>
+  </section>
   <section id="sect-Defensive_Coding-CXX-Std-String">
     <title>String handling with
<literal>std::string</literal></title>
     <para>
@@ -124,6 +179,11 @@
       supplied an output area that is too small, and their use should
       be avoided.
     </para>
+    <para>
+      These issues make some of the standard library functions
+      difficult to use correctly, see <xref
+     
linkend="sect-Defensive_Coding-CXX-Std-Functions-Unpaired_Iterators"/>.
+    </para>
   </section>
 </section>