Merging changes synced from https://github.com/MicrosoftDocs/cpp-docs-pr (branch live)

Author: opbld15

docs/c-runtime-library/c-run-time-library-reference.md

@@ -25,6 +25,9 @@ Provides links to the global variables and standard types provided by the run-ti
 [Global Constants](../c-runtime-library/global-constants.md)<br/>
 Provides links to the global constants defined by the run-time library.
 
+[Global State](../c-runtime-library/global-state.md)<br/>
+Describes the scope of global state in the C run-time library.
+
 [Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)<br/>
 Provides a table of contents entry point into an alphabetical listing of all C run-time library functions.
 

docs/c-runtime-library/cgets-cgetws.md

@@ -1,8 +1,8 @@
 ---
 title: "_cgets, _cgetws"
-ms.date: "11/04/2016"
-api_name: ["_cgetws", "_cgets"]
-api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr80.dll", "msvcr120.dll", "msvcr90.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_cgetws", "_cgets", "_o__cgets", "_o__cgetws"]
+api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr80.dll", "msvcr120.dll", "msvcr90.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["cgetws", "_cgetws", "_cgets"]
@@ -55,6 +55,8 @@ Because all editing keys are active when `_cgets` or `_cgetws` is called while i
 
 In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../c-runtime-library/secure-template-overloads.md).
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ### Generic-Text Routine Mappings
 
 |Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined|

docs/c-runtime-library/ciatan.md

@@ -1,8 +1,8 @@
 ---
 title: "_CIatan"
