4/8/2022 AM Publish (#4212)

* Update open-wopen.md

Clarify that _O_TEMPORARY sets FILE_SHARE_DELETE.

* Update other pages that mention _O_TEMPORARY effects.

* Broken link fixed

* Broken link fixed

* Update virtual-functions.md

* Address cpp-docs 3780 3782 3790 3791 3805

* Attempt correction of table format

* Add documentation for compiler error C2956 and update error text (MicrosoftDocs#4176)

* Add documentation for compiler error C2956 and update error text

* Add TOC entry

* Update for grammar and my own comprehension.

Sometimes, you just get carried away. This version could use some simplification.

* Simplify.

Address remarks, attempt simplification.
Acrolinx all the things.

* More updates per review

Co-authored-by: Colin Robertson <corob@microsoft.com>

* Address cpp-docs 3816

* Address non-blocking issues from 4207

* fix for sample program.

Co-authored-by: Steve Wishnousky <stwish@microsoft.com>
Co-authored-by: atikmapari <31974726+atikmapari@users.noreply.github.com>
Co-authored-by: Colin Robertson <corob@microsoft.com>
Co-authored-by: PRMerger19 <prmrgr19@microsoft.com>
Co-authored-by: Ming Ho <94572161+homing1@users.noreply.github.com>
Co-authored-by: PRMerger5 <prmergr5@microsoft.com>
Co-authored-by: Regan Downer <97987445+v-regandowner@users.noreply.github.com>
Co-authored-by: Jonathan Emmett <joemmett@microsoft.com>
Co-authored-by: Tamara K <93546702+tamarakhader@users.noreply.github.com>
Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com>
Co-authored-by: PRMerger17 <prmrgr17@microsoft.com>

Author: 12 people

docs/build/arm64-exception-handling.md

@@ -11,39 +11,41 @@ Windows on ARM64 uses the same structured exception handling mechanism for async
 
 The exception unwinding data conventions, and this description, are intended to:
 
-1. Provide enough description to allow unwinding without code probing in all cases.
+- Provide enough description to allow unwinding without code probing in all cases.
 
-   - Analyzing the code requires the code to be paged in. It prevents unwinding in some circumstances where it's useful (tracing, sampling, debugging).
+  - Analyzing the code requires the code to be paged in. It prevents unwinding in some circumstances where it's useful (tracing, sampling, debugging).
 
-   - Analyzing the code is complex; the compiler must be careful to only generate instructions that the unwinder can decode.
 
-   - If unwinding can't be fully described by using unwind codes, then in some cases it must fall back to instruction decoding. Instruction decoding increases the overall complexity, and ideally should be avoided.
+  - Analyzing the code is complex; the compiler must be careful to only generate instructions that the unwinder can decode.
 
-1. Support unwinding in mid-prolog and mid-epilog.
+  - If unwinding can't be fully described by using unwind codes, then in some cases it must fall back to instruction decoding. Instruction decoding increases the overall complexity, and ideally should be avoided.
 
-   - Unwinding is used in Windows for more than exception handling. It's critical that code can unwind accurately even when in the middle of a prolog or epilog code sequence.
 
-1. Take up a minimal amount of space.
+- Support unwinding in mid-prolog and mid-epilog.
 
-   - The unwind codes must not aggregate to significantly increase the binary size.
+  - Unwinding is used in Windows for more than exception handling. It's critical that code can unwind accurately even when in the middle of a prolog or epilog code sequence.
 
-   - Since the unwind codes are likely to be locked in memory, a small footprint ensures a minimal overhead for each loaded binary.
+- Take up a minimal amount of space.
+
+  - The unwind codes must not aggregate to significantly increase the binary size.
+
+  - Since the unwind codes are likely to be locked in memory, a small footprint ensures a minimal overhead for each loaded binary.
 
 ## Assumptions
 
 These assumptions are made in the exception handling description:
 
-1. Prologs and epilogs tend to mirror each other. By taking advantage of this common trait, the size of the metadata needed to describe unwinding can be greatly reduced. Within the body of the function, it doesn't matter whether the prolog's operations are undone, or the epilog's operations are done in a forward manner. Both should produce identical results.
+- Prologs and epilogs tend to mirror each other. By taking advantage of this common trait, the size of the metadata needed to describe unwinding can be greatly reduced. Within the body of the function, it doesn't matter whether the prolog's operations are undone, or the epilog's operations are done in a forward manner. Both should produce identical results.
 
-1. Functions tend on the whole to be relatively small. Several optimizations for space rely on this fact to achieve the most efficient packing of data.
+- Functions tend on the whole to be relatively small. Several optimizations for space rely on this fact to achieve the most efficient packing of data.
 
-1. There's no conditional code in epilogs.
+- There's no conditional code in epilogs.
 
-1. Dedicated frame pointer register: If the sp is saved in another register (x29) in the prolog, that register remains untouched throughout the function. It means the original sp may be recovered at any time.
+- Dedicated frame pointer register: If the sp is saved in another register (x29) in the prolog, that register remains untouched throughout the function. It means the original sp may be recovered at any time.
 
-1. Unless the sp is saved in another register, all manipulation of the stack pointer occurs strictly within the prolog and epilog.
+- Unless the sp is saved in another register, all manipulation of the stack pointer occurs strictly within the prolog and epilog.
 
-1. The stack frame layout is organized as described in the next section.
+- The stack frame layout is organized as described in the next section.
 
 ## ARM64 stack frame layout
 
@@ -275,11 +277,13 @@ The array of unwind codes is a pool of sequences that describe exactly how to un
 
 If exceptions were guaranteed to only ever occur within a function body, and never within a prolog or any epilog, then only a single sequence would be necessary. However, the Windows unwinding model requires that code can unwind from within a partially executed prolog or epilog. To meet this requirement, the unwind codes have been carefully designed so they unambiguously map 1:1 to each relevant opcode in the prolog and epilog. This design has several implications:
 
-1. By counting the number of unwind codes, it's possible to compute the length of the prolog and epilog.
 
-1. By counting the number of instructions past the start of an epilog scope, it's possible to skip the equivalent number of unwind codes. We can execute the rest of a sequence to complete the partially executed unwind done by the epilog.
+- By counting the number of unwind codes, it's possible to compute the length of the prolog and epilog.
+
+- By counting the number of instructions past the start of an epilog scope, it's possible to skip the equivalent number of unwind codes. We can execute the rest of a sequence to complete the partially executed unwind done by the epilog.
+
+- By counting the number of instructions before the end of the prolog, it's possible to skip the equivalent number of unwind codes. We can execute the rest of the sequence to undo only those parts of the prolog that have completed execution.
 
-1. By counting the number of instructions before the end of the prolog, it's possible to skip the equivalent number of unwind codes. We can execute the rest of the sequence to undo only those parts of the prolog that have completed execution.
 
 The unwind codes are encoded according to the table below. All unwind codes are a single/double byte, except the one that allocates a huge stack. There are 21 unwind codes in total. Each unwind code maps exactly one instruction in the prolog/epilog, to allow for unwinding of partially executed prologs and epilogs.
 
@@ -365,7 +369,7 @@ Step 4: Save input arguments in the home parameter area.
 
 Step 5: Allocate remaining stack, including local area, \<x29,lr> pair, and outgoing parameter area. 5a  corresponds to canonical type 1. 5b and 5c are for canonical type 2. 5d and 5e are for both type 3 and type 4.
 
-| Step # | Flag values | # of instructions | Opcode | Unwind Code |
+| Step # | Flag values | # of instructions | Opcode | Unwind code |
 |--|--|--|--|--|
 | 0 |  |  | `#intsz = RegI * 8;`<br/>`if (CR==01) #intsz += 8; // lr`<br/>`#fpsz = RegF * 8;`<br/>`if(RegF) #fpsz += 8;`<br/>`#savsz=((#intsz+#fpsz+8*8*H)+0xf)&~0xf)`<br/>`#locsz = #famsz - #savsz` |
 | 1 | 0 < **RegI** <= 10 | **RegI** / 2 +<br/> **RegI** % 2 | `stp x19,x20,[sp,#savsz]!`<br/>`stp x21,x22,[sp,#16]`<br/>`...` | `save_regp_x`<br/>`save_regp`<br/>`...` |
@@ -624,5 +628,5 @@ Epilog Start Index [4] points to the middle of Prolog unwind code (partially reu
 
 ## See also
 
-[Overview of ARM64 ABI conventions](arm64-windows-abi-conventions.md)<br/>
-[ARM Exception Handling](arm-exception-handling.md)
+[Overview of ARM64 ABI conventions](arm64-windows-abi-conventions.md)\
+[ARM exception handling](arm-exception-handling.md)

docs/c-language/c-operators.md

@@ -1,15 +1,17 @@
 ---
-description: "Learn more about: C Operators"
-title: "C Operators"
-ms.date: "06/14/2018"
+description: "Learn more about: C operators"
+title: "C operators"
+ms.date: 04/07/2022
 helpviewer_keywords: ["ternary operators", "operators [C]", "symbols, operators", "binary operators", "associativity of operators", "binary data, binary expressions"]
 ms.assetid: 13bc4c8e-2dc9-4b23-9f3a-25064e8777ed
 ---
-# C Operators
+# C operators
 
 The C operators are a subset of the [C++ built-in operators](../cpp/cpp-built-in-operators-precedence-and-associativity.md).
 
-There are three types of operators. A unary expression consists of either a unary operator followed by an operand, or the **`sizeof`** keyword followed by an expression. The expression can be either the name of a variable or a cast expression. If the expression is a cast expression, it must be enclosed in parentheses. A binary expression consists of two operands joined by a binary operator. A ternary expression consists of three operands joined by the conditional-expression operator.
+
+There are three types of operators. A unary expression consists of either a unary operator followed by an operand, or the **`sizeof`** or **`_Alignof`** keyword followed by an expression. The expression can be either the name of a variable or a cast expression. If the expression is a cast expression, it must be enclosed in parentheses. A binary expression consists of two operands joined by a binary operator. A ternary expression consists of three operands joined by the conditional-expression operator.
+
 
 C includes the following unary operators:
 

docs/c-runtime-library/reference/open-wopen.md

@@ -72,7 +72,7 @@ The **`_open`** function opens the file specified by *`filename`* and prepares i
 | **`_O_BINARY`** | Opens the file in binary (untranslated) mode. (See [`fopen`](fopen-wfopen.md) for a description of binary mode.) |
 | **`_O_CREAT`** | Creates a file and opens it for writing. Has no effect if the file specified by *filename* exists. The *pmode* argument is required when **`_O_CREAT`** is specified. |
 | **`_O_CREAT`** | **`_O_SHORT_LIVED`** | Creates a file as temporary and if possible does not flush to disk. The *pmode* argument is required when **`_O_CREAT`** is specified. |
-| **`_O_CREAT`** | **`_O_TEMPORARY`** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *pmode* argument is required when **`_O_CREAT`** is specified. |
+| **`_O_CREAT`** | **`_O_TEMPORARY`** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *pmode* argument is required when **`_O_CREAT`** is specified. To preserve legacy behavior for app-compatibility, other processes are not prevented from deleting this file. |
 | **`_O_CREAT`** | `_O_EXCL` | Returns an error value if a file specified by *filename* exists. Applies only when used with **`_O_CREAT`**. |
 | **`_O_NOINHERIT`** | Prevents creation of a shared file descriptor. |
 | **`_O_RANDOM`** | Specifies that caching is optimized for, but not restricted to, random access from disk. |

docs/c-runtime-library/reference/sopen-s-wsopen-s.md

@@ -88,7 +88,7 @@ The integer expression *oflag* is formed by combining one or more manifest const
 | **`_O_BINARY`** | Opens the file in binary (untranslated) mode. (See [`fopen`](fopen-wfopen.md) for a description of binary mode.) |
 | **`_O_CREAT`** | Creates a file and opens it for writing. Has no effect if the file specified by *`filename`* exists. The *`pmode`* argument is required when **`_O_CREAT`** is specified. |
 | **`_O_CREAT`** | **`_O_SHORT_LIVED`** | Creates a file as temporary and if possible does not flush to disk. The *`pmode`* argument is required when **`_O_CREAT`** is specified. |
-| **`_O_CREAT`** | **`_O_TEMPORARY`** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *`pmode`* argument is required when **`_O_CREAT`** is specified. |
+| **`_O_CREAT`** | **`_O_TEMPORARY`** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *`pmode`* argument is required when **`_O_CREAT`** is specified. To preserve legacy behavior for app-compatibility, other processes are not prevented from deleting this file. |
 | **`_O_CREAT`** | `_O_EXCL` | Returns an error value if a file specified by *`filename`* exists. Applies only when used with **`_O_CREAT`**. |
 | **`_O_NOINHERIT`** | Prevents creation of a shared file descriptor. |
 | **`_O_RANDOM`** | Specifies that caching is optimized for, but not restricted to, random access from disk. |

docs/c-runtime-library/reference/sopen-wsopen.md

@@ -81,7 +81,7 @@ The integer expression *oflag* is formed by combining one or more of the followi
 | **_O_BINARY** | Opens the file in binary (untranslated) mode. (See [fopen](fopen-wfopen.md) for a description of binary mode.) |
 | **_O_CREAT** | Creates a file and opens it for writing. Has no effect if the file specified by *filename* exists. The *pmode* argument is required when **_O_CREAT** is specified. |
 | **_O_CREAT** | **_O_SHORT_LIVED** | Creates a file as temporary and if possible does not flush to disk. The *pmode* argument is required when **_O_CREAT** is specified. |
-| **_O_CREAT** | **_O_TEMPORARY** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *pmode* argument is required when **_O_CREAT** is specified. |
+| **_O_CREAT** | **_O_TEMPORARY** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *pmode* argument is required when **_O_CREAT** is specified. To preserve legacy behavior for app-compatibility, other processes are not prevented from deleting this file. |
 | **_O_CREAT** | `_O_EXCL` | Returns an error value if a file specified by *filename* exists. Applies only when used with **_O_CREAT**. |
 | **_O_NOINHERIT** | Prevents creation of a shared file descriptor. |
 | **_O_RANDOM** | Specifies that caching is optimized for, but not restricted to, random access from disk. |

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

@@ -0,0 +1,62 @@
+---
+description: "Learn more about: Compiler Error C2956"
+title: "Compiler Error C2956"
+ms.date: 04/05/2022
+f1_keywords: ["C2956"]
+helpviewer_keywords: ["C2956"]
+---
+# Compiler Error C2956
+
+> usual deallocation function '*function*' would be chosen as placement deallocation function
+
+The deallocation function found for the placement new expression matches one of the usual deallocation functions. Either an implicit compiler-generated deallocation or an explicit `delete` (or `delete[]`) would use the wrong deallocation function.
+
+## Remarks
+
+Error C2956 indicates you used a *placement new expression* (a `new` expression that takes parameters) in a way that can cause a memory leak or runtime crash. It usually means the resulting value can't be deleted in a typical way. That is, either an explicit `delete` (or `delete[]`) expression in your code, or the implicit deallocation when a constructor throws an exception, could invoke the wrong `operator delete` or supply it with the wrong parameters.
+
+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:
+
+```cpp
+#include <new>
+struct T {
+    void* operator new(std::size_t, std::size_t); // Placement allocation function
+    void operator delete(void*, std::size_t); // now considered a usual deallocation function
+};
+
+T* p = new (0) T;   // error: usual deallocation function would be chosen as placement deallocation function
+```
+
+If your intent is to specify over-aligned memory for an object, you can instead specify the alignment directly on the type by using `alignas`. For more information about `alignas`, see [Alignment](../../cpp/alignment-cpp-declarations.md).
+
+If your intent is to specify over-aligned memory for a heap-allocated native type or an array, wrap it in a `struct` or `class` that has the `alignas` specifier. Then normal `new` and `delete` expressions can allocate and deallocate instances that have your intended alignment.
+
+## Example
+
+In this example, the *`new-expression`* uses placement syntax with an argument of type `std::align_val_t`. However, since type `T` doesn't specify an alignment requirement, a *`delete-expression`* on a `T*` won't invoke a matching over-aligned deallocation function. Instead, the compiler would invoke the usual deallocation function `void operator delete(void* ptr) noexcept`, which doesn't handle an over-aligned allocation. Rather than cause a crash or a memory leak, the compiler reports an error for this use of placement `new`:
+
+```cpp
+#include <new>
+struct T {};
+
+int main()
+{
+    T* p = new (std::align_val_t{64}) T; // C2956
+    delete p; // ordinary, not over-aligned delete
+}
+```
+
+To resolve this issue, apply an `alignas` specifier to `T`:
+
+```cpp
+#include <new>
+struct alignas(64) T {};
+
+int main()
+{
+    T* p = new T; // invokes ::operator new(std::size_t, std::align_val_t)
+    delete p; // now invokes ::operator delete(void*, std::align_val_t)
+}
+```

docs/error-messages/compiler-errors-2/compiler-errors-c2900-through-c3499.md

@@ -72,7 +72,7 @@ The articles in this section of the documentation explain a subset of the error
 |[Compiler error C2953](compiler-error-c2953.md)|'*type*': class template has already been defined|
 |Compiler error C2954|instruction word argument not in range|
 |[Compiler error C2955](compiler-error-c2955.md)|'*type*': use of class template/generic requires template/generic argument list|
-|Compiler error C2956|sized deallocation function 'operator delete(void*, size_t)' would be chosen as placement deallocation function.|
+|[Compiler error C2956](compiler-error-c2956.md)|usual deallocation function '*function*' would be chosen as placement deallocation function|
 |[Compiler error C2957](compiler-error-c2957.md)|'*token*': invalid left delimiter: expected '<'|
 |[Compiler error C2958](compiler-error-c2958.md)|the left *delimiter* found at '*file*(*line_number*)' was not matched correctly|
 |[Compiler error C2959](compiler-error-c2959.md)|a generic class or function may not be a member of a template|

docs/error-messages/toc.yml

@@ -1915,6 +1915,8 @@ items:
           href: compiler-errors-2/compiler-error-c2953.md
         - name: Compiler error C2955
           href: compiler-errors-2/compiler-error-c2955.md
+        - name: Compiler error C2956
+          href: compiler-errors-2/compiler-error-c2956.md
         - name: Compiler error C2957
           href: compiler-errors-2/compiler-error-c2957.md
         - name: Compiler error C2958