Repo sync for protected branch

docs/code-quality/c6059.md

@@ -1,7 +1,7 @@
 ---
 description: "Learn more about: Warning C6059"
 title: Warning C6059
-ms.date: 10/04/2022
+ms.date: 12/14/2023
 f1_keywords: ["C6059", "BAD_CONCATENATION", "__WARNING_BAD_CONCATENATION"]
 helpviewer_keywords: ["C6059"]
 ms.assetid: 343a4cd1-048a-4edf-bb4b-187097bb6093
@@ -14,6 +14,8 @@ ms.assetid: 343a4cd1-048a-4edf-bb4b-187097bb6093
 
 This warning indicates that a call to a string concatenation function is probably passing an incorrect value for the number of characters to concatenate. This defect might cause an exploitable buffer overrun or crash. A common cause of this defect is passing the buffer size (instead of the remaining number of characters in the buffer) to the string manipulation function.
 
+This warning helps identify the common error of sending the size of the target buffer instead of the size of the data. It does so by detecting when the size used to allocate the buffer is passed, unchanged, to the function putting data in the buffer.
+
 Code analysis name: `BAD_CONCATENATION`
 
 ## Example
@@ -27,8 +29,8 @@ The following code generates warning C6059:
 void f( )
 {
   char szTarget[MAX];
-  char *szState ="Washington";
-  char *szCity="Redmond, ";
+  const char *szState ="Washington";
+  const char *szCity="Redmond, ";
 
   strncpy(szTarget, szCity, MAX);
   szTarget[MAX -1] = '\0';
@@ -46,8 +48,8 @@ To correct this warning, use the correct number of characters to concatenate as
 void f( )
 {
   char szTarget[MAX];
-  char *szState ="Washington";
-  char *szCity="Redmond, ";
+  const char *szState ="Washington";
+  const char *szCity="Redmond, ";
 
   strncpy(szTarget, szCity, MAX);
   szTarget[MAX -1] = '\0';
@@ -63,8 +65,8 @@ To correct this warning using the safe string manipulation functions `strncpy_s`
 
 void f( )
 {
-  char *szState ="Washington";
-  char *szCity="Redmond, ";
+  const char *szState ="Washington";
+  const char *szCity="Redmond, ";
 
   size_t nTargetSize = strlen(szState) + strlen(szCity) + 1;
   char *szTarget= new char[nTargetSize];
@@ -77,6 +79,48 @@ void f( )
 }
 ```
 
+## Heuristics
+
+This analysis detects when the target buffer size is passed unmodified into the length parameter of the string manipulation function. This warning isn't given if some other value is passed as the length parameter, even if that value is incorrect.
+
+Consider the following code that generates warning C6059:
+
+```cpp
+#include <string.h>
+#define MAX 25
+
+void f( )
+{
+  char szTarget[MAX];
+  const char *szState ="Washington";
+  const char *szCity="Redmond, ";
+
+  strncpy(szTarget, szCity, MAX);
+  szTarget[MAX -1] = '\0';
+  strncat(szTarget, szState, MAX); // wrong size
+  // code ...
+}
+```
+
+The warning goes away by changing the `MAX` argument to `strncat` to `MAX - 1`, even though the length calculation is still incorrect.
+
+```cpp
+#include <string.h>
+#define MAX 25
+
+void f( )
+{
+  char szTarget[MAX];
+  const char *szState ="Washington";
+  const char *szCity="Redmond, ";
+
+  strncpy(szTarget, szCity, MAX);
+  szTarget[MAX -1] = '\0';
+  strncat(szTarget, szState, MAX - 1); // wrong size, but no warning
+  // code ...
+}
+```
+
 ## See also
 
 - [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)