C++: Tweak docs of UsingStrcpyAsBoolean.ql

jbj · jbj · commit 657fe0eda3ac · 2019-01-10T08:35:53.000+01:00
This should make the documentation more in line with the documentation for our other queries. The @name of the query is changed to "Use of string copy function in a condition".
diff --git a/cpp/ql/src/Likely Bugs/Likely Typos/UsingStrcpyAsBoolean.qhelp b/cpp/ql/src/Likely Bugs/Likely Typos/UsingStrcpyAsBoolean.qhelp
@@ -4,12 +4,14 @@
 <qhelp>
 
 <overview>
-<p>This rule finds uses of the string copy function calls that return the <code>destination</code> parameter, 
-and that do not have a return value reserved to indicate an error.</p>
+<p>This rule flags calls to string copy functions used in conditions, either
+directly or as part of an equality operator or logical operator. The most
+common string copy functions always return their <code>destination</code>
+parameter and do not have a return value reserved to indicate an error.
+Therefore, such a function call always evaluates to true in a Boolean
+context.</p>
 
-<p>The rule flags occurrences using such string copy functions as the conditional of an <code>if</code> statement, either directly, as part of an equality operator or a logical operator.</p>
-  
-<p>The string copy functions that the rule takes into consideration are: </p>
+<p>The string copy functions that the rule takes into consideration are:</p>
 <ul>
   <li>strcpy</li>
   <li>wcscpy</li>
@@ -21,8 +23,8 @@ and that do not have a return value reserved to indicate an error.</p>
   <li>_mbsncpy</li>
   <li>_mbsncpy_l</li>
 </ul>
-  
-<p>NOTE: It is highly recommended to consider using a more secure version of string manipulation functions suchas as <code>strcpy_s</code>.</p>
+
+<p>NOTE: It is highly recommended to consider using a more secure version of string manipulation functions such as as <code>strcpy_s</code>.</p>
 
 </overview>
 <recommendation>
@@ -35,8 +37,8 @@ and that do not have a return value reserved to indicate an error.</p>
 </example>
 
 <references>
-<li>Microsoft Books on Line: <a href="https://docs.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2012/ccf4h9w8(v=vs.110)">C6324</a></li>
-<li>Microsoft Books on Line: <a href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/strcpy-wcscpy-mbscpy?view=vs-2017">strcpy, wcscpy, _mbscpy</a></li>
+<li>Microsoft Code Analysis for C/C++: <a href="https://docs.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2012/ccf4h9w8(v=vs.110)">C6324</a></li>
+<li>Microsoft C library reference: <a href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/strcpy-wcscpy-mbscpy">strcpy, wcscpy, _mbscpy</a></li>
 <li>US-CERT: <a href="https://www.us-cert.gov/bsi/articles/knowledge/coding-practices/strcpy_s-and-strcat_s">strncpy_s() and strncat_s()</a></li>
 
 </references>
diff --git a/cpp/ql/src/Likely Bugs/Likely Typos/UsingStrcpyAsBoolean.ql b/cpp/ql/src/Likely Bugs/Likely Typos/UsingStrcpyAsBoolean.ql
@@ -1,13 +1,14 @@
 /**
- * @name Using the return value of a strcpy or related string copy function as a boolean operator
- * @description The return value for strcpy, strncpy, or related string copy functions have no reserved return value to indicate an error.
- *              Using the return values of these functions as boolean function .
- *              Either the intent was to use a more secure version of a string copy function (such as strcpy_s), or a string compare function (such as strcmp).
+ * @name Use of string copy function in a condition
+ * @description The return value for strcpy, strncpy, or related string copy
+ *              functions have no reserved return value to indicate an error.
+ *              Using them in a condition is likely to be a logic error.
  * @kind problem
  * @problem.severity error
  * @precision high
  * @id cpp/string-copy-return-value-as-boolean
  * @tags external/microsoft/C6324
+ *       correctness
  */
 
 import cpp
@@ -36,7 +37,7 @@ predicate isStringCopyCastedAsBoolean(FunctionCall func, Expr expr1, string msg)
   DataFlow::localFlow(DataFlow::exprNode(func), DataFlow::exprNode(expr1)) and
   isBoolean(expr1.getConversion*()) and
   isStringComparisonFunction(func.getTarget().getQualifiedName()) and
-  msg = "Return Value of " + func.getTarget().getQualifiedName() + " used as boolean."
+  msg = "Return value of " + func.getTarget().getQualifiedName() + " used as Boolean."
 }
 
 predicate isStringCopyUsedInLogicalOperationOrCondition(FunctionCall func, Expr expr1, string msg) {
@@ -60,14 +61,14 @@ predicate isStringCopyUsedInLogicalOperationOrCondition(FunctionCall func, Expr
           func = ble.getAChild()
         )
       ) and
-      msg = "Return Value of " + func.getTarget().getQualifiedName() +
+      msg = "Return value of " + func.getTarget().getQualifiedName() +
           " used in a logical operation."
     )
     or
     exists(ConditionalStmt condstmt | condstmt.getAChild() = expr1 |
       // or the string copy function is used directly as the conditional expression
       func = condstmt.getChild(0) and
-      msg = "Return Value of " + func.getTarget().getQualifiedName() +
+      msg = "Return value of " + func.getTarget().getQualifiedName() +
           " used directly in a conditional expression."
     )
   )
