Merge pull request MicrosoftDocs#3279 from MicrosoftDocs/master637636092850540086

Repo sync for protected CLA branch

Author: Colin Robertson

docs/c-runtime-library/crt-initialization.md

@@ -2,16 +2,18 @@
 title: "CRT Initialization"
 description: "Describes how the CRT initializes global state in native code."
 ms.topic: "conceptual"
-ms.date: "11/04/2016"
+ms.date: 08/02/2021
 helpviewer_keywords: ["CRT initialization [C++]"]
 ms.assetid: e7979813-1856-4848-9639-f29c86b74ad7
 ---
 # CRT Initialization
 
-This topic describes how the CRT initializes global state in native code.
+This article describes how the CRT initializes global state in native code.
 
 By default, the linker includes the CRT library, which provides its own startup code. This startup code initializes the CRT library, calls global initializers, and then calls the user-provided `main` function for console applications.
 
+It's possible, though not recommended, to take advantage of Microsoft-specific linker behavior to insert your own global initializers in a specific order. This code isn't portable, and comes with some important caveats.
+
 ## Initializing a Global Object
 
 Consider the following code:
@@ -32,13 +34,13 @@ int main()
 
 According to the C/C++ standard, `func()` must be called before `main()` is executed. But who calls it?
 
-One way to determine the caller is to set a breakpoint in `func()`, debug the application, and examine the stack. This is possible because the CRT source code is included with Visual Studio.
+One way to determine the caller is to set a breakpoint in `func()`, debug the application, and examine the stack. It's possible because the CRT source code is included with Visual Studio.
 
 When you browse the functions on the stack, you'll see that the CRT is calling a list of function pointers. These functions are similar to `func()`, or constructors for class instances.
 
-The CRT gets the list of function pointers from the Microsoft C++ compiler. When the compiler sees a global initializer, it generates a dynamic initializer in the `.CRT$XCU` section where `CRT` is the section name and `XCU` is the group name. To get a list of dynamic initializers, run the command **dumpbin /all main.obj**, and then search the `.CRT$XCU` section. This applies when main.cpp is compiled as a C++ file, not a C file. It will be similar to the following example:
+The CRT gets the list of function pointers from the Microsoft C++ compiler. When the compiler sees a global initializer, it generates a dynamic initializer in the `.CRT$XCU` section where `CRT` is the section name and `XCU` is the group name. To get a list of dynamic initializers, run the command **`dumpbin /all main.obj`**, and then search the `.CRT$XCU` section. The command only applies when *`main.cpp`* is compiled as a C++ file, not a C file. It should be similar to this example:
 
-```
+```cmd
 SECTION HEADER #6
 .CRT$XCU name
        0 physical address
@@ -72,11 +74,11 @@ The CRT defines two pointers:
 
 Neither group has any other symbols defined except `__xc_a` and `__xc_z`.
 
-Now, when the linker reads various `.CRT` groups, it combines them in one section and orders them alphabetically. This means that the user-defined global initializers (which the Microsoft C++ compiler puts in `.CRT$XCU`) will always come after `.CRT$XCA` and before `.CRT$XCZ`.
+Now, when the linker reads various `.CRT` subsections (the part after the `$`), it combines them in one section and orders them alphabetically. It means that the user-defined global initializers (which the Microsoft C++ compiler puts in `.CRT$XCU`) always come after `.CRT$XCA` and before `.CRT$XCZ`.
 
-The section will resemble the following example:
+The section should resemble this example:
 
-```
+```asm
 .CRT$XCA
             __xc_a
 .CRT$XCU
@@ -88,6 +90,26 @@ The section will resemble the following example:
 
 So, the CRT library uses both `__xc_a` and `__xc_z` to determine the start and end of the global initializers list because of the way in which they're laid out in memory after the image is loaded.
 
