Skip to content

Commit c58e190

Browse files
jsingletjsinglet
committed
docs
1 parent 2a42deb commit c58e190

File tree

2 files changed

+196
-0
lines changed

2 files changed

+196
-0
lines changed

‎c/cert/src/rules/CON41-C/WrapFunctionsThatCanFailSpuriouslyInLoop.md

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# CON41-C: Wrap functions that can fail spuriously in a loop
2+
3+
This query implements the CERT-C rule CON41-C:
4+
5+
> Wrap functions that can fail spuriously in a loop
6+
7+
8+
9+
## Description
10+
11+
Functions that can fail spuriously should be wrapped in a loop. The `atomic_compare_exchange_weak()` and `atomic_compare_exchange_weak_explicit()` functions both attempt to set an atomic variable to a new value but only if it currently possesses a known old value. Unlike the related functions `atomic_compare_exchange_strong()` and `atomic_compare_exchange_strong_explicit()`, these functions are permitted to *fail spuriously*. This makes these functions faster on some platforms—for example, on architectures that implement compare-and-exchange using load-linked/store-conditional instructions, such as Alpha, ARM, MIPS, and PowerPC. The C Standard, 7.17.7.4, paragraph 4 \[[ISO/IEC 9899:2011](https://wiki.sei.cmu.edu/confluence/display/c/AA.+Bibliography#AA.Bibliography-ISO%2FIEC9899-2011)\], describes this behavior:
12+
13+
> A weak compare-and-exchange operation may fail spuriously. That is, even when the contents of memory referred to by `expected` and `object` are equal, it may return zero and store back to `expected` the same memory contents that were originally there.
14+
15+
16+
## Noncompliant Code Example
17+
18+
In this noncompliant code example, `reorganize_data_structure()` is to be used as an argument to `thrd_create()`. After reorganizing, the function attempts to replace the head pointer so that it points to the new version. If no other thread has changed the head pointer since it was originally loaded, `reorganize_data_structure()` is intended to exit the thread with a result of `true`, indicating success. Otherwise, the new reorganization attempt is discarded and the thread is exited with a result of `false`. However, `atomic_compare_exchange_weak()` may fail even when the head pointer has not changed. Therefore, `reorganize_data_structure()` may perform the work and then discard it unnecessarily.
19+
20+
```cpp
21+
#include <stdatomic.h>
22+
#include <stdbool.h>
23+
24+
struct data {
25+
struct data *next;
26+
/* ... */
27+
};
28+
29+
extern void cleanup_data_structure(struct data *head);
30+
31+
int reorganize_data_structure(void *thread_arg) {
32+
struct data *_Atomic *ptr_to_head = thread_arg;
33+
struct data *old_head = atomic_load(ptr_to_head);
34+
struct data *new_head;
35+
bool success;
36+
37+
/* ... Reorganize the data structure ... */
38+
39+
success = atomic_compare_exchange_weak(ptr_to_head,
40+
&old_head, new_head);
41+
if (!success) {
42+
cleanup_data_structure(new_head);
43+
}
44+
return success; /* Exit the thread */
45+
}
46+
47+
```
48+
49+
## Compliant Solution (atomic_compare_exchange_weak())
50+
51+
To recover from spurious failures, a loop must be used. However, `atomic_compare_exchange_weak()` might fail because the head pointer changed, or the failure may be spurious. In either case, the thread must perform the work repeatedly until the compare-and-exchange succeeds, as shown in this compliant solution:
52+
53+
```cpp
54+
#include <stdatomic.h>
55+
#include <stdbool.h>
56+
#include <stddef.h>
57+
58+
struct data {
59+
struct data *next;
60+
/* ... */
61+
};
62+
63+
extern void cleanup_data_structure(struct data *head);
64+
65+
int reorganize_data_structure(void *thread_arg) {
66+
struct data *_Atomic *ptr_to_head = thread_arg;
67+
struct data *old_head = atomic_load(ptr_to_head);
68+
struct data *new_head = NULL;
69+
struct data *saved_old_head;
70+
bool success;
71+
72+
do {
73+
if (new_head != NULL) {
74+
cleanup_data_structure(new_head);
75+
}
76+
saved_old_head = old_head;
77+
78+
/* ... Reorganize the data structure ... */
79+
80+
} while (!(success = atomic_compare_exchange_weak(
81+
ptr_to_head, &old_head, new_head
82+
)) && old_head == saved_old_head);
83+
return success; /* Exit the thread */
84+
}
85+
86+
```
87+
This loop could also be part of a larger control flow; for example, the thread from the noncompliant code example could be retried if it returns `false`.
88+
89+
## Compliant Solution (atomic_compare_exchange_strong())
90+
91+
When a weak compare-and-exchange would require a loop and a strong one would not, the strong one is preferable, as in this compliant solution:
92+
93+
```cpp
94+
#include <stdatomic.h>
95+
#include <stdbool.h>
96+
97+
struct data {
98+
struct data *next;
99+
/* ... */
100+
};
101+
102+
extern void cleanup_data_structure(struct data *head);
103+
104+
int reorganize_data_structure(void *thread_arg) {
105+
struct data *_Atomic *ptr_to_head = thread_arg;
106+
struct data *old_head = atomic_load(ptr_to_head);
107+
struct data *new_head;
108+
bool success;
109+
110+
/* ... Reorganize the data structure ... */
111+
112+
success = atomic_compare_exchange_strong(
113+
ptr_to_head, &old_head, new_head
114+
);
115+
if (!success) {
116+
cleanup_data_structure(new_head);
117+
}
118+
return success; /* Exit the thread */
119+
}
120+
121+
```
122+
123+
## Risk Assessment
124+
125+
Failing to wrap the `atomic_compare_exchange_weak()` and `atomic_compare_exchange_weak_explicit()` functions in a loop can result in incorrect values and control flow.
126+
127+
<table> <tbody> <tr> <th> Rule </th> <th> Severity </th> <th> Likelihood </th> <th> Remediation Cost </th> <th> Priority </th> <th> Level </th> </tr> <tr> <td> CON41-C </td> <td> Low </td> <td> Unlikely </td> <td> Medium </td> <td> <strong>P2</strong> </td> <td> <strong>L3</strong> </td> </tr> </tbody> </table>
128+
129+
130+
## Automated Detection
131+
132+
<table> <tbody> <tr> <th> Tool </th> <th> Version </th> <th> Checker </th> <th> Description </th> </tr> <tr> <td> <a> CodeSonar </a> </td> <td> 7.0p0 </td> <td> <strong>LANG.STRUCT.ICOL</strong> </td> <td> Inappropriate Call Outside Loop </td> </tr> <tr> <td> <a> Coverity </a> </td> <td> 2017.07 </td> <td> <strong>BAD_CHECK_OF_WAIT_COND</strong> </td> <td> Implemented </td> </tr> <tr> <td> <a> Helix QAC </a> </td> <td> 2022.2 </td> <td> <strong>C2026</strong> <strong>C++5023</strong> </td> <td> </td> </tr> <tr> <td> <a> Klocwork </a> </td> <td> 2022.2 </td> <td> <strong>CERT.CONC.ATOMIC_COMP_FAIL_IN_LOOP</strong> </td> <td> </td> </tr> <tr> <td> <a> Parasoft C/C++test </a> </td> <td> 2022.1 </td> <td> <strong>CERT_C-CON41-a</strong> </td> <td> Wrap functions that can fail spuriously in a loop </td> </tr> <tr> <td> <a> Polyspace Bug Finder </a> </td> <td> R2022a </td> <td> <a> CERT C: Rule CON41-C </a> </td> <td> Checks for situations where functions that can spuriously fail are not wrapped in loop (rule fully covered) </td> </tr> <tr> <td> <a> PRQA QA-C </a> </td> <td> 9.7 </td> <td> <strong>2026</strong> </td> <td> </td> </tr> <tr> <td> <a> PRQA QA-C++ </a> </td> <td> 4.4 </td> <td> <strong>5023</strong> </td> <td> </td> </tr> </tbody> </table>
133+
134+
135+
## Related Vulnerabilities
136+
137+
Search for [vulnerabilities](https://www.securecoding.cert.org/confluence/display/seccode/BB.+Definitions#BB.Definitions-vulnerability) resulting from the violation of this rule on the [CERT website](https://www.kb.cert.org/vulnotes/bymetric?searchview&query=FIELD+KEYWORDS+contains+CON41-C).
138+
139+
## Related Guidelines
140+
141+
[Key here](https://wiki.sei.cmu.edu/confluence/display/c/How+this+Coding+Standard+is+Organized#HowthisCodingStandardisOrganized-RelatedGuidelines) (explains table format and definitions)
142+
143+
<table> <tbody> <tr> <th> Taxonomy </th> <th> Taxonomy item </th> <th> Relationship </th> </tr> <tr> <td> <a> CERT Oracle Secure Coding Standard for Java </a> </td> <td> <a> THI03-J. Always invoke wait() and await() methods inside a loop </a> </td> <td> Prior to 2018-01-12: CERT: Unspecified Relationship </td> </tr> </tbody> </table>
144+
145+
146+
## Bibliography
147+
148+
<table> <tbody> <tr> <td> \[ <a> ISO/IEC 9899:2011 </a> \] </td> <td> 7.17.7.4, "The <code>atomic_compare_exchange</code> Generic Functions" </td> </tr> <tr> <td> \[ <a> Lea 2000 </a> \] </td> <td> 1.3.2, "Liveness" 3.2.2, "Monitor Mechanics" </td> </tr> </tbody> </table>
149+
150+
151+
## Implementation notes
152+
153+
None
154+
155+
## References
156+
157+
* CERT-C: [CON41-C: Wrap functions that can fail spuriously in a loop](https://wiki.sei.cmu.edu/confluence/display/c)

‎c/cert/src/rules/CON41-C/WrapFunctionsThatCanFailSpuriouslyInLoop.ql

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
/**
2+
* @id c/cert/wrap-functions-that-can-fail-spuriously-in-loop
3+
* @name CON41-C: Wrap functions that can fail spuriously in a loop
4+
* @description Failing to wrap a function that may fail spuriously may result in unreliable program
5+
* behavior.
6+
* @kind problem
7+
* @precision very-high
8+
* @problem.severity error
9+
* @tags external/cert/id/con41-c
10+
* correctness
11+
* concurrency
12+
* external/cert/obligation/rule
13+
*/
14+
15+
import cpp
16+
import codingstandards.c.cert
17+
18+
/**
19+
* Models calls to routines in the `stdatomic` library. Note that these
20+
* are typically implemented as macros within Clang and GCC's standard
21+
* libraries.
22+
*/
23+
class SpuriouslyFailingFunctionCallType extends MacroInvocation {
24+
SpuriouslyFailingFunctionCallType() {
25+
getMacroName() = ["atomic_compare_exchange_weak", "atomic_compare_exchange_weak_explicit"]
26+
}
27+
}
28+
29+
from SpuriouslyFailingFunctionCallType fc
30+
where
31+
not isExcluded(fc, Concurrency3Package::wrapFunctionsThatCanFailSpuriouslyInLoopQuery()) and
32+
(
33+
exists(StmtParent sp | sp = fc.getStmt() and not sp.(Stmt).getParentStmt*() instanceof Loop)
34+
or
35+
exists(StmtParent sp |
36+
sp = fc.getExpr() and not sp.(Expr).getEnclosingStmt().getParentStmt*() instanceof Loop
37+
)
38+
)
39+
select fc, "Function that can spuriously fail not wrapped in a loop."

0 commit comments

Comments
 (0)