Merge pull request #5140 from MicrosoftDocs/main

1/4/2024 AM Publish

Author: PhilKang0704

docs/build/walkthrough-header-units.md

@@ -36,7 +36,7 @@ Header units impose fewer constraints on the required similarities of compiler s
 
 Finally, header units are more flexible than a PCH. With a PCH, you can't choose to bring in only one of the headers in the PCH--the compiler processes all of them. With header units, even when you compile them together into a static library, you only bring the contents of the header unit you import into your application.
 
-Header units are a step in between header files and C++ 20 modules. They provide some of the benefits of modules. They're more robust because outside macro definitions don't affect them--so you can import them in any order. And the compiler can process them faster than header files. But header units don't have all of the advantages of modules because header units expose the macros defined within them (modules don't). Unlike modules, there's no way to hide private implementation in a header unit. To indicate private implementation with header files, different techniques are employed like adding leading underscores to names, or putting things in an implementation namespace. A module doesn't expose private implementation in any form, so you don't need to do that.
+Header units are a step in between header files and C++20 modules. They provide some of the benefits of modules. They're more robust because outside macro definitions don't affect them--so you can import them in any order. And the compiler can process them faster than header files. But header units don't have all of the advantages of modules because header units expose the macros defined within them (modules don't). Unlike modules, there's no way to hide private implementation in a header unit. To indicate private implementation with header files, different techniques are employed like adding leading underscores to names, or putting things in an implementation namespace. A module doesn't expose private implementation in any form, so you don't need to do that.
 
 Consider replacing your precompiled headers with header units. You get the same speed advantage, but with other code hygiene and flexibility benefits as well.
 

docs/code-quality/c28112.md

@@ -38,5 +38,5 @@ InterlockedIncrement(&inter_var);
 
 ## See Also
 
-[InterlockedIncrement function (wdm.h)](/windows-hardware/drivers/ddi/wdm/nf-wdm-interlockedincrement)
+[InterlockedIncrement function (wdm.h)](/windows-hardware/drivers/ddi/wdm/nf-wdm-interlockedincrement)\
 [InterlockedDecrement function (wdm.h)](/windows-hardware/drivers/ddi/wdm/nf-wdm-interlockeddecrement)

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)

docs/cpp/align-cpp.md

@@ -7,7 +7,7 @@ helpviewer_keywords: ["align __declspec keyword", "__declspec keyword [C++], ali
 ---
 # `align` (C++)
 
-In Visual Studio 2015 and later, use [**`alignas`** specifier](../cpp/alignas-specifier.md) (C++ 11) to control alignment. For more information, see [Alignment](../cpp/alignment-cpp-declarations.md).
+In Visual Studio 2015 and later, use [**`alignas`** specifier](../cpp/alignas-specifier.md) (C++11) to control alignment. For more information, see [Alignment](../cpp/alignment-cpp-declarations.md).
 
 **Microsoft Specific**
 

docs/cpp/compiler-limits.md

@@ -6,7 +6,7 @@ helpviewer_keywords: ["cl.exe compiler, limits for language constructs"]
 ---
 # Compiler Limits
 
-The C++ standard recommends limits for various language constructs. The following is a list of cases where the Microsoft C++ compiler does not implement the recommended limits. The first number is the limit that is established in the ISO C++ 11 standard (INCITS/ISO/IEC 14882-2011[2012], Annex B) and the second number is the limit implemented by the Microsoft C++ compiler:
+The C++ standard recommends limits for various language constructs. The following is a list of cases where the Microsoft C++ compiler does not implement the recommended limits. The first number is the limit that is established in the ISO C++11 standard (INCITS/ISO/IEC 14882-2011[2012], Annex B) and the second number is the limit implemented by the Microsoft C++ compiler:
 
 - Nesting levels of compound statements, iteration control structures, and selection control structures - C++ standard: 256, Microsoft C++ compiler: depends on the combination of statements that are nested, but generally between 100 and 110.
 

docs/cpp/function-call-operator-parens.md

@@ -17,7 +17,7 @@ A function call is a kind of *`postfix-expression`*, formed by an expression tha
 
 ## Remarks
 
-The arguments to the function-call operator come from an *`argument-expression-list`*, a comma-separated list of expressions. The values of these expressions are passed to the function as arguments. The *argument-expression-list* can be empty. Before C++ 17, the order of evaluation of the function expression and the argument expressions is unspecified and may occur in any order. In C++17 and later, the function expression is evaluated before any argument expressions or default arguments. The argument expressions are evaluated in an indeterminate sequence.
+The arguments to the function-call operator come from an *`argument-expression-list`*, a comma-separated list of expressions. The values of these expressions are passed to the function as arguments. The *argument-expression-list* can be empty. Before C++17, the order of evaluation of the function expression and the argument expressions is unspecified and may occur in any order. In C++17 and later, the function expression is evaluated before any argument expressions or default arguments. The argument expressions are evaluated in an indeterminate sequence.
 
 The *`postfix-expression`* evaluates to the function to call. It can take any of several forms:
 

docs/cpp/functions-cpp.md

@@ -180,7 +180,7 @@ When a function modifies an argument that is passed by reference, it modifies th
 void DoSomething(const std::string& input){...}
 ```
 
-**C++ 11:**  To explicitly handle arguments that are passed by rvalue-reference or lvalue-reference, use a double-ampersand on the parameter to indicate a universal reference:
+**C++11:**  To explicitly handle arguments that are passed by rvalue-reference or lvalue-reference, use a double-ampersand on the parameter to indicate a universal reference:
 
 ```cpp
 void DoSomething(const std::string&& input){...}

docs/cpp/lambda-expressions-in-cpp.md

@@ -105,7 +105,7 @@ When you use the capture clause, we recommend that you keep these points in mind
 
 - Reference captures introduce a lifetime dependency, but value captures have no lifetime dependencies. It's especially important when the lambda runs asynchronously. If you capture a local by reference in an async lambda, that local could easily be gone by the time the lambda runs. Your code could cause an access violation at run time.
 
-### Generalized capture (C++ 14)
+### Generalized capture (C++14)
 
 In C++14, you can introduce and initialize new variables in the capture clause, without the need to have those variables exist in the lambda function's enclosing scope. The initialization can be expressed as any arbitrary expression; the type of the new variable is deduced from the type produced by the expression. This feature lets you capture move-only variables (such as `std::unique_ptr`) from the surrounding scope and use them in a lambda.
 

docs/cpp/namespaces-cpp.md

@@ -139,7 +139,7 @@ namespace ContosoDataServer
 
 Ordinary nested namespaces can be used to encapsulate internal implementation details that are not part of the public interface of the parent namespace.
 
-## Inline namespaces (C++ 11)
+## Inline namespaces (C++11)
 
 In contrast to an ordinary nested namespace, members of an inline namespace are treated as members of the parent namespace. This characteristic enables argument dependent lookup on overloaded functions to work on functions that have overloads in a parent and a nested inline namespace. It also enables you to declare a specialization in a parent namespace for a template that is declared in the inline namespace. The following example shows how external code binds to the inline namespace by default:
 

docs/cpp/nonstandard-behavior.md

@@ -7,13 +7,13 @@ ms.assetid: a57dea27-dc79-4f64-8a83-017e84841773
 ---
 # Nonstandard Behavior
 
-The following sections list some of the places where the Microsoft implementation of C++ doesn't conform to the C++ standard. The section numbers given below refer to the section numbers in the C++ 11 standard (ISO/IEC 14882:2011(E)).
+The following sections list some of the places where the Microsoft implementation of C++ doesn't conform to the C++ standard. The section numbers given below refer to the section numbers in the C++11 standard (ISO/IEC 14882:2011(E)).
 
 The list of compiler limits that differ from those defined in the C++ standard is given in [Compiler Limits](../cpp/compiler-limits.md).
 
 ## Covariant Return Types
 
-Virtual base classes are not supported as covariant return types when the virtual function has a variable number of arguments. This doesn't conform to section 10.3, paragraph 7 of the C++ 11 ISO specification. The following sample doesn't compile; it generates compiler error [C2688](../error-messages/compiler-errors-2/compiler-error-c2688.md):
+Virtual base classes are not supported as covariant return types when the virtual function has a variable number of arguments. This doesn't conform to section 10.3, paragraph 7 of the C++11 ISO specification. The following sample doesn't compile; it generates compiler error [C2688](../error-messages/compiler-errors-2/compiler-error-c2688.md):
 
 ```cpp
 // CovariantReturn.cpp
@@ -30,7 +30,7 @@ class B : virtual A
 
 ## Binding Nondependent Names in Templates
 
-The Microsoft C++ compiler doesn't currently support binding nondependent names when initially parsing a template. This doesn't conform to section 14.6.3 of the C++ 11 ISO specification. This can cause overloads declared after the template (but before the template is instantiated) to be seen.
+The Microsoft C++ compiler doesn't currently support binding nondependent names when initially parsing a template. This doesn't conform to section 14.6.3 of the C++11 ISO specification. This can cause overloads declared after the template (but before the template is instantiated) to be seen.
 
 ```cpp
 #include <iostream>
@@ -56,7 +56,7 @@ int main() {
 
 ## Function Exception Specifiers
 
-Function exception specifiers other than `throw()` are parsed but not used. This doesn't conform to section 15.4 of the ISO C++ 11 specification. For example:
+Function exception specifiers other than `throw()` are parsed but not used. This doesn't conform to section 15.4 of the ISO C++11 specification. For example:
 
 ```cpp
 void f() throw(int); // parsed but not used
@@ -67,7 +67,7 @@ For more information on exception specifications, see [Exception Specifications]
 
 ## char_traits::eof()
 
-The C++ standard states that [char_traits::eof](../standard-library/char-traits-struct.md#eof) must not correspond to a valid `char_type` value. The Microsoft C++ compiler enforces this constraint for type **`char`**, but not for type **`wchar_t`**. This doesn't conform to the requirement in Table 62 in section 12.1.1 of the C++ 11 ISO specification. The example below demonstrates this behavior.
+The C++ standard states that [char_traits::eof](../standard-library/char-traits-struct.md#eof) must not correspond to a valid `char_type` value. The Microsoft C++ compiler enforces this constraint for type **`char`**, but not for type **`wchar_t`**. This doesn't conform to the requirement in Table 62 in section 12.1.1 of the C++11 ISO specification. The example below demonstrates this behavior.
 
 ```cpp
 #include <iostream>

docs/cpp/user-defined-literals-cpp.md

@@ -6,7 +6,7 @@ ms.assetid: ff4a5bec-f795-4705-a2c0-53788fd57609
 ---
 # User-defined literals
 
-There are six major categories of literals in C++: integer, character, floating-point, string, boolean, and pointer. Starting in C++ 11, you can define your own literals based on these categories, to provide syntactic shortcuts for common idioms and increase type safety. For example, let's say you have a `Distance` class. You could define a literal for kilometers and another one for miles, and encourage the user to be explicit about the units of measure by writing: `auto d = 42.0_km` or `auto d = 42.0_mi`. There's no performance advantage or disadvantage to user-defined literals; they're primarily for convenience or for compile-time type deduction. The Standard Library has user-defined literals for `std::string`, for `std::complex`, and for units in time and duration operations in the \<chrono> header:
+There are six major categories of literals in C++: integer, character, floating-point, string, boolean, and pointer. Starting in C++11, you can define your own literals based on these categories, to provide syntactic shortcuts for common idioms and increase type safety. For example, let's say you have a `Distance` class. You could define a literal for kilometers and another one for miles, and encourage the user to be explicit about the units of measure by writing: `auto d = 42.0_km` or `auto d = 42.0_mi`. There's no performance advantage or disadvantage to user-defined literals; they're primarily for convenience or for compile-time type deduction. The Standard Library has user-defined literals for `std::string`, for `std::complex`, and for units in time and duration operations in the \<chrono> header:
 
 ```cpp
 Distance d = 36.0_mi + 42.0_km;         // Custom UDL (see below)

docs/error-messages/compiler-errors-2/compiler-error-c2956.md

@@ -17,7 +17,7 @@ Error C2956 indicates you used a *placement new expression* (a `new` expression
 
 The C++ standard specifies *usual deallocation functions* as overloads of `operator delete` or `operator delete[]` that take extra parameters of type `std::size_t` (C++14 or later), `std::align_val_t` (C++17 or later), and `std::destroying_delete_t` (C++20 or later). When you use a placement new expression, the compiler looks for a matching `operator delete` function that takes the same parameters (after the first one). If one is found and its signature matches a usual deallocation function, the compiler reports error C2956.
 
-The way to resolve the issue depends in part on your intent. For example, in C++ 11, you could define an `operator new` overload that takes an extra `size_t` parameter in your class to pass a value to the allocator. In C++ 14, the same code now causes an error:
+The way to resolve the issue depends in part on your intent. For example, in C++11, you could define an `operator new` overload that takes an extra `size_t` parameter in your class to pass a value to the allocator. In C++14, the same code now causes an error:
 
 ```cpp
 #include <new>

docs/error-messages/compiler-warnings/c4834.md

@@ -14,7 +14,7 @@ helpviewer_keywords: ["C4834"]
 Starting in the C++17 Standard, the `[[nodiscard]]` attribute specifies that a function's return value isn't intended to be discarded. If a caller discards the return value, the compiler generates warning C4834.
 
 To resolve this warning, consider why your code doesn't use the return value. Your use of the function may not match its intent. You can circumvent the warning by assigning the value to **`std::ignore`** or by casting it to **`void`** if discarding the value is intentional.  
-Assignment to **`std::ignore`** is preferred over casting to **`void`** in C++ 11 and higher, as it makes your intent clearer and will not trigger [Warning C26457](../../code-quality/c26457.md) if enabled in your code analysis settings.
+Assignment to **`std::ignore`** is preferred over casting to **`void`** in C++11 and higher, as it makes your intent clearer and will not trigger [Warning C26457](../../code-quality/c26457.md) if enabled in your code analysis settings.
 
 This warning was introduced in Visual Studio 2017 version 15.3 as a level 3 warning. It was changed to a level 1 warning in Visual Studio 2017 version 15.7. Code that compiled without warnings in versions of the compiler before Visual Studio 2017 version 15.3 can now generate C4834. For information on how to disable warnings introduced in a particular compiler version or later, see [Compiler warnings by compiler version](compiler-warnings-by-compiler-version.md).
 
@@ -52,7 +52,7 @@ int main()
 
     // If ignoring the [[nodiscard]] attribute value is intentional, you have two options:
     // Preferrably, assign the return value to std::ignore:
-    std::ignore = square_of(42); // Ok, C++ 11 and higher
+    std::ignore = square_of(42); // Ok, C++11 and higher
     // Alternatively, you can cast the return value to void. 
     // The intent may be less clear to other developers.
     (void) square_of(42); // May produce warning C26457

docs/standard-library/ambiguous-local-time.md

@@ -14,7 +14,7 @@ This exception is thrown when attempting to convert a `local_time` to a `sys_tim
 ## Syntax
 
 ```cpp
-class ambiguous_local_time : public runtime_error; // C++ 20
+class ambiguous_local_time : public runtime_error; // C++20
 ```
 
 ## Remarks
@@ -98,7 +98,7 @@ You typically won't create this exception. It's thrown by functions that convert
 Gets a string describing the details of the ambiguity.
 
 ```cpp
-[nodiscard] virtual const char* what() const noexcept;
+[[nodiscard]] virtual const char* what() const noexcept;
 ```
 
 ### Return value