+## Linker features for initialization
+
+The C++ Standard doesn't provide a conforming way to specify relative order across translation units for a user-supplied global initializer. However, since the Microsoft linker orders the `.CRT` subsections alphabetically, it's possible to take advantage of this ordering to specify initialization order. We don't recommend this Microsoft-specific technique, and it may break in a future release. We've documented it only to keep you from creating code that's broken in hard-to-diagnose ways.
+
+To help prevent issues in your code, starting in Visual Studio 2019 version 16.11, we've added two new off by default warnings: [C5247](../error-messages/compiler-warnings/c5247.md) and [C5248](../error-messages/compiler-warnings/c5248.md). Enable these warnings to detect problems when creating your own initializers.
+
+You can add initializers to unused reserved section names to create them in a specific relative order to the compiler generated dynamic initializers:
+
+```cpp
+#pragma section(".CRT$XCT", read)
+// 'i1' is guaranteed to be called before any compiler generated C++ dynamic initializer
+__declspec(allocate(".CRT$XCT")) type i1 = f;
+
+#pragma section(".CRT$XCV", read)
+// 'i2' is guaranteed to be called after any compiler generated C++ dynamic initializer
+__declspec(allocate(".CRT$XCV")) type i2 = f;
+```
+
+The names `.CRT$XCT` and `.CRT$XCV` aren't used by either the compiler or the CRT library right now, but there's no guarantee that they'll remain unused in the future. And, your variables could still be optimized away by the compiler. Consider the potential engineering, maintenance, and portability issues before adopting this technique.
+
 ## See also
 
 [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md)

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

@@ -0,0 +1,50 @@
+---
+title: "Compiler Warning C5247"
+description: Compiler warning C5247 description and solution.
+ms.date: 08/02/2021
+f1_keywords: ["C5247"]
+helpviewer_keywords: ["C5247"]
+---
+# Compiler Warning C5247
+
+> section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior
+
+## Remarks
+
+The Microsoft C++ compiler uses reserved section names for internal implementation of features such as C++ dynamic initialization. If your code creates a section with the same name as a reserved section, such as `.CRT$XCU`, it interferes with the compiler. It may prevent other dynamic initialization and cause undefined behavior.
+
+To resolve this error, don't create a section that uses the reserved name.
+
+There's no C++ standard conforming way to initialize variables across translation units, in a specific relative order with compiler generated dynamic initializers. Ways to force initialization before or after compiler generated C++ dynamic initializers are implementation-specific. For more information on Microsoft-specific implementation details, see [CRT initialization](../../c-runtime-library/crt-initialization.md).
+
+Compiler Warning C5247 is new in Visual Studio 2019 version 16.11. It's off by default. For more information on how to enable this warning, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md).
+
+## Example
+
+Code that tries to emulate the C++ compiler behavior for dynamic initialization often takes this form:
+
+```cpp
+void f();
+typedef void (*type)();
+
+#pragma section(".CRT$XCU", read)
+__declspec(allocate(".CRT$XCU")) type i = f;
+```
+
+This code creates a section using a reserved name, `.CRT$XCU`. It stops the compiler from creating the section with the expected properties, and it may skip other initializations. The variable `i` placed in the section is a regular variable, and isn't considered an initializer by the compiler. The compiler may optimize `i` away. The relative order when `f` gets called compared to other dynamic initializers is unspecified.
+
+If initialization order isn't important, you can use this pattern to dynamically initialize a variable at startup:
+
+```cpp
+void f();
+
+struct init_helper {
+    init_helper() { f(); }
+};
+
+init_helper i;
+```
+
+## See also
+
+[CRT initialization](../../c-runtime-library/crt-initialization.md)

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

