clang-tools-extra/docs/clang-tidy/checks/bugprone-not-null-terminated-result.rst

   1 .. title:: clang-tidy - bugprone-not-null-terminated-result
   2
   3 bugprone-not-null-terminated-result
   4 ===================================
   5
   6 Finds function calls where it is possible to cause a not null-terminated result.
   7 Usually the proper length of a string is ``strlen(src) + 1`` or equal length of
   8 this expression, because the null terminator needs an extra space. Without the
   9 null terminator it can result in undefined behavior when the string is read.
  10
  11 The following and their respective ``wchar_t`` based functions are checked:
  12
  13 ``memcpy``, ``memcpy_s``, ``memchr``, ``memmove``, ``memmove_s``,
  14 ``strerror_s``, ``strncmp``, ``strxfrm``
  15
  16 The following is a real-world example where the programmer forgot to increase
  17 the passed third argument, which is ``size_t length``. That is why the length
  18 of the allocated memory is not enough to hold the null terminator.
  19
  20 .. code-block:: c
  21
  22   static char *stringCpy(const std::string &str) {
  23     char *result = reinterpret_cast<char *>(malloc(str.size()));
  24     memcpy(result, str.data(), str.size());
  25     return result;
  26   }
  27
  28 In addition to issuing warnings, fix-it rewrites all the necessary code. It also
  29 tries to adjust the capacity of the destination array:
  30
  31 .. code-block:: c
  32
  33   static char *stringCpy(const std::string &str) {
  34     char *result = reinterpret_cast<char *>(malloc(str.size() + 1));
  35     strcpy(result, str.data());
  36     return result;
  37   }
  38
  39 Note: It cannot guarantee to rewrite every of the path-sensitive memory
  40 allocations.
  41
  42 .. _MemcpyTransformation:
  43
  44 Transformation rules of 'memcpy()'
  45 ----------------------------------
  46
  47 It is possible to rewrite the ``memcpy()`` and ``memcpy_s()`` calls as the
  48 following four functions:  ``strcpy()``, ``strncpy()``, ``strcpy_s()``,
  49 ``strncpy_s()``, where the latter two are the safer versions of the former two.
  50 It rewrites the ``wchar_t`` based memory handler functions respectively.
  51
  52 Rewrite based on the destination array
  53 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  54
  55 - If copy to the destination array cannot overflow [1] the new function should
  56   be the older copy function (ending with ``cpy``), because it is more
  57   efficient than the safe version.
  58
  59 - If copy to the destination array can overflow [1] and
  60   :option:`WantToUseSafeFunctions` is set to `true` and it is possible to
  61   obtain the capacity of the destination array then the new function could be
  62   the safe version (ending with ``cpy_s``).
  63
  64 - If the new function is could be safe version and C++ files are analyzed and
  65   the destination array is plain ``char``/``wchar_t`` without ``un/signed`` then
  66   the length of the destination array can be omitted.
  67
  68 - If the new function is could be safe version and the destination array is
  69   ``un/signed`` it needs to be casted to plain ``char *``/``wchar_t *``.
  70
  71 [1] It is possible to overflow:
  72   - If the capacity of the destination array is unknown.
  73   - If the given length is equal to the destination array's capacity.
  74
  75 Rewrite based on the length of the source string
  76 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  77
  78 - If the given length is ``strlen(source)`` or equal length of this expression
  79   then the new function should be the older copy function (ending with ``cpy``),
  80   as it is more efficient than the safe version (ending with ``cpy_s``).
  81
  82 - Otherwise we assume that the programmer wanted to copy 'N' characters, so the
  83   new function is ``ncpy``-like which copies 'N' characters.
  84
  85 Transformations with 'strlen()' or equal length of this expression
  86 ------------------------------------------------------------------
  87
  88 It transforms the ``wchar_t`` based memory and string handler functions
  89 respectively (where only ``strerror_s`` does not have ``wchar_t`` based alias).
  90
  91 Memory handler functions
  92 ^^^^^^^^^^^^^^^^^^^^^^^^
  93
  94 ``memcpy``
  95 Please visit the
  96 :ref:`Transformation rules of 'memcpy()'<MemcpyTransformation>` section.
  97
  98 ``memchr``
  99 Usually there is a C-style cast and it is needed to be removed, because the
 100 new function ``strchr``'s return type is correct. The given length is going
 101 to be removed.
 102
 103 ``memmove``
 104 If safe functions are available the new function is ``memmove_s``, which has
 105 a new second argument which is the length of the destination array, it is
 106 adjusted, and the length of the source string is incremented by one.
 107 If safe functions are not available the given length is incremented by one.
 108
 109 ``memmove_s``
 110 The given length is incremented by one.
 111
 112 String handler functions
 113 ^^^^^^^^^^^^^^^^^^^^^^^^
 114
 115 ``strerror_s``
 116 The given length is incremented by one.
 117
 118 ``strncmp``
 119 If the third argument is the first or the second argument's ``length + 1``
 120 it has to be truncated without the ``+ 1`` operation.
 121
 122 ``strxfrm``
 123 The given length is incremented by one.
 124
 125 Options
 126 -------
 127
 128 .. option::  WantToUseSafeFunctions
 129
 130    The value `true` specifies that the target environment is considered to
 131    implement '_s' suffixed memory and string handler functions which are safer
 132    than older versions (e.g. 'memcpy_s()'). The default value is `true`.