From: Kristof Umann <dkszelethus@gmail.com>
Date: Thu, 15 Aug 2019 08:52:10 +0000 (+0000)
Subject: [analyzer] Add docs for cplusplus.InnerPointer
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9979caf37555c34d181467c1af52410086e19f59;p=clang

[analyzer] Add docs for cplusplus.InnerPointer

Differential Revision: https://reviews.llvm.org/D60281

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@368979 91177308-0d34-0410-b5e6-96231b3b80d8
---

diff --git a/docs/analyzer/checkers.rst b/docs/analyzer/checkers.rst
index e5b60bbf15..f50fff918c 100644
--- a/docs/analyzer/checkers.rst
+++ b/docs/analyzer/checkers.rst
@@ -242,10 +242,35 @@ C++ Checkers.
 
 .. _cplusplus-InnerPointer:
 
-cplusplus.InnerPointer
-""""""""""""""""""""""
+cplusplus.InnerPointer (C++)
+""""""""""""""""""""""""""""
 Check for inner pointers of C++ containers used after re/deallocation.
 
+Many container methods in the C++ standard library are known to invalidate
+"references" (including actual references, iterators and raw pointers) to
+elements of the container. Using such references after they are invalidated
+causes undefined behavior, which is a common source of memory errors in C++ that
+this checker is capable of finding.
+
+The checker is currently limited to ``std::string`` objects and doesn't
+recognize some of the more sophisticated approaches to passing unowned pointers
+around, such as ``std::string_view``.
+
+.. code-block:: cpp
+
+ void deref_after_assignment() {
+   std::string s = "llvm";
+   const char *c = s.data(); // note: pointer to inner buffer of 'std::string' obtained here
+   s = "clang"; // note: inner buffer of 'std::string' reallocated by call to 'operator='
+   consume(c); // warn: inner pointer of container used after re/deallocation
+ }
+
+ const char *return_temp(int x) {
+   return std::to_string(x).c_str(); // warn: inner pointer of container used after re/deallocation
+   // note: pointer to inner buffer of 'std::string' obtained here
+   // note: inner buffer of 'std::string' deallocated by call to destructor
+ }
+
 .. _cplusplus-NewDelete:
 
 cplusplus.NewDelete (C++)