@@ -0,0 +1,50 @@
+---
+title: "Compiler Warning C5248"
+description: Compiler warning C5248 description and solution.
+ms.date: 08/02/2021
+f1_keywords: ["C5248"]
+helpviewer_keywords: ["C5248"]
+---
+# Compiler Warning C5248
+
+> section '*section-name*' is reserved for C++ dynamic initialization. Variables manually put into the section may be optimized out and their order relative to compiler generated dynamic initializers is unspecified
+
+## Remarks
+
+The Microsoft C++ compiler uses reserved section names for internal implementation of features such as C++ dynamic initialization. If your code inserts a variable in a reserved section, such as `.CRT$XCU`, it interferes with the compiler. Your variable isn't considered a C++ dynamic initializer. Also, its relative initialization order compared to compiler generated dynamic initializers isn't specified.
+
+To resolve this error, don't create a section that uses the reserved name or insert a variable in the reserved section.
+
+There's no C++ standard conforming way to initialize variables across translation units, in a specific relative order with compiler generated dynamic initializers. Ways to force initialization before or after compiler generated C++ dynamic initializers are implementation-specific. For more information on Microsoft-specific implementation details, see [CRT initialization](../../c-runtime-library/crt-initialization.md).
+
+Compiler Warning C5248 is new in Visual Studio 2019 version 16.11. It's off by default. For more information on how to enable this warning, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md).
+
+## Example
+
+Code that tries to emulate the C++ compiler behavior for dynamic initialization often takes this form:
+
+```cpp
+void f();
+typedef void (*type)();
+
+#pragma section(".CRT$XCU", read)
+__declspec(allocate(".CRT$XCU")) type i = f;
+```
+
+This code creates a section using a reserved name, `.CRT$XCU`. It stops the compiler from creating the section with the expected properties, and it may skip other initializations. The variable `i` placed in the section is a regular variable, and isn't considered an initializer by the compiler. The compiler may optimize `i` away. The relative order when `f` gets called compared to other dynamic initializers is unspecified.
+
+If initialization order isn't important, you can use this pattern to dynamically initialize a variable at startup:
+
+```cpp
+void f();
+
+struct init_helper {
+    init_helper() { f(); }
+};
+
+init_helper i;
+```
+
+## See also
+
+[CRT initialization](../../c-runtime-library/crt-initialization.md)

docs/error-messages/compiler-warnings/compiler-warnings-c4800-through-c4999.md

@@ -2,8 +2,8 @@
 title: "Compiler warnings C4800 Through C5999"
 description: "Table of Microsoft C/C++ compiler warnings C4800 through C5999."
 ms.date: 06/11/2021
