[clang-tidy] introduce legacy resource functions to 'cppcoreguidelines-owning-memory'

Summary:
This patch introduces support for legacy C-style resource functions that must obey
the 'owner<>' semantics.

- added legacy creators like malloc,fopen,...
- added legacy consumers like free,fclose,...

This helps codes that mostly benefit from owner:
Legacy, C-Style code that isn't feasable to port directly to RAII but needs a step in between
to identify actual resource management and just using the resources.

Reviewers: aaron.ballman, alexfh, hokein

Reviewed By: aaron.ballman

Subscribers: nemanjai, JDevlieghere, xazax.hun, kbarton

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

llvm-svn: 316092

1 files changed, 31 insertions, 2 deletions

diff --git a/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines-owning-memory.rst b/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines-owning-memory.rst
index 2b6a083615e..116b3351c08 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines-owning-memory.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines-owning-memory.rst
@@ -20,7 +20,8 @@ the `Guideline Support Library <https://github.com/isocpp/CppCoreGuidelines/blob
 All checks are purely type based and not (yet) flow sensitive.
 
 The following examples will demonstrate the correct and incorrect initializations
-of owners, assignment is handled the same way.
+of owners, assignment is handled the same way. Note that both ``new`` and 
+``malloc()``-like resource functions are considered to produce resources.
 
 .. code-block:: c++
 
@@ -69,6 +70,33 @@ argument get called with either a ``gsl::owner<T*>`` or a newly created resource
   expects_owner(Owner); // Good
   expects_owner(new int(42)); // Good as well, recognized created resource
 
+  // Port legacy code for better resource-safety
+  gsl::owner<FILE*> File = fopen("my_file.txt", "rw+");
+  FILE* BadFile = fopen("another_file.txt", "w"); // Bad, warned
+
+  // ... use the file
+
+  fclose(File); // Ok, File is annotated as 'owner<>'
+  fclose(BadFile); // BadFile is not an 'owner<>', will be warned
+
+
+Options
+-------
+
+.. option:: LegacyResourceProducers
+
+   Semicolon-separated list of fully qualified names of legacy functions that create
+   resources but cannot introduce ``gsl::owner<>``.
+   Defaults to ``::malloc;::aligned_alloc;::realloc;::calloc;::fopen;::freopen;::tmpfile``.
+
+
+.. option:: LegacyResourceConsumers
+
+   Semicolon-separated list of fully qualified names of legacy functions expecting
+   resource owners as pointer arguments but cannot introduce ``gsl::owner<>``.
+   Defaults to ``::free;::realloc;::freopen;::fclose``.
+
+
 Limitations
 -----------
 
@@ -82,7 +110,8 @@ Using ``gsl::owner<T*>`` in a typedef or alias is not handled correctly.
 The ``gsl::owner<T*>`` is declared as a templated type alias.
 In template functions and classes, like in the example below, the information
 of the type aliases gets lost. Therefore using ``gsl::owner<T*>`` in a heavy templated
-code base might lead to false positives.
+code base might lead to false positives. 
+This limitation results in ``std::vector<gsl::owner<T*>>`` not being diagnosed correctly.
 
 .. code-block:: c++