draft changes

TylerMSFT · TylerMSFT · commit 65ea7664deee · 2026-04-10T13:41:31.000-07:00
diff --git a/docs/build/building-on-the-command-line.md b/docs/build/building-on-the-command-line.md
@@ -17,7 +17,7 @@ You can build C and C++ applications on the command line by using tools that are
 
 ::: moniker range=">=msvc-160"
 
-If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Desktop development with C++** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015, 2017, or 2019 toolsets, select the optional MSVC v140, v141, or v142 build tools. When you're satisfied with your selections, choose **Install**.
+If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/). On the downloads page, expand the **Tools for Visual Studio** section to find the Build Tools download. When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Desktop development with C++** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015, 2017, or 2019 toolsets, select the optional MSVC v140, v141, or v142 build tools. When you're satisfied with your selections, choose **Install**.
 
 ::: moniker-end
 ::: moniker range="<=msvc-150"
diff --git a/docs/build/reference/zf.md b/docs/build/reference/zf.md
@@ -19,7 +19,7 @@ The **/Zf** option enables compiler support for faster generation of PDB files w
 
 Because the **/Zf** option only applies to PDB generation, it requires the [/Zi](z7-zi-zi-debug-information-format.md) or [/ZI](z7-zi-zi-debug-information-format.md) option.
 
-The **/Zf** option is available beginning in Visual Studio 2017 version 15.1, where it is off by default. Starting in Visual Studio 2017 version 15.7, this option is on by default when the **/Zi** or **/ZI** option is enabled.
+The **/Zf** option is available beginning in Visual Studio 2017 version 15.1, where it is off by default. Starting in Visual Studio 2017 version 15.7, this option is on by default when the **/Zi** or **/ZI** option is enabled. To explicitly disable this option, use **/Zf-**.
 
 ### To set this compiler option in the Visual Studio development environment
 
diff --git a/docs/c-runtime-library/reference/calloc-dbg.md b/docs/c-runtime-library/reference/calloc-dbg.md
@@ -68,9 +68,9 @@ For information about how memory blocks are allocated, initialized, and managed
 
 ## Requirements
 
-| Routine | Required header |
-|---|---|
-| **`_calloc_dbg`** | \<crtdbg.h> |
+| Routine | Required header | Required library |
+|---|---|---|
+| **`_calloc_dbg`** | \<crtdbg.h> | The debug C Runtime Library (for example, `ucrtd.lib`). Only available in debug builds. See [CRT library features](../crt-library-features.md). |
 
 For more compatibility information, see [Compatibility](../compatibility.md).
 
diff --git a/docs/c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md b/docs/c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md
@@ -109,7 +109,7 @@ For more information, see [Format specification syntax: `printf` and `wprintf` f
 
 ## Return value
 
-The number of characters that which would have been written to the buffer if `count` was ignored. The count doesn't include the terminating `NULL` character.
+The number of characters that would have been written to the buffer if `count` was ignored. The count doesn't include the terminating `NULL` character.
 
 Let **`len`** be the length of the formatted data string, not including the terminating `NULL`.\
 For all functions, if `len < count`, then **`len`** characters are stored in *`buffer`*, a null-terminator is appended, and the number of characters written, not including the terminating `NULL`, is returned.
@@ -120,7 +120,12 @@ See [Behavior summary](#behavior-summary) for details.
 
 ## Remarks
 
-Beginning with the UCRT in Visual Studio 2015 and Windows 10, **`snprintf`** is no longer identical to **`_snprintf`**. The **`snprintf`** behavior is now C99 standard conformant. The difference is that if you run out of buffer, `snprintf` null-terminates the end of the buffer and returns the number of characters that would have been required whereas `_snprintf` doesn't null-terminate the buffer and returns -1. Also, `_snprintf()` includes one more character in the output because it doesn't null-terminate the buffer.
+Beginning with the UCRT in Visual Studio 2015 and Windows 10, **`snprintf`** is no longer identical to **`_snprintf`**. The **`snprintf`** behavior is now C99 standard conformant. The differences are:
+
+- **`snprintf`** always null-terminates the buffer (even when truncating), and returns the total number of characters that would have been written if the buffer were large enough (not counting the null-terminator).
+- **`_snprintf`** does **not** null-terminate the buffer when the output is truncated, and returns **-1** when truncation occurs.
+
+Because `_snprintf` doesn't write a null-terminator when it truncates, it can fit one more data character into the same buffer size. However, the resulting string is not null-terminated, so you must handle termination yourself.
 
 - **`snprintf`** and the **`_snprintf`** family of functions format and store *`count`* or fewer characters in *`buffer`*.
 - **`snprintf`** always stores a terminating `NULL` character, truncating the output if necessary.
diff --git a/docs/c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md b/docs/c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md
@@ -114,9 +114,9 @@ By default, this function's global state is scoped to the application. To change
 
 ## Requirements
 
-| Routine | Required header |
-|---|---|
-| **`wcstombs_s`** | `<stdlib.h>` |
+| Routine | Required header | Required library |
+|---|---|---|
+| **`wcstombs_s`** | `<stdlib.h>` | The Universal C Runtime Library (UCRT). Linked automatically when you build with the Visual C++ compiler. |
 
 For more compatibility information, see [Compatibility](../compatibility.md).
 
diff --git a/docs/code-quality/c6387.md b/docs/code-quality/c6387.md
@@ -13,11 +13,16 @@ helpviewer_keywords: ["C6387"]
 
 This warning is raised if an annotated function parameter is being passed an unexpected value. For example, passing a potentially null value to a parameter that is marked with `_In_` annotation generates this warning.
 
+This commonly happens when one function is annotated with `_Post_ _Null_` on its return value (meaning it may return null), and the result is then passed to another function that expects a non-null `_In_` parameter. To fix the issue, either change the first function's annotation to `_Post_ _Notnull_` if it truly never returns null, or add a null check before passing the value to the second function.
+
+> [!NOTE]
+> The SAL annotations (`_Post_ _Null_`, `_Post_ _Notnull_`, `_In_`, etc.) are used on function declarations to describe the contract of the function's parameters and return values. They do not apply to local variable declarations.
+
 Code analysis name: `INVALID_PARAM_VALUE_1`
 
 ## Example
 
-The following code generates this warning because a null parameter is passed to `f(char *)`:
+The following code generates this warning because the function `g` is annotated as potentially returning null (`_Post_ _Null_`), and the result is passed to `f`, which requires a non-null input (`_In_`):
 
 ```cpp
 #include <sal.h>
@@ -33,7 +38,7 @@ int main()
 }
 ```
 
-To correct this warning, use the following code:
+To correct this warning, you can change the annotation on `g` if it never actually returns null:
 
 ```cpp
 #include <sal.h>
@@ -49,6 +54,25 @@ int main()
 }
 ```
 
+Alternatively, you can add a null check before passing the value:
+
+```cpp
+#include <sal.h>
+
+_Post_ _Null_ char * g();
+
+void f(_In_ char *pch);
+
+int main()
+{
+    char *pCh = g();
+    if (pCh != nullptr)
+    {
+        f(pCh);
+    }
+}
+```
+
 ## See also
 
 [strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md)
diff --git a/docs/code-quality/how-to-set-code-analysis-properties-for-c-cpp-projects.md b/docs/code-quality/how-to-set-code-analysis-properties-for-c-cpp-projects.md
@@ -18,6 +18,9 @@ ms.assetid: 7af52097-6d44-4785-9b9f-43b7a7d447d7
 
 You can configure which rules the code analysis tool uses to analyze the code in each configuration of your project. In addition, you can direct code analysis to suppress warnings from code that was generated and added to your project by a third-party tool.
 
+> [!NOTE]
+> In recent versions of Visual Studio, the legacy **Code Analysis** property page in the project properties dialog may appear empty or show a deprecation notice. Use the individual settings described below to configure code analysis. For CMake projects, use `CMakeSettings.json` or `CMakePresets.json` instead.
+
 ## Code Analysis Property Page
 
 The **Code Analysis** property page contains all code analysis configuration settings for an MSBuild project. To open the code analysis property page for a project in **Solution Explorer**, right-click the project and then click **Properties**. Next, expand **Configuration Properties** and select the **Code Analysis** tab.
diff --git a/docs/cpp/abstract-classes-cpp.md b/docs/cpp/abstract-classes-cpp.md
@@ -31,13 +31,15 @@ The only difference between this declaration and the previous one is that `Print
 
 Abstract classes can't be used for:
 
-- Variables or member data
+- Variables or member data (you can't declare a variable of an abstract class type)
 
-- Argument types
+- Argument types (you can't pass an abstract class by value as a function parameter)
 
-- Function return types
+- Function return types (a function can't return an abstract class by value)
 
-- Types of explicit conversions
+- Types of explicit conversions (you can't cast to an abstract class type)
+
+In each case, you can use pointers or references to the abstract class type instead. For example, a function can take `AbstractBase&` or `AbstractBase*` as a parameter, and you can declare pointers or references of the abstract class type.
 
 If the constructor for an abstract class calls a pure virtual function, either directly or indirectly, the result is undefined. However, constructors and destructors for abstract classes can call other member functions.
 
diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1140.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1140.md
@@ -11,7 +11,9 @@ helpviewer_keywords: ["LNK1140"]
 
 ## Remarks
 
-The project contains more than 4096 modules.
+The project exceeds the maximum number of modules allowed in a program database (PDB) file. This limit was originally 4,096 modules and was later increased to 65,535.
+
+This error can also occur when other PDB size limits are exceeded, such as very large symbol tables or an excessive number of type records.
 
 ### To fix by using the following possible solutions
 
@@ -20,3 +22,5 @@ The project contains more than 4096 modules.
 1. Compile some modules without debugging information.
 
 1. Reduce the number of modules.
+
+1. Split your project into multiple smaller libraries or DLLs.
diff --git a/docs/error-messages/tool-errors/linker-tools-errors-and-warnings.md b/docs/error-messages/tool-errors/linker-tools-errors-and-warnings.md
@@ -25,6 +25,7 @@ The linker tools LINK, LIB, DUMPBIN, and EDITBIN share a common executable that
 | [Linker Tools Error LNK1120](linker-tools-error-lnk1120.md) | *number* unresolved externals |
 | [Linker Tools Error LNK1123](linker-tools-error-lnk1123.md) | failure during conversion to COFF: file invalid or corrupt |
 | [Linker Tools Error LNK1127](linker-tools-error-lnk1127.md) | library is corrupt |
+| Linker Tools Error LNK1131 | no library specified |
 | [Linker Tools Error LNK1136](linker-tools-error-lnk1136.md) | invalid or corrupt file |
 | [Linker Tools Error LNK1140](linker-tools-error-lnk1140.md) | too many modules for program database; link with /PDB:NONE |
 | [Linker Tools Error LNK1141](linker-tools-error-lnk1141.md) | failure during build of exports file |
diff --git a/docs/preprocessor/compiler-warnings-that-are-off-by-default.md b/docs/preprocessor/compiler-warnings-that-are-off-by-default.md
@@ -101,6 +101,7 @@ The following warnings are turned off by default in Visual Studio 2015 and later
 | [C4686](../error-messages/compiler-warnings/compiler-warning-level-3-c4686.md) (level 3) | '*user-defined type*': possible change in behavior, change in UDT return calling convention |
 | [C4692](../error-messages/compiler-warnings/compiler-warning-level-1-c4692.md) (level 1) | '*function*': signature of non-private member contains assembly private native type '*native_type*' |
 | [C4710](../error-messages/compiler-warnings/compiler-warning-level-4-c4710.md) (level 4) | '*function*': function not inlined |
+| [C4711](../error-messages/compiler-warnings/compiler-warning-level-1-c4711.md) (level 1) | function '*function*' selected for inline expansion |
 | [C4738](../error-messages/compiler-warnings/compiler-warning-level-3-c4738.md) (level 3) | storing 32-bit float result in memory, possible loss of performance |
 | [C4746](../error-messages/compiler-warnings/compiler-warning-c4746.md) | volatile access of '*expression*' is subject to /volatile:\<iso\|ms> setting; consider using __iso_volatile_load/store intrinsic functions |
 | C4749 (level 4) | conditionally supported: offsetof applied to non-standard-layout type '*type*' |
diff --git a/docs/standard-library/binary-function-struct.md b/docs/standard-library/binary-function-struct.md
@@ -13,6 +13,7 @@ An empty base struct that defines types that may be inherited by derived classes
 ## Syntax
 
 ```cpp
+template <class Arg1, class Arg2, class Result>
 struct binary_function {
    typedef Arg1 first_argument_type;
    typedef Arg2 second_argument_type;
diff --git a/docs/standard-library/identity-structure.md b/docs/standard-library/identity-structure.md
@@ -10,6 +10,9 @@ ms.assetid: 990756fd-7969-4b39-ad7e-0878e8dac8fd
 
 A struct that provides a type definition as the template parameter.
 
+> [!NOTE]
+> This Microsoft-specific `identity` structure from `<utility>` is deprecated and may not be available in all versions of Visual Studio. In C++20 and later, use `std::identity` from [`<functional>`](functional.md) instead, which is the standard-conforming equivalent.
+
 ## Syntax
 
 ```cpp
diff --git a/docs/standard-library/scoped-lock-class.md b/docs/standard-library/scoped-lock-class.md
@@ -6,6 +6,8 @@ f1_keywords: ["mutex/std::scoped_lock"]
 ---
 # scoped_lock Class
 
+The `scoped_lock` class is an RAII (Resource Acquisition Is Initialization) wrapper that acquires one or more mutexes on construction and releases them on destruction. When multiple mutexes are provided, they are locked using a deadlock-avoidance algorithm (equivalent to `std::lock`), which prevents deadlocks regardless of the order in which different threads lock the same set of mutexes. Introduced in C++17.
+
 ## Syntax
 
 ```cpp
@@ -19,3 +21,80 @@ class scoped_lock {
     scoped_lock& operator=(const scoped_lock&) = delete;
 };
 ```
+
+## Remarks
+
+The `scoped_lock` class manages locking and unlocking of one or more mutexes throughout a scope. When you create a `scoped_lock` object, it acquires ownership of the mutexes passed to it. When the `scoped_lock` object is destroyed (for example, when it goes out of scope), the mutexes are released. This ensures that mutexes are always properly released, even if an exception is thrown.
+
+If you need to lock only a single mutex, consider using [`lock_guard`](lock-guard-class.md) or [`unique_lock`](unique-lock-class.md). Use `scoped_lock` when you need to lock multiple mutexes simultaneously without risk of deadlock.
+
+### Constructors
+
+| Constructor | Description |
+|---|---|
+| `scoped_lock(MutexTypes&... m)` | Constructs a `scoped_lock` object and locks all the supplied mutexes. If multiple mutexes are supplied, they're locked using a deadlock-avoidance algorithm. |
+| `scoped_lock(MutexTypes&... m, adopt_lock_t)` | Constructs a `scoped_lock` object and adopts ownership of the supplied mutexes, which must already be locked by the calling thread. |
+
+### Destructor
+
+| Destructor | Description |
+|---|---|
+| `~scoped_lock()` | Destroys the `scoped_lock` object and releases all owned mutexes. |
+
+## Example
+
+```cpp
+#include <iostream>
+#include <mutex>
+#include <thread>
+#include <vector>
+
+std::mutex mutex1;
+std::mutex mutex2;
+int shared_data1 = 0;
+int shared_data2 = 0;
+
+void update_both(int iterations)
+{
+    for (int i = 0; i < iterations; ++i)
+    {
+        // Lock both mutexes simultaneously without risk of deadlock
+        std::scoped_lock lock(mutex1, mutex2);
+        ++shared_data1;
+        ++shared_data2;
+    }
+}
+
+int main()
+{
+    std::vector<std::thread> threads;
+    for (int i = 0; i < 4; ++i)
+    {
+        threads.emplace_back(update_both, 1000);
+    }
+
+    for (auto& t : threads)
+    {
+        t.join();
+    }
+
+    std::cout << "shared_data1: " << shared_data1 << '\n';
+    std::cout << "shared_data2: " << shared_data2 << '\n';
+    // Output:
+    // shared_data1: 4000
+    // shared_data2: 4000
+}
+```
+
+## Requirements
+
+**Header:** \<mutex>
+
+**Namespace:** std
+
+## See also
+
+[Header files reference](../standard-library/header-files-reference.md)\
+[`lock_guard` Class](lock-guard-class.md)\
+[`unique_lock` Class](unique-lock-class.md)\
+[`<mutex>`](mutex.md)
diff --git a/docs/windows/redistributing-visual-cpp-files.md b/docs/windows/redistributing-visual-cpp-files.md
@@ -68,7 +68,7 @@ The version number is stored in the `REG_SZ` string value `Version` and also in
 
 The Visual C++ Redistributable supports several command-line options. The `/?`, `/h`, or `/help` options display a dialog that lists the available options. You can specify `/install` to install, `/repair` to repair, or `/uninstall` to uninstall the Redistributable. The `/layout` option copies the complete contents of the Redistributable in the current directory.
 
-By default, the Redistributable installs its contents and prompts the user for information and whether to restart after installation. You can specify the `/passive` option, which displays progress but doesn't otherwise require user interaction. You can also specify a `/quiet` option, which doesn't display a user interface or require any user interaction. The `/norestart` option suppresses any attempts to restart. By default, a log file is created in `%TEMP%`. You can use `/log filename.txt` to log to a specific file.
+By default, the Redistributable installs its contents and prompts the user for information and whether to restart after installation. You can specify the `/passive` option, which displays a progress bar but doesn't otherwise require user interaction (however, a license acceptance dialog may still appear if the Redistributable hasn't been installed before). You can also specify a `/quiet` option, which doesn't display a user interface or require any user interaction, including no license dialog. Use `/quiet` for fully unattended installations. The `/norestart` option suppresses any attempts to restart. By default, a log file is created in `%TEMP%`. You can use `/log filename.txt` to log to a specific file.
 
 This example command installs the x64 Redistributable. It shows installation progress but doesn't require user interaction or a restart:
 