-f1_keywords: ["C4808", "C4809", "C4825", "C4827", "C4837", "C4842", "C4844", "C4845", "C4846", "C4847", "C4848", "C4854", "C4855", "C4856", "C4857", "C4872", "C4880", "C4881", "C4882", "C4916", "C4921", "C4934", "C4954", "C4955", "C4963", "C4966", "C4970", "C4971", "C4973", "C4974", "C4981", "C4987", "C4988", "C4989", "C4990", "C4991", "C4992", "C4998", "C5022", "C5023", "C5024", "C5025", "C5026", "C5027", "C5028", "C5029", "C5030", "C5031", "C5032", "C5033", "C5034", "C5035", "C5036", "C5039", "C5040", "C5041", "C5042", "C5043", "C5044", "C5047", "C5048", "C5049", "C5051", "C5052", "C5053", "C5054", "C5055", "C5056", "C5057", "C5058", "C5059", "C5060", "C5061", "C5062", "C5063", "C5100", "C5101", "C5102", "C5103", "C5104", "C5106", "C5107", "C5108", "C5200", "C5201", "C5202", "C5203", "C5204", "C5205", "C5206", "C5207", "C5209", "C5210", "C5211", "C5212", "C5213", "C5214", "C5215", "C5216", "C5217", "C5218", "C5219", "C5220", "C5221", "C5222", "C5223", "C5224", "C5225", "C5226", "C5227", "C5228", "C5229", "C5230", "C5231", "C5232", "C5233", "C5234", "C5235", "C5236", "C5237", "C5238", "C5239", "C5240", "C5241", "C5242", "C5243", "C5244", "C5245", "C5246", "C5247", "C5248"]
-helpviewer_keywords: ["C4808", "C4809", "C4825", "C4827", "C4837", "C4842", "C4844", "C4845", "C4846", "C4847", "C4848", "C4854", "C4855", "C4856", "C4857", "C4872", "C4880", "C4881", "C4882", "C4916", "C4921", "C4934", "C4954", "C4955", "C4963", "C4966", "C4970", "C4971", "C4973", "C4974", "C4981", "C4987", "C4988", "C4989", "C4990", "C4991", "C4992", "C4998", "C5022", "C5023", "C5024", "C5025", "C5026", "C5027", "C5028", "C5029", "C5030", "C5031", "C5032", "C5033", "C5034", "C5035", "C5036", "C5039", "C5040", "C5041", "C5042", "C5043", "C5044", "C5047", "C5048", "C5049", "C5051", "C5052", "C5053", "C5054", "C5055", "C5056", "C5057", "C5058", "C5059", "C5060", "C5061", "C5062", "C5063", "C5100", "C5101", "C5102", "C5103", "C5104", "C5106", "C5107", "C5108", "C5200", "C5201", "C5202", "C5203", "C5204", "C5205", "C5206", "C5207", "C5209", "C5210", "C5211", "C5212", "C5213", "C5214", "C5215", "C5216", "C5217", "C5218", "C5219", "C5220", "C5221", "C5222", "C5223", "C5224", "C5225", "C5226", "C5227", "C5228", "C5229", "C5230", "C5231", "C5232", "C5233", "C5234", "C5235", "C5236", "C5237", "C5238", "C5239", "C5240", "C5241", "C5242", "C5243", "C5244", "C5245", "C5246", "C5247", "C5248"]
+f1_keywords: ["C4808", "C4809", "C4825", "C4827", "C4837", "C4842", "C4844", "C4845", "C4846", "C4847", "C4848", "C4854", "C4855", "C4856", "C4857", "C4872", "C4880", "C4881", "C4882", "C4916", "C4921", "C4934", "C4954", "C4955", "C4963", "C4966", "C4970", "C4971", "C4973", "C4974", "C4981", "C4987", "C4988", "C4989", "C4990", "C4991", "C4992", "C4998", "C5022", "C5023", "C5024", "C5025", "C5026", "C5027", "C5028", "C5029", "C5030", "C5031", "C5032", "C5033", "C5034", "C5035", "C5036", "C5039", "C5040", "C5041", "C5042", "C5043", "C5044", "C5047", "C5048", "C5049", "C5051", "C5052", "C5053", "C5054", "C5055", "C5056", "C5057", "C5058", "C5059", "C5060", "C5061", "C5062", "C5063", "C5100", "C5101", "C5102", "C5103", "C5104", "C5106", "C5107", "C5108", "C5200", "C5201", "C5202", "C5203", "C5204", "C5205", "C5206", "C5207", "C5209", "C5210", "C5211", "C5212", "C5213", "C5214", "C5215", "C5216", "C5217", "C5218", "C5219", "C5220", "C5221", "C5222", "C5223", "C5224", "C5225", "C5226", "C5227", "C5228", "C5229", "C5230", "C5231", "C5232", "C5233", "C5234", "C5235", "C5236", "C5237", "C5238", "C5239", "C5240", "C5241", "C5242", "C5243", "C5244", "C5245", "C5246"]
+helpviewer_keywords: ["C4808", "C4809", "C4825", "C4827", "C4837", "C4842", "C4844", "C4845", "C4846", "C4847", "C4848", "C4854", "C4855", "C4856", "C4857", "C4872", "C4880", "C4881", "C4882", "C4916", "C4921", "C4934", "C4954", "C4955", "C4963", "C4966", "C4970", "C4971", "C4973", "C4974", "C4981", "C4987", "C4988", "C4989", "C4990", "C4991", "C4992", "C4998", "C5022", "C5023", "C5024", "C5025", "C5026", "C5027", "C5028", "C5029", "C5030", "C5031", "C5032", "C5033", "C5034", "C5035", "C5036", "C5039", "C5040", "C5041", "C5042", "C5043", "C5044", "C5047", "C5048", "C5049", "C5051", "C5052", "C5053", "C5054", "C5055", "C5056", "C5057", "C5058", "C5059", "C5060", "C5061", "C5062", "C5063", "C5100", "C5101", "C5102", "C5103", "C5104", "C5106", "C5107", "C5108", "C5200", "C5201", "C5202", "C5203", "C5204", "C5205", "C5206", "C5207", "C5209", "C5210", "C5211", "C5212", "C5213", "C5214", "C5215", "C5216", "C5217", "C5218", "C5219", "C5220", "C5221", "C5222", "C5223", "C5224", "C5225", "C5226", "C5227", "C5228", "C5229", "C5230", "C5231", "C5232", "C5233", "C5234", "C5235", "C5236", "C5237", "C5238", "C5239", "C5240", "C5241", "C5242", "C5243", "C5244", "C5245", "C5246"]
 ---
 # Compiler warnings C4800 through C5999
 
@@ -227,8 +227,8 @@ The articles in this section of the documentation explain a subset of the warnin
 | Compiler warning (level 1) C5244 | '#include \<*filename*>' in the purview of module '*module-name-1*' appears erroneous.  Consider moving that directive before the module declaration, or replace the textual inclusion with 'import \<*module-name-2*>;'. |
 | Compiler warning (level 4) C5245 | '*function*': unreferenced function with internal linkage has been removed |
 | Compiler warning (level 1) C5246 | '*member*': the initialization of a subobject should be wrapped in braces |
-| Compiler warning (level 1) C5247 | section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior |
-| Compiler warning (level 1) C5248 | section '*section-name*' is reserved for C++ dynamic initialization. Variables manually put into the section may be optimized out and their order relative to compiler generated dynamic initializers is unspecified |
+| [Compiler warning (level 1) C5247](c5247.md) | section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior |
+| [Compiler warning (level 1) C5248](c5248.md) | section '*section-name*' is reserved for C++ dynamic initialization. Variables manually put into the section may be optimized out and their order relative to compiler generated dynamic initializers is unspecified |
 
 ## See also
 

docs/error-messages/toc.yml

@@ -4296,6 +4296,10 @@
           href: compiler-warnings/c5105.md
         - name: Compiler warning (level 1) C5208
           href: compiler-warnings/c5208.md
+        - name: Compiler warning (level 1) C5247
+          href: compiler-warnings/c5247.md
+        - name: Compiler warning (level 1) C5248
+          href: compiler-warnings/c5248.md
 - name: Compiler warnings by compiler version
   href: compiler-warnings/compiler-warnings-by-compiler-version.md
 - name: Compiler warnings that are off by default

docs/preprocessor/compiler-warnings-that-are-off-by-default.md

@@ -156,8 +156,8 @@ The following warnings are turned off by default in Visual Studio 2015 and later
 | C5243 (level 1) | '*type-name*': using incomplete class '*class-name*' can cause potential one definition rule violation due to ABI limitation <sup>16.10</sup> |
 | C5245 (level 4) | '*function*': unreferenced function with internal linkage has been removed |
 | C5246 (level 1) | '*member*': the initialization of a subobject should be wrapped in braces <sup>16.10</sup> |
-| C5247 (level 1) | Section '*section-name*' is reserved for C++ dynamic initialization.<br/> Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior <sup>16.11</sup> |
-| C5248 (level 1) | Section '*section-name*' is reserved for C++ dynamic initialization.<br/> Variable manually put into the section may be optimized out and its order relative to compiler generated dynamic<br/> initializers is unspecified <sup>16.11</sup> |
+| [C5247 (level 1)](../error-messages/compiler-warnings/c5247.md) | Section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior <sup>16.11</sup> |
+| [C5248 (level 1)](../error-messages/compiler-warnings/c5248.md) | Section '*section-name*' is reserved for C++ dynamic initialization. Variable manually put into the section may be optimized out and its order relative to compiler generated dynamic initializers is unspecified <sup>16.11</sup> |
 
 <sup>14.1</sup> This warning is available starting in Visual Studio 2015 Update 1.\
 <sup>14.3</sup> This warning is available starting in Visual Studio 2015 Update 3.\