-ms.date: "11/04/2016"
-api_name: ["_CIatan"]
-api_location: ["msvcr120.dll", "msvcr110.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_CIatan", "_o__CIatan"]
+api_location: ["msvcr120.dll", "msvcr110.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["_CIatan", "CIatan"]
@@ -25,6 +25,8 @@ This version of the `atan` function has a specialized calling convention that th
 
 The resulting value is pushed onto the top of the stack.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 **Platform:** x86

docs/c-runtime-library/ciatan2.md

@@ -1,8 +1,8 @@
 ---
 title: "_CIatan2"
-ms.date: "11/04/2016"
-api_name: ["_CIatan2"]
-api_location: ["msvcr80.dll", "msvcrt.dll", "msvcr120.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr100.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_CIatan2", "_o__CIatan2"]
+api_location: ["msvcr80.dll", "msvcrt.dll", "msvcr120.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr100.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["CIatan2", "_CIatan2"]
@@ -25,6 +25,8 @@ This version of the `atan2` function has a specialized calling convention that t
 
 The resulting value is pushed onto the top of the stack.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 **Platform:** x86

docs/c-runtime-library/cicos.md

@@ -1,8 +1,8 @@
 ---
 title: "_CIcos"
-ms.date: "04/11/2018"
-api_name: ["_CIcos"]
-api_location: ["msvcr90.dll", "msvcrt.dll", "msvcr120.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_CIcos", "_o__CIcos"]
+api_location: ["msvcr90.dll", "msvcrt.dll", "msvcr120.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["CIcos", "_CIcos"]
@@ -25,6 +25,8 @@ This version of the [cos](../c-runtime-library/reference/cos-cosf-cosl.md) funct
 
 The resulting value is pushed onto the top of the floating-point stack.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 **Platform:** x86

docs/c-runtime-library/ciexp.md

@@ -1,8 +1,8 @@
 ---
 title: "_CIexp"
-ms.date: "11/04/2016"
-api_name: ["_CIexp"]
-api_location: ["msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_CIexp", "_o__CIexp"]
+api_location: ["msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["CIexp", "_CIexp"]
@@ -25,6 +25,8 @@ This version of the `exp` function has a specialized calling convention that the
 
 The resulting value is pushed onto the top of the stack.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 **Platform:** x86

docs/c-runtime-library/cifmod.md

@@ -1,8 +1,8 @@
 ---
 title: "_CIfmod"
-ms.date: "11/04/2016"
-api_name: ["_CIfmod"]
-api_location: ["msvcrt.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_CIfmod", "_o__CIfmod"]
+api_location: ["msvcrt.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["_CIfmod", "CIfmod"]
@@ -25,6 +25,8 @@ This version of the `fmod` function has a specialized calling convention that th
 
 The resulting value is pushed onto the top of the stack.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 **Platform:** x86

docs/c-runtime-library/cilog.md

@@ -1,8 +1,8 @@
 ---
 title: "_CIlog"
-ms.date: "11/04/2016"
-api_name: ["_CIlog"]
-api_location: ["msvcr90.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcrt.dll", "api-ms-win-crt-math-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_CIlog", "_o__CIlog"]
+api_location: ["msvcr90.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcrt.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["_CIlog", "CIlog"]
@@ -25,6 +25,8 @@ This version of the `log` function has a specialized calling convention that the
 
 The resulting value is pushed onto the top of the stack.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 **Platform:** x86

docs/c-runtime-library/cilog10.md

@@ -1,8 +1,8 @@
 ---
 title: "_CIlog10"
-ms.date: "11/04/2016"
-api_name: ["_CIlog10"]
-api_location: ["msvcr100.dll", "msvcr120.dll", "msvcr80.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_CIlog10", "_o__CIlog10"]
+api_location: ["msvcr100.dll", "msvcr120.dll", "msvcr80.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["CIlog10", "_CIlog10"]
@@ -25,6 +25,8 @@ This version of the `log10` function has a specialized calling convention that t
 
 The resulting value is pushed onto the top of the stack.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 **Platform:** x86

docs/c-runtime-library/cipow.md

@@ -1,8 +1,8 @@
 ---
 title: "_CIpow"
-ms.date: "11/04/2016"
-api_name: ["_CIpow"]
-api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_CIpow", "_o__CIpow"]
+api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["CIpow", "_CIpow"]
@@ -25,6 +25,8 @@ This version of the `pow` function has a specialized calling convention that the
 
 The resulting value is pushed onto the top of the stack.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 **Platform:** x86

docs/c-runtime-library/cisin.md

@@ -1,8 +1,8 @@
 ---
 title: "_CIsin"
-ms.date: "04/10/2018"
-api_name: ["_CIsin"]
-api_location: ["msvcr80.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110.dll", "msvcr120.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_CIsin", "_o__CIsin"]
+api_location: ["msvcr80.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110.dll", "msvcr120.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["CIsin", "_CIsin"]
@@ -25,6 +25,8 @@ This intrinsic version of the [sin](../c-runtime-library/reference/sin-sinf-sinl
 
 The resulting value is pushed onto the top of the floating-point stack.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 **Platform:** x86

docs/c-runtime-library/cisqrt.md

@@ -1,8 +1,8 @@
 ---
 title: "_CIsqrt"
-ms.date: "11/04/2016"
-api_name: ["_CIsqrt"]
-api_location: ["msvcr90.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcrt.dll", "msvcr110.dll", "msvcr100.dll", "api-ms-win-crt-math-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_CIsqrt", "_o__CIsqrt"]
+api_location: ["msvcr90.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcrt.dll", "msvcr110.dll", "msvcr100.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["_CIsqrt", "CIsqrt"]
@@ -25,6 +25,8 @@ This version of the `sqrt` function has a specialized calling convention that th
 
 The resulting value is pushed onto the top of the stack.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 **Platform:** x86

docs/c-runtime-library/citan.md

@@ -1,8 +1,8 @@
 ---
 title: "_CItan"
-ms.date: "04/11/2018"
-api_name: ["_CItan"]
-api_location: ["msvcr100.dll", "msvcr110_clr0400.dll", "msvcr80.dll", "msvcrt.dll", "msvcr110.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-math-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_CItan", "_o__CItan"]
+api_location: ["msvcr100.dll", "msvcr110_clr0400.dll", "msvcr80.dll", "msvcrt.dll", "msvcr110.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["_CItan", "CItan"]
@@ -25,6 +25,8 @@ This version of the [tan](../c-runtime-library/reference/tan-tanf-tanl.md) funct
 
 The resulting value is pushed onto the top of the floating-point stack.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 **Platform:** x86

docs/c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md

@@ -1,8 +1,8 @@
 ---
 title: "_execute_onexit_table, _initialize_onexit_table, _register_onexit_function"
-ms.date: "11/04/2016"
-api_name: ["_execute_onexit_table", "_initialize_onexit_table", "_register_onexit_function"]
-api_location: ["api-ms-win-crt-runtime-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_execute_onexit_table", "_initialize_onexit_table", "_register_onexit_function", "_o__execute_onexit_table", "_o__initialize_onexit_table", "_o__register_onexit_function"]
+api_location: ["api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["_execute_onexit_table", "process/_execute_onexit_table", "_initialize_onexit_table", "process/_initialize_onexit_table", "_register_onexit_function", "process/_register_onexit_function"]
@@ -52,6 +52,8 @@ The `_register_onexit_function` function appends a function to the end of the on
 
 The `_execute_onexit_table` function executes all of the functions in the onexit function table, clears the table, and then returns. After a call to `_execute_onexit_table`, the table is in a non-valid state; it must be reinitialized by a call to `_initialize_onexit_table` before it is used again.
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ## Requirements
 
 |Routine|Required header|

docs/c-runtime-library/gets-getws.md

@@ -1,8 +1,8 @@
 ---
 title: "gets, _getws"
-ms.date: "11/04/2016"
-api_name: ["_getws", "gets"]
-api_location: ["msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr100.dll", "api-ms-win-crt-stdio-l1-1-0.dll"]
+ms.date: "4/2/2020"
+api_name: ["_getws", "gets", "_o__getws", "_o_gets"]
+api_location: ["msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr100.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0"]
 api_type: ["DLLExport"]
 topic_type: ["apiref"]
 f1_keywords: ["_getts", "gets", "_getws"]
@@ -56,6 +56,8 @@ The `gets` function reads a line from the standard input stream `stdin` and stor
 
 In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../c-runtime-library/secure-template-overloads.md).
 
+By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md).
+
 ### Generic-Text Routine Mappings
 
 |TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined|

docs/c-runtime-library/global-state.md

@@ -0,0 +1,59 @@
+---
+title: "Global state in the CRT"
+ms.date: "04/02/2020"
+helpviewer_keywords: ["CRT global state"]
+---
+
+# Global state in the CRT
+
+Some functions in the Universal C Runtime (UCRT) use global state. For example, `setlocale()` sets the locale for the entire program, which affects the digit separators, text code page, and so on.
+
+The UCRT's global state is not shared between applications and the OS. For example, if your application calls `setlocale()`, it won't affect the locale for any OS components that uses the C run-time, or vice-versa.
+
+## OS-specific versions of CRT functions
+
+In the UCRT, functions that interact with global state have a "twin" function, prefixed with `_o_`. For example:
+
+    `setlocale()` affects global state specific to the app.
+    `_o_setlocale()` affects global state shared by all OS components, but not apps.
+
+The only difference between these "twin" functions is that when they read/write the global CRT state, the OS-specific versions (that is, the versions that start with `_o_`) use the OS copy of global state instead of the app's copy of global state.
+
+The OS-specific versions of these functions are in `ucrt.osmode.lib`. For example, the OS-specific version of `setlocale()` is `_o_setlocale()`
+
+There are two ways to isolate your component's CRT state from an app's CRT state:
+
+- Statically link your component by using compiler options /MT (release) or MTd (debug). For details, see [/MD, /MT, /LD](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library?view=vs-2019). Note that static linking can greatly increase binary size.
+- Starting with Windows 10 20H2, get CRT state isolation by dynamically linking to the CRT but call the OS-mode exports (the functions that begin with _o_). To call the OS-mode exports, statically link as before, but ignore the static UCRT by using linker option `/NODEFAULTLIB:libucrt.lib` (release) or `/NODEFAULTLIB:libucrtd.lib` (debug) See [/NODEFAULTLIB (Ignore Libraries)](https://docs.microsoft.com/cpp/build/reference/nodefaultlib-ignore-libraries?view=vs-2019) for details. And add `ucrt.osmode.lib` to the linker input.
+
+> [!Note]
+> In source code,  write `setlocale()`, not `_o_setlocale()`. When you link against `ucrt.osmode.lib`, the linker will automatically substitute the OS-specific version of the function. That is, `setlocale()` will be substituted with `_o_setlocale()`.
+
+Linking against `ucrt.osmode.lib` disables some UCRT calls that are only available in app mode. Attempting to call these will result in a link error.
+
+## Global state affected by app/OS separation
+
+Global state affected by the separation of app and OS state includes:
+
+- [Locale data](locale.md)
+- Signal handlers set by [signal](reference/signal.md)
+- Termination routines set by [terminate](reference/set-terminate-crt.md)
+- [errno and _doserrno](errno-doserrno-sys-errlist-and-sys-nerr.md)
+- Random number generation state used by [rand](reference/rand.md) and [srand](reference/srand.md)
+- Functions that return a buffer that the user doesn't need to release:
+    [strtok, wcstok, _mbstok](reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md)
+    [Tmpnam, _wtmpnam](reference/tempnam-wtempnam-tmpnam-wtmpnam.md)
+    [asctime, _wasctime](reference/asctime-wasctime.md)
+    [gmtime, _gmtime32, _gmtime64](reference/gmtime-gmtime32-gmtime64.md)
+    [_fcvt](reference/fcvt.md)
+    [_ecvt](reference/ecvt.md)
+    [strerror, _strerror, _wcserror, __wcserror](reference/strerror-strerror-wcserror-wcserror.md)
+- The buffer used by [_putch, _putwch](reference/putch-putwch.md)
+- [_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler](reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md)
+- [_set_new_handler](reference/set-new-handler.md) and [_set_new_mode](reference/set-new-mode.md)
+- [fmode] (text-and-binary-mode-file-i-o.md)
+- [Time zone information](time-management.md)
+
+## See also
+
+[C Run-Time library reference](c-run-time-library-reference.md)