Merge pull request #5118 from MicrosoftDocs/main

11/30/2023 AM Publish

Author: PhilKang0704

docs/code-quality/c26837.md

@@ -0,0 +1,143 @@
+---
+description: "Learn more about: Warning C26837"
+title: Warning C26837
+ms.date: 11/29/2023
+f1_keywords: ["C26837", "INTERLOCKED_COMPARE_EXCHANGE_MISUSE", "__WARNING_INTERLOCKED_COMPARE_EXCHANGE_MISUSE"]
+helpviewer_keywords: ["C26837"]
+---
+# Warning C26837
+
+> Value for the comparand `comp` for function `func` has been loaded from the destination location `dest` through non-volatile read.
+
+This rule was added in Visual Studio 2022 17.8.
+
+## Remarks
+
+The [`InterlockedCompareExchange`](/windows/win32/api/winnt/nf-winnt-interlockedcompareexchange) function, and its derivatives such as [`InterlockedCompareExchangePointer`](/windows/win32/api/winnt/nf-winnt-interlockedcompareexchangepointer), perform an atomic compare-and-exchange operation on the specified values. If the `Destination` value is equal to the `Comparand` value, the *exchange* value is stored in the address specified by `Destination`. Otherwise, no operation is performed. The `interlocked` functions provide a simple mechanism for synchronizing access to a variable that is shared by multiple threads. This function is atomic with respect to calls to other `interlocked` functions. Misuse of these functions can generate object code that behaves differently than you expect because optimization can change the behavior of the code in unexpected ways.
+
+Consider the following code:
+
+```cpp
+#include <Windows.h> 
+ 
+bool TryLock(__int64* plock) 
+{ 
+    __int64 lock = *plock; 
+    return (lock & 1) && 
+        _InterlockedCompareExchange64(plock, lock & ~1, lock) == lock; 
+} 
+```
+
+The intent of this code is:
+
+1. Read the current value from the `plock` pointer.
+1. Check if this current value has the least significant bit set.
+1. If it does have least significant bit set, clear the bit while preserving the other bits of the current value.
+
+To accomplish this, a copy of the current value is read from the`plock` pointer and saved to a stack variable `lock`. `lock` is used three times:
+
+1. First, to check if the least-significant bit is set.
+1. Second, as the `Comparand` value to `InterlockedCompareExchange64`.
+1. Finally, in the comparison of the return value from `InterlockedCompareExchange64`
+
+This assumes that the current value saved to the stack variable is read once at the start of the function and doesn't change. This is necessary because the current value is first checked before attempting the operation, then explicitly used as the `Comparand` in `InterlockedCompareExchange64`, and finally used to compare the return value from `InterlockedCompareExchange64`.
+
+Unfortunately, the previous code can be compiled into assembly that behaves differently than from what you expect from the source code. Compile the previous code with the Microsoft Visual C++ (MSVC) compiler and the [`/O1`](../build/reference/o1-o2-minimize-size-maximize-speed.md) option and inspect the resultant assembly code to see how the value of the lock for each of the references to `lock` is obtained. The MSVC compiler version v19.37 produces assembly code that looks like:
+
+```x86asm
+plock$ = 8 
+bool TryLock(__int64 *) PROC                          ; TryLock, COMDAT 
+        mov     r8b, 1 
+        test    BYTE PTR [rcx], r8b 
+        je      SHORT $LN3@TryLock 
+        mov     rdx, QWORD PTR [rcx] 
+        mov     rax, QWORD PTR [rcx] 
+        and     rdx, -2 
+        lock cmpxchg QWORD PTR [rcx], rdx 
+        je      SHORT $LN4@TryLock 
+$LN3@TryLock: 
+        xor     r8b, r8b 
+$LN4@TryLock: 
+        mov     al, r8b 
+        ret     0 
+bool TryLock(__int64 *) ENDP                          ; TryLock 
+```
+
+`rcx` holds the value of the parameter `plock`. Rather than make a copy of the current value on the stack, the assembly code is re-reading the value from `plock` every time. This means the value could be different each time it's read. This invalidates the sanitization that the developer is performing. The value is re-read from `plock` after it's verified that it has its least-significant bit set. Because it's re-read after this validation is performed, the new value might no longer have the least-significant bit set. Under a race condition, this code might behave as if it successfully obtained the specified lock when it was already locked by another thread.
+
+The compiler is allowed to remove or add memory reads or writes as long as the behavior of the code isn't altered. To prevent the compiler from making such changes, force reads to be `volatile` when you read the value from memory and cache it in a variable. Objects that are declared as `volatile` aren't used in certain optimizations because their values can change at any time. The generated code always reads the current value of a `volatile` object when it's requested, even if a previous instruction asked for a value from the same object. The reverse also applies for the same reason. The value of the `volatile` object isn't read again unless requested. For more information about `volatile`, see [`volatile`](..\cpp\volatile-cpp.md). For example:
+
+```cpp
+#include <Windows.h> 
+ 
+bool TryLock(__int64* plock) 
+{ 
+    __int64 lock = *static_cast<volatile __int64*>(plock); 
+    return (lock & 1) && 
+        _InterlockedCompareExchange64(plock, lock & ~1, lock) == lock; 
+}
+```
+
+Compile this code with same [`/O1`](../build/reference/o1-o2-minimize-size-maximize-speed.md) option as before. The generated assembly no longer reads `plock` for use of the cached value in `lock`.
+
+For more examples of how the code can be fixed, see [Example](#example).
+
+Code analysis name: `INTERLOCKED_COMPARE_EXCHANGE_MISUSE`
+
+## Example
+
+The compiler might optimize the following code to read `plock` multiple times instead of using the cached value in `lock`:
+
+```cpp
+#include <Windows.h> 
+ 
+bool TryLock(__int64* plock) 
+{ 
+    __int64 lock = *plock; 
+    return (lock & 1) && 
+        _InterlockedCompareExchange64(plock, lock & ~1, lock) == lock; 
+}
+```
+
+To fix the problem, force reads to be `volatile` so that the compiler doesn't optimize code to read successively from the same memory unless explicitly instructed. This prevents the optimizer from introducing unexpected behavior.
+
+The first method to treat memory as `volatile` is to take the destination address as `volatile` pointer:
+
+```cpp
+#include <Windows.h> 
+ 
+bool TryLock(volatile __int64* plock) 
+{ 
+    __int64 lock = *plock; 
+    return (lock & 1) && 
+        _InterlockedCompareExchange64(plock, lock & ~1, lock) == lock; 
+} 
+```
+
+The second method is using `volatile` read from the destination address. There are a few different ways to do this:
+
+- Casting the pointer to `volatile` pointer before dereferencing the pointer
+- Creating a `volatile` pointer from the provided pointer
+- Using `volatile` read helper functions.
+
+For example:
+
+```cpp
+#include <Windows.h> 
+ 
+bool TryLock(__int64* plock) 
+{ 
+    __int64 lock = ReadNoFence64(plock); 
+    return (lock & 1) && 
+        _InterlockedCompareExchange64(plock, lock & ~1, lock) == lock; 
+}
+```
+
+## Heuristics
+
+This rule is enforced by detecting if the value in the `Destination` of the `InterlockedCompareExchange` function, or any of its derivatives, is loaded through a non-`volatile` read, and then used as the `Comparand` value. However, it doesn't explicitly check if the loaded value is used to determine the *exchange* value. It assumes the *exchange* value is related to the `Comparand` value.
+
+## See also
+
+[`InterlockedCompareExchange` function (winnt.h)](/windows/win32/api/winnt/nf-winnt-interlockedcompareexchange)\
+[`_InterlockedCompareExchange` intrinsic functions](../intrinsics/interlockedcompareexchange-intrinsic-functions.md)

docs/code-quality/c26861.md

@@ -0,0 +1,69 @@
+---
+description: "Learn more about: Warning C26861"
+title: Warning C26861
+ms.date: 11/29/2023
+f1_keywords: ["C26861", "DATETIME_MANIPULATION_WITHOUT_LEAPYEAR_CHECK", "__WARNING_DATETIME_MANIPULATION_WITHOUT_LEAPYEAR_CHECK"]
+helpviewer_keywords: ["C26861"]
+---
+# Warning C26861
+
+> Field of a date-time object `var` has been modified without proper leap year checking: `expr`
+
+This rule was added in Visual Studio 2022 17.8.
+
+## Remarks
+
+In the Gregorian calendar, every year exactly divisible by four is a leap year--except for years that are exactly divisible by 100. The centurial years are also leap years if they're exactly divisible by 400.
+
+A leap year bug occurs when software doesn't account for this leap year logic, or uses flawed logic. The can affect reliability, availability, or even the security of the affected system.
+
+It isn't safe to add or subtract some number to or from the year, month, or day field of a date-time object without taking leap years into account. This calculation is commonly performed to determine the expiration date for a certificate, for example. On many dates, a naive calculation may produce the desired result. However, when the result is February 29 (a leap day) and the year isn't a leap year, the result is invalid.
+
+For example, adding a year to 2020-01-31 produces 2021-01-31. But adding a year to 2020-02-29 produces 2021-02-29, which isn't a valid date because 2021 isn't a leap year.
+
+Be cautious when manipulating variables that represent date values. Handle leap years and leap days properly, or use an API or library that handles date arithmetic safely.
+
+Code analysis name: `DATETIME_MANIPULATION_WITHOUT_LEAPYEAR_CHECK`
+
+## Example
+
+The following code advances the system time by a year by incrementing the year field of the date-time object representing the system time. However, it can produce an invalid date-time object if the date was February 29 before the modification, because the next year isn't a leap year:
+
+```cpp
+SYSTEMTIME st; 
+GetSystemTime(&st); 
+st.wYear++;  // warning C26861 
+```
+
+To avoid creating an invalid date-time object due to a leap year, check if the resulting date is still valid and make the necessary adjustments to make it valid, as in this example:
+
+```cpp
+SYSTEMTIME st; 
+GetSystemTime(&st); 
+st.wYear++; 
+if (st.wMonth == 2 && st.wDay == 29) 
+{ 
+    // move back a day when landing on Feb 29 in a non-leap year 
+    bool isLeapYear = st.wYear % 4 == 0 && (st.wYear % 100 != 0 || st.wYear % 400 == 0); 
+    if (!isLeapYear) 
+    { 
+        st.wDay = 28; 
+    } 
+}
+```
+
+## Heuristics
+
+Currently, this rule only recognizes the Windows `SYSTEMTIME` struct and C `tm` struct.
+
+This rule employs a simplified heuristic to find potentially risky changes and reports warnings unless there's appropriate leap year or leap day checking. It doesn't try to verify if the leap year or leap day checking is performed correctly for the modified date-time object.
+
+This rule is an opt-in rule, which means that code analysis should use a ruleset file, and the rule should be explicitly included in the ruleset file, and enabled for it to be applied. For more information on creating a custom ruleset for code analysis, see: [Use Rule Sets to Specify the `C++` Rules to Run](using-rule-sets-to-specify-the-cpp-rules-to-run.md).
+
+## See also
+
+[C6393](c6393.md)\
+[C6394](c6394.md)\
+[C26862](c26862.md)\
+[C26863](c26863.md)\
+[C26864](c26864.md)

docs/code-quality/c26862.md

@@ -0,0 +1,64 @@
+---
+description: "Learn more about: Warning C26862"
+title: Warning C26862
+ms.date: 11/29/2023
+f1_keywords: ["C26862", "INCOMPLETE_DATETIME_CONVERSION", "__WARNING_INCOMPLETE_DATETIME_CONVERSION"]
+helpviewer_keywords: ["C26862"]
+---
+# Warning C26862
+
+> A date-time object `var` has been created from a different type of date-time object but conversion was incomplete: `expr`
+
+This rule was added in Visual Studio 2022 17.8.
+
+## Remarks
+
+Proper enforcement of leap year and leap day handling rules require tracking the proper conversion between date-time objects of different types such as the Windows `SYSTEMTIME` struct and the C `tm` struct. Different date-time types may have different bases for the year, month, and day fields. For example, `SYSTEMTIME` has a 0-based year, but 1-based month and day fields. On the other hand, `tm` has a 1900-based year, a 0-based month, and a 1-based day fields. To convert an object of one of these types to an object of another type, the year, month, and day fields must be adjusted appropriately.
+
+Code analysis name: `INCOMPLETE_DATETIME_CONVERSION`
+
+## Example
+
+The following code tries to convert an instance of `tm` into an instance of `SYSTEMTIME`. It makes the necessary adjustment to the year field, but doesn't properly adjust the month field:
+
+```cpp
+#include <Windows.h>
+#include <ctime>
+  
+void ConvertTmToSystemTime1b(const tm& tm) 
+{ 
+    SYSTEMTIME st; 
+    st.wYear = tm.tm_year + 1900; 
+    st.wMonth = tm.tm_mon; // C26862, Adjustment is missing 
+    st.wDay = tm.tm_mday; 
+} 
+```
+
+To fix this problem, adjust the month and year fields:
+
+```cpp
+#include <Windows.h> 
+#include <ctime> 
+  
+void ConvertTmToSystemTime(const tm& tm) 
+{ 
+    SYSTEMTIME st; 
+    st.wYear = tm.tm_year + 1900; 
+    st.wMonth = tm.tm_mon + 1; 
+    st.wDay = tm.tm_mday; 
+} 
+```
+
+## Heuristics
+
+This rule only recognizes the Windows `SYSTEMTIME` struct and the C `tm` struct.
+
+This rule is an opt-in rule, meaning that code analysis should use a ruleset file, and the rule should be explicitly included in the ruleset file, and enabled for it to be applied. For more information on creating a custom ruleset for code analysis, see [Use Rule Sets to Specify the `C++` Rules to Run](using-rule-sets-to-specify-the-cpp-rules-to-run.md).
+
+## See also
+
+[C6393](c6393.md)\
+[C6394](c6394.md)\
+[C26861](c26861.md)\
+[C26863](c26863.md)\
+[C26864](c26864.md)

docs/code-quality/c26863.md

@@ -0,0 +1,83 @@
+---
+description: "Learn more about: Warning C26863"
+title: Warning C26863
+ms.date: 11/29/2023
+f1_keywords: ["C26863", "DATETIME_MANIPULATION_FUNCTION_RETURN_IGNORED", "__WARNING_DATETIME_MANIPULATION_FUNCTION_RETURN_IGNORED"]
+helpviewer_keywords: ["C26863"]
+---
+# Warning C26863
+
+> Return value from a date-time handling function `func` is ignored
+
+This rule was added in Visual Studio 2022 17.8.
+
+## Remarks
+
+It's important to verify the return value of a function that transforms a date structure when the year, month, or date input argument was manipulated without proper leap year handling. Otherwise, the function may have failed and execution continues with an output parameter containing invalid data.
+
+The following is a list of the functions that this warning covers:
+
+- [`FileTimeToSystemTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-filetimetosystemtime)
+- [`SystemTimeToFileTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-systemtimetofiletime)
+- [`SystemTimeToTzSpecificLocalTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-systemtimetotzspecificlocaltime)
+- [`SystemTimeToTzSpecificLocalTimeEx`](/windows/win32/api/timezoneapi/nf-timezoneapi-systemtimetotzspecificlocaltimeex)
+- [`TzSpecificLocalTimeToSystemTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtime)
+- [`TzSpecificLocalTimeToSystemTimeEx`](/windows/win32/api/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtimeex)
+- [`RtlLocalTimeToSystemTime`](/windows/win32/api/winternl/nf-winternl-rtllocaltimetosystemtime)
+- [`RtlTimeToSecondsSince1970`](/windows/win32/api/winternl/nf-winternl-rtltimetosecondssince1970)
+
+Code analysis name: `DATETIME_MANIPULATION_FUNCTION_RETURN_IGNORED`
+
+## Example
+
+The following code tries to get current system time, advance the month field by one month, and get the file time that corresponds to the updated system time via [`SystemTimeToFileTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-systemtimetofiletime). However, [`SystemTimeToFileTime`](/windows/win32/api/timezoneapi/nf-timezoneapi-systemtimetofiletime) might fail, as the updated system time may become invalid:
+
+```cpp
+#include <Windows.h> 
+ 
+void foo() 
+{ 
+    FILETIME ft; 
+    SYSTEMTIME st; 
+    GetSystemTime(&st); 
+    st.wMonth++; // Advance month by one 
+    // Get the file time 
+    SystemTimeToFileTime(&st, &ft);    // C26863 
+}
+```
+
+To fix the problem, always check the return value from date-time manipulation functions and handle failures appropriately:
+
+```cpp
+#include <Windows.h> 
+  
+void foo() 
+{ 
+    FILETIME ft; 
+    SYSTEMTIME st; 
+    GetSystemTime(&st); 
+    
+    st.wMonth++; // Advance month by one 
+    // Get file time 
+    if (SystemTimeToFileTime(&st, &ft)) 
+    { 
+        // Use file time 
+    } 
+}
+```
+
+## Heuristics
+
+This rule only recognizes the Windows `SYSTEMTIME` struct and the C `tm` struct.
+
+This rule is enforced regardless of whether the input arguments were validated before calling these functions. If all the input arguments are validated before calling the function, this rule can report false warning.
+
+This rule is an opt-in rule, meaning that code analysis should use a ruleset file, and the rule should be explicitly included in the ruleset file, and enabled for it to be applied. For more information on creating a custom ruleset for code analysis, see [Use Rule Sets to Specify the `C++` Rules to Run](using-rule-sets-to-specify-the-cpp-rules-to-run.md).
+
+## See also
+
+[C6393](c6393.md)\
+[C6394](c6394.md)\
+[C26861](c26861.md)\
+[C26862](c26862.md)\
+[C26864](c26864.md)