Merge pull request #6081 from MicrosoftDocs/main

Auto Publish – main to live - 2025-09-09 17:30 UTC

Author: learn-build-service-prod[bot]

docs/build-insights/tutorials/build-insights-function-view.md

@@ -45,15 +45,15 @@ Set the optimization level to maximum optimizations:
 
 1. In the **Solution Explorer**, right-click the project name and select **Properties**.
 1. In the project properties, navigate to **C/C++** > **Optimization**.
-1. Set the **Optimization** dropdown to **Maximum Optimization (Favor Speed) ([`/O2`](../../build/reference/ob-inline-function-expansion.md))**.
+1. Set the **Optimization** dropdown to **Maximum Optimization (Favor Speed) ([`/O2`](../../build/reference/o1-o2-minimize-size-maximize-speed.md))**.
 
     :::image type="content" source="./media/max-optimization-setting.png" alt-text="Screenshot of the project property pages dialog. The settings are open to Configuration Properties > C/C++ > Optimization. The Optimization dropdown is set to Maximum Optimization (Favor Speed) (/O2).":::
 
 1. Click **OK** to close the dialog.
 
 ## Run Build Insights
 
-On a project of your choosing, and using the **Release** build options set in the previous section, run Build Insights by choosing from the main menu **Build** > **Run Build Insights on Selection** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. Choose **Rebuild** instead of **Build** to measure the build time for the entire project and not for just the few files may be dirty right now.
+On a project of your choosing, and using the **Release** build options set in the previous section, run Build Insights by choosing from the main menu **Build** > **Run Build Insights on Selection** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. Choose **Rebuild** instead of **Build** to measure the build time for the entire project and not for just the few files that may be dirty right now.
 
 :::image type="content" source="./media/build-insights-rebuild-project.png" alt-text="Screenshot of the main menu with Run Build Insights on Selection > Rebuild selected.":::
 
@@ -69,9 +69,9 @@ In the Function Name column, performPhysicsCalculations() is highlighted and mar
 
 The **Time [sec, %]** column shows how long it took to compile each function in [wall clock responsibility time (WCTR)](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/#:~:text=Today%2C%20we%E2%80%99d%20like%20to%20teach%20you%20about%20a,your%20build%2C%20even%20in%20the%20presence%20of%20parallelism). This metric distributes the wall clock time among functions based on their use of parallel compiler threads. For example, if two different threads are compiling two different functions simultaneously within a one-second period, each function's WCTR is recorded as 0.5 seconds. This reflects each function's proportional share of the total compilation time, taking into account the resources each consumed during parallel execution. Thus, WCTR provides a better measure of the impact each function has on the overall build time in environments where multiple compilation activities occur simultaneously.
 
-The **Forceinline Size** column shows roughly how many instructions were generated for the function. Click the chevron before the function name to see the individual inlined functions that were expanded in that function how roughly how many instructions were generated for each.
+The **Forceinline Size** column shows roughly how many instructions were generated for the function. Click the chevron before the function name to see the individual inlined functions that were expanded in that function and roughly how many instructions were generated for each.
 
-You can sort the list by clicking on the **Time** column to see which functions are taking the most time to compile. A 'fire' icon indicates that cost of generating that function is high and is worth investigating. Excessive use of `__forceinline` functions can significantly slow compilation.
+You can sort the list by clicking on the **Time** column to see which functions are taking the most time to compile. A 'fire' icon indicates that the cost of generating that function is high and is worth investigating. Excessive use of `__forceinline` functions can significantly slow compilation.
 
 You can search for a specific function by using the **Filter Functions** box. If a function's code generation time is too small, it doesn't appear in the **Functions** View.
 
@@ -89,7 +89,7 @@ By selecting the chevron before that function, and then sorting the **Forceinlin
 performPhysicsCalculations() is expanded and shows a long list of functions that were inlined inside it. There are multiple instances of functions such as complexOperation(), recursiveHelper(), and sin() shown. The Forceinline Size column shows that complexOperation() is the largest inlined function at 315 instructions. recursiveHelper() has 119 instructions. Sin() has 75 instructions, but there are many more instances of it than the other functions.
 :::image-end:::
 
-There are some larger inlined functions, such as `Vector2D<float>::complexOperation()` and `Vector2D<float>::recursiveHelper()` that are contributing to the problem. But there are many more instances (not all shown here) of `Vector2d<float>::sin(float)`, `Vector2d<float>::cos(float)`, `Vector2D<float>::power(float,int)`, and `Vector2D<float>::factorial(int)`. When you add those up, the total number of generated instructions quickly exceeds the few larger generated functions.
+There are some larger inlined functions, such as `Vector2D<float>::complexOperation()` and `Vector2D<float>::recursiveHelper()` that are contributing to the problem. But there are many more instances (not all shown here) of `Vector2D<float>::sin(float)`, `Vector2D<float>::cos(float)`, `Vector2D<float>::power(float,int)`, and `Vector2D<float>::factorial(int)`. When you add those up, the total number of generated instructions quickly exceeds the few larger generated functions.
 
 Looking at those functions in the source code, we see that execution time is going to be spent inside loops. For example, here's the code for `factorial()`:
 
@@ -108,15 +108,15 @@ static __forceinline T factorial(int n)
 
 Perhaps the overall cost of calling this function is insignificant compared to the cost of the function itself. Making a function inline is most beneficial when the time it takes to call the function (pushing arguments on the stack, jumping to the function, popping return arguments, and returning from the function) is roughly similar to the time it takes to execute the function, and when the function is called a lot. When that's not the case, there may be diminishing returns on making it inline. We can try removing the `__forceinline` directive from it to see if it helps the build time. The code for `power`, `sin()`, and `cos()` is similar in that the code consists of a loop that executes many times. We can try removing the `__forceinline` directive from those functions as well.
 
-We rerun Build Insights from the main menu by choosing **Build** > **Run Build Insights on Selection** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. We choose **Rebuild** instead of **Build** to measure the build time for the entire project, as before, and not for just the few files may be dirty right now.
+We rerun Build Insights from the main menu by choosing **Build** > **Run Build Insights on Selection** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. We choose **Rebuild** instead of **Build** to measure the build time for the entire project, as before, and not for just the few files that may be dirty right now.
 
 The build time goes from 25.181 seconds to 13.376 seconds and the `performPhysicsCalculations` function doesn't show up anymore in the **Functions** view because it doesn't contribute enough to the build time to be counted.
 
 :::image type="complex" source="./media/functions-view-after-fix.png" alt-text="Screenshot of the 2D vector header file.":::
 In the Function Name column, performPhysicsCalculations() is highlighted and marked with a fire icon.
 :::image-end:::
 
-The Diagnostics Session time is the overall time it took do the build plus any overhead for gathering the Build Insights data.
+The Diagnostics Session time is the overall time it took to do the build plus any overhead for gathering the Build Insights data.
 
 The next step would be to profile the application to see if the performance of the application is negatively impacted by the change. If it is, we can selectively add `__forceinline` back as needed.
 

docs/build/arm64-windows-abi-conventions.md

@@ -1,6 +1,6 @@
 ---
-description: "Learn more about: Overview of ARM64 ABI conventions"
 title: "Overview of ARM64 ABI conventions"
+description: "Learn more about: Overview of ARM64 ABI conventions"
 ms.date: 04/08/2025
 ---
 # Overview of ARM64 ABI conventions
@@ -123,7 +123,7 @@ To determine if an ARM CPU supports exceptions, write a value that enables excep
 
 On ARM64, Windows delivers exceptions for processors that support hardware floating-point exceptions.
 
-The [`_set_controlfp`](/cpp/c-runtime-library/reference/controlfp-s) function on ARM platforms correctly changes the FPCR register when unmasking floating-point exceptions. However, instead of raising an unmasked exception, Windows resets the FPCR register to its defaults every time an FP exception is about to be raised.
+The [`_set_controlfp`](../c-runtime-library/reference/controlfp-s.md) function on ARM platforms correctly changes the FPCR register when unmasking floating-point exceptions. However, instead of raising an unmasked exception, Windows resets the FPCR register to its defaults every time an FP exception is about to be raised.
 
 ## Parameter passing
 

docs/c-runtime-library/crt-debugging-techniques.md

@@ -16,7 +16,7 @@ When you debug a program that uses the C run-time library, these debugging techn
 
 ## CRT debug library use
 
-The C runtime (CRT) library provides extensive debugging support. To use one of the CRT debug libraries, you must link with [`/DEBUG`](/cpp/build/reference/debug-generate-debug-info) and compile with [`/MDd`, `/MTd`, or `/LDd`](../build/reference/md-mt-ld-use-run-time-library.md).
+The C runtime (CRT) library provides extensive debugging support. To use one of the CRT debug libraries, you must link with [`/DEBUG`](../build/reference/debug-generate-debug-info.md) and compile with [`/MDd`, `/MTd`, or `/LDd`](../build/reference/md-mt-ld-use-run-time-library.md).
 
 The main definitions and macros for CRT debugging can be found in the `<crtdbg.h>` header file.
 

docs/c-runtime-library/using-generic-text-mappings.md

@@ -1,17 +1,16 @@
 ---
 title: "Using Generic-Text Mappings"
 description: "An introduction to Microsoft-specific mappings for data types, routines, and other objects in the C runtime."
+ms.date: 11/04/2016
 ms.topic: "concept-article"
-ms.date: "11/04/2016"
 f1_keywords: ["_UNICODE"]
 helpviewer_keywords: ["_TXCHAR type", "TINT type", "_TCHAR type", "TSCHAR type", "TEXT type", "TCHAR type", "TCHAR.H data types, mappings defined in", "generic-text data types", "_TINT type", "TUCHAR type", "_UNICODE constant", "TXCHAR type", "generic-text mappings", "_TSCHAR type", "T type", "mappings, generic-text", "_TUCHAR type", "MBCS data type", "_MBCS data type", "_TEXT type", "UNICODE constant", "_T type"]
-ms.assetid: 2848121c-e51f-4b9b-a2e6-833ece4b0cb3
 ---
 # Using generic-text mappings
 
 **Microsoft Specific**
 
-To simplify code development for various international markets, the Microsoft run-time library provides Microsoft-specific "generic-text" mappings for many data types, routines, and other objects. These mappings are defined in TCHAR.H. You can use these name mappings to write generic code that can be compiled for any of the three kinds of character sets: ASCII (SBCS), MBCS, or Unicode, depending on a manifest constant you define using a `#define` statement. Generic-text mappings are Microsoft extensions that aren't ANSI compatible.
+To simplify code development for various international markets, the Microsoft run-time library provides Microsoft-specific "generic-text" mappings for many data types, routines, and other objects. These mappings are defined in `TCHAR.H`. You can use these name mappings to write generic code that can be compiled for any of the three kinds of character sets: ASCII (SBCS), MBCS, or Unicode, depending on a manifest constant you define using a `#define` statement. Generic-text mappings are Microsoft extensions that aren't ANSI compatible.
 
 ### Preprocessor directives for generic-text mappings
 
@@ -21,13 +20,13 @@ To simplify code development for various international markets, the Microsoft ru
 | `_MBCS` | Multibyte-character | `_tcsrev` maps to `_mbsrev` |
 | None (the default: both `_UNICODE` and `_MBCS` not defined) | SBCS (ASCII) | `_tcsrev` maps to `strrev` |
 
-For example, the generic-text function `_tcsrev`, defined in TCHAR.H, maps to `mbsrev` if `MBCS` has been defined in your program, or to `_wcsrev` if `_UNICODE` has been defined. Otherwise `_tcsrev` maps to `strrev`.
+For example, the generic-text function `_tcsrev`, defined in `TCHAR.H`, maps to `_mbsrev` if `_MBCS` has been defined in your program, or to `_wcsrev` if `_UNICODE` has been defined. Otherwise `_tcsrev` maps to `strrev`.
 
-The generic-text data type `_TCHAR`, also defined in TCHAR.H, maps to type **`char`** if `_MBCS` is defined, to type **`wchar_t`** if `_UNICODE` is defined, and to type **`char`** if neither constant is defined. Other data type mappings are provided in TCHAR.H for programming convenience, but `_TCHAR` is the type that is most useful.
+The generic-text data type `_TCHAR`, also defined in `TCHAR.H`, maps to type **`char`** if `_MBCS` is defined, to type **`wchar_t`** if `_UNICODE` is defined, and to type **`char`** if neither constant is defined. Other data type mappings are provided in `TCHAR.H` for programming convenience, but `_TCHAR` is the type that is most useful.
 
 ### Generic-Text Data Type Mappings
 
-| Generic-text data type name | SBCS (_UNICODE, _MBCS not defined) | _MBCS defined | _UNICODE defined |
+| Generic-text data type name | SBCS (`_UNICODE`, `_MBCS` not defined) | `_MBCS` defined | `_UNICODE` defined |
 |---|---|---|---|
 | `_TCHAR` | **`char`** | **`char`** | **`wchar_t`** |
 | `_TINT` | **`int`** | **`int`** | `wint_t` |
@@ -36,7 +35,7 @@ The generic-text data type `_TCHAR`, also defined in TCHAR.H, maps to type **`ch
 | `_TXCHAR` | **`char`** | **`unsigned char`** | **`wchar_t`** |
 | `_T` or `_TEXT` | No effect (removed by preprocessor) | No effect (removed by preprocessor) | `L` (converts following character or string to its Unicode counterpart) |
 
-For a complete list of generic-text mappings of routines, variables, and other objects, see [Generic-text mappings](./generic-text-mappings.md).
+For a complete list of generic-text mappings of routines, variables, and other objects, see [Generic-text mappings](generic-text-mappings.md).
 
 The following code fragments illustrate the use of `_TCHAR` and `_tcsrev` for mapping to the MBCS, Unicode, and SBCS models.
 
@@ -45,7 +44,7 @@ _TCHAR *RetVal, *szString;
 RetVal = _tcsrev(szString);
 ```
 
-If `MBCS` has been defined, the preprocessor maps the preceding fragment to the following code:
+If `_MBCS` has been defined, the preprocessor maps the preceding fragment to the following code:
 
 ```C
 char *RetVal, *szString;
@@ -72,8 +71,8 @@ These macros let you write, maintain, and compile a single source code file usin
 
 ## See also
 
-[Generic-text mappings](./generic-text-mappings.md)\
-[Data type mappings](./data-type-mappings.md)\
-[Constant and global variable mappings](./constant-and-global-variable-mappings.md)\
-[Routine mappings](./routine-mappings.md)\
-[A sample generic-text program](./a-sample-generic-text-program.md)
+[Generic-text mappings](generic-text-mappings.md)\
+[Data type mappings](data-type-mappings.md)\
+[Constant and global variable mappings](constant-and-global-variable-mappings.md)\
+[Routine mappings](routine-mappings.md)\
+[A sample generic-text program](a-sample-generic-text-program.md)

docs/code-quality/c6255.md

@@ -1,19 +1,18 @@
 ---
+title: "Warning C6255"
 description: "Learn more about: Warning C6255"
-title: Warning C6255
 ms.date: 11/04/2016
 f1_keywords: ["C6255", "UNPROTECTEDUSEOFALLOCA", "__WARNING_UNPROTECTEDUSEOFALLOCA"]
 helpviewer_keywords: ["C6255"]
-ms.assetid: bb6430b2-782a-4410-a8e1-609df06007de
 ---
 # Warning C6255
 
 > _alloca indicates failure by raising a stack overflow exception. Consider using _malloca instead
 
-This warning indicates that a call to `_alloca` has been detected outside of local exception handling.
-
 ## Remarks
 
+This warning indicates that a call to `_alloca` has been detected outside of local exception handling.
+
 `_alloca` should always be called from within the protected range of an exception handler because it can raise a stack overflow exception on failure. If possible, instead of using `_alloca`, consider using `_malloca`, which is a more secure version of `_alloca`.
 
 Code analysis name: `UNPROTECTEDUSEOFALLOCA`

docs/code-quality/c6258.md

@@ -1,19 +1,18 @@
 ---
+title: "Warning C6258"
 description: "Learn more about: Warning C6258"
-title: Warning C6258
 ms.date: 11/04/2016
 f1_keywords: ["C6258", "USINGTERMINATETHREAD", "__WARNING_USINGTERMINATETHREAD"]
 helpviewer_keywords: ["C6258"]
-ms.assetid: 62f3eed7-d9cd-46eb-8c38-0bc4f647941f
 ---
 # Warning C6258
 
 > Using `TerminateThread` does not allow proper thread clean up.
 
-This warning indicates that a call to `TerminateThread` has been detected.
-
 ## Remarks
 
+This warning indicates that a call to `TerminateThread` has been detected.
+
 `TerminateThread` is a dangerous function that should only be used in the most extreme cases. For more information about problems associated with TerminateThread call, see [`TerminateThread` function](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-terminatethread).
 
 Code analysis name: `USINGTERMINATETHREAD`

docs/code-quality/c6259.md

@@ -1,10 +1,9 @@
 ---
+title: "Warning C6259"
 description: "Learn more about: Warning C6259"
-title: Warning C6259
 ms.date: 11/04/2016
 f1_keywords: ["C6259", "DEADCODEINBITORLIMITEDSWITCH", "__WARNING_DEADCODEINBITORLIMITEDSWITCH"]
 helpviewer_keywords: ["C6259"]
-ms.assetid: a370bfd2-6634-402c-84c7-3d83fa0009b7
 ---
 # Warning C6259
 
@@ -18,7 +17,7 @@ Code analysis name: `DEADCODEINBITORLIMITEDSWITCH`
 
 ## Example
 
-The following sample code generates this warning because the 'switch' expression `(rand() & 3)` can't evaluate to case label (`case 4`):
+The following example code generates this warning because the 'switch' expression `(rand() & 3)` can't evaluate to case label (`case 4`):
 
 ```cpp
 #include <stdlib.h>

docs/code-quality/c6260.md

@@ -1,19 +1,18 @@
 ---
+title: "Warning C6260"
 description: "Learn more about: Warning C6260"
-title: Warning C6260
 ms.date: 11/04/2016
 f1_keywords: ["C6260", "USEOFBYTEAREA", "__WARNING_USEOFBYTEAREA"]
 helpviewer_keywords: ["C6260"]
-ms.assetid: 9cbedfcb-32b2-4fe4-99f7-a2d4a7f4422a
 ---
 # Warning C6260
 
 > `sizeof` * `sizeof` is almost always wrong, did you intend to use a character count or a byte count?
 
-This warning indicates that the results of two **`sizeof`** operations have been multiplied together.
-
 ## Remarks
 
+This warning indicates that the results of two **`sizeof`** operations have been multiplied together.
+
 The C/C++ **`sizeof`** operator returns the number of bytes of storage an object uses. It's typically incorrect to multiply it by another **`sizeof`** operation. Usually, you're interested in the number of bytes in an object or the number of elements in an array (for example, the number of wide-characters in an array).
 
 There's some unintuitive behavior associated with **`sizeof`** operator. For example, in C, `sizeof ('\0') == 4`, because a character is of an integral type. In C++, the type of a character literal is **`char`**, so `sizeof ('\0') == 1`. However, in both C and C++, the following relation is true:

docs/code-quality/c6262.md

@@ -1,5 +1,5 @@
 ---
-title: Warning C6262
+title: "Warning C6262"
 description: "Visual Studio C++ Code Analysis warning C6262 description and resolution."
 ms.date: 10/14/2020
 f1_keywords: ["C6262", "EXCESSIVESTACKUSAGE", "__WARNING_EXCESSIVESTACKUSAGE"]