Skip to content

Fix missing trailing underscore for SAL annotations #5591

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions docs/c-runtime-library/sal-annotations.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
---
title: "SAL Annotations"
description: "A brief description of the Microsoft source-code annotation language (SAL)."
ms.date: "11/04/2016"
ms.date: 11/04/2016
ms.topic: "concept-article"
helpviewer_keywords: ["__z annotation", "ref annotation", "_opt annotation", "__checkreturn annotatioin", "__deref_opt annotation", "deref_opt annotation", "__deref annotation", "__in annotation", "annotations [C++]", "z annotation", "_inout annotation", "__ref annotation", "full annotation", "_in annotation", "_ref annotation", "__out annotation", "_ecount annotation", "SAL annotations", "__opt annotation", "inout annotation", "in annotation", "_CA_SHOULD_CHECK_RETURN", "__bcount annotation", "_full annotation", "_bcount annotation", "deref annotation", "part annotation", "_out annotation", "__nz annotation", "__part annotation", "opt annotation", "__full annotation", "_nz annotation", "_z annotation", "out annotation", "__ecount annotation", "__inout annotation", "SAL annotations, _CA_SHOULD_CHECK_RETURN", "_deref_opt annotation", "_deref annotation", "nz annotation", "_part annotation", "ecount annotation", "bcount annotation"]
ms.assetid: 81893638-010c-41a0-9cb3-666fe360f3e0
---
# SAL annotations

If you examine the library header files, you may notice some unusual annotations, for example, `_In_z` and `_Out_z_cap_(_Size)`. These annotations are examples of the Microsoft source-code annotation language (SAL). SAL provides a set of annotations to describe how a function uses its parameters and return type. For example, it indicates the assumptions it makes about them and the guarantees it makes on finishing. The header file \<sal.h> defines the annotations.
If you examine the library header files, you may notice some unusual annotations, for example, `_In_z_` and `_Out_z_cap_(_Size)`. These annotations are examples of the Microsoft source-code annotation language (SAL). SAL provides a set of annotations to describe how a function uses its parameters and return type. For example, it indicates the assumptions it makes about them and the guarantees it makes on finishing. The header file \<sal.h> defines the annotations.

For more information about using SAL annotations in Visual Studio, see [Using SAL annotations to reduce C/C++ code defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md).

Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Annotating function parameters and return values
title: "Annotating function parameters and return values"
description: "Reference guide to function parameter and return value annotations."
ms.date: 10/15/2019
ms.topic: "concept-article"
Expand Down Expand Up @@ -102,7 +102,7 @@ f1_keywords:
- "_In_"
- "_Inout_updates_bytes_"
- "_In_reads_to_ptr_z_"
- "_Ret_writes_bytes_to_maybenull"
- "_Ret_writes_bytes_to_maybenull_"
- "_Outptr_opt_result_nullonfailure_"
- "_In_reads_to_ptr_"
- "_Outptr_result_buffer_"
Expand All @@ -123,7 +123,6 @@ f1_keywords:
- "_Scanf_format_string_"
- "_Scanf_s_format_string_"
- "_Printf_format_string_"
ms.assetid: 82826a3d-0c81-421c-8ffe-4072555dca3a
---
# Annotating function parameters and return values

Expand Down
7 changes: 3 additions & 4 deletions docs/code-quality/c26116.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,19 @@
---
title: "Warning C26116"
description: "Learn more about: Warning C26116"
title: Warning C26116
ms.date: 11/04/2016
f1_keywords: ["C26116"]
helpviewer_keywords: ["C26116"]
ms.assetid: 43e99d2c-405e-4913-b6bd-47f5858b2877
---
# Warning C26116

> Failing to acquire or to hold lock '*lock*' in '*func*'.

Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs isn't performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock. You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Requires_lock_held`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases aren't balanced, they're considered to be *orphaned*. Warning C26116 is issued when a function has been annotated with `_Acquires_lock_`, but it doesn't acquire a lock, or when a function is annotated with `_Requires_lock_held` and releases the lock.
Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs isn't performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock. You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Requires_lock_held_`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases aren't balanced, they're considered to be *orphaned*. Warning C26116 is issued when a function has been annotated with `_Acquires_lock_`, but it doesn't acquire a lock, or when a function is annotated with `_Requires_lock_held_` and releases the lock.

## Example

The following example generates warning C26116 because the function `DoesNotLock` was annotated with `_Acquires_lock_` but doesn't acquire it. The function `DoesNotHoldLock` generates the warning because it's annotated with `_Requires_lock_held` and doesn't hold it.
The following example generates warning C26116 because the function `DoesNotLock` was annotated with `_Acquires_lock_` but doesn't acquire it. The function `DoesNotHoldLock` generates the warning because it's annotated with `_Requires_lock_held_` and doesn't hold it.

```cpp
typedef struct _DATA
Expand Down