C++: Rename predicates in FunctionInputsAndOutputs.qll and add QLDoc

cpp/ql/src/semmle/code/cpp/dataflow/internal/DataFlowUtil.qll

@@ -574,8 +574,8 @@ private predicate exprToExprStep_nocfg(Expr fromExpr, Expr toExpr) {
       exists(DataFlowFunction f, FunctionInput inModel, FunctionOutput outModel, int iIn |
         call.getTarget() = f and
         f.hasDataFlow(inModel, outModel) and
-        outModel.isOutReturnValue() and
-        inModel.isInParameter(iIn) and
+        outModel.isReturnValue() and
+        inModel.isParameter(iIn) and
         fromExpr = call.getArgument(iIn)
       )
     )
@@ -585,12 +585,12 @@ private predicate exprToDefinitionByReferenceStep(Expr exprIn, Expr argOut) {
   exists(DataFlowFunction f, Call call, FunctionOutput outModel, int argOutIndex |
     call.getTarget() = f and
     argOut = call.getArgument(argOutIndex) and
-    outModel.isOutParameterPointer(argOutIndex) and
+    outModel.isParameterDeref(argOutIndex) and
     exists(int argInIndex, FunctionInput inModel | f.hasDataFlow(inModel, outModel) |
-      inModel.isInParameterPointer(argInIndex) and
+      inModel.isParameterDeref(argInIndex) and
       call.passesByReference(argInIndex, exprIn)
       or
-      inModel.isInParameter(argInIndex) and
+      inModel.isParameter(argInIndex) and
       exprIn = call.getArgument(argInIndex)
     )
   )

cpp/ql/src/semmle/code/cpp/dataflow/internal/TaintTrackingUtil.qll

@@ -122,11 +122,11 @@ private predicate exprToDefinitionByReferenceStep(Expr exprIn, Expr argOut) {
   exists(DataFlowFunction f, Call call, FunctionOutput outModel, int argOutIndex |
     call.getTarget() = f and
     argOut = call.getArgument(argOutIndex) and
-    outModel.isOutParameterPointer(argOutIndex) and
+    outModel.isParameterDeref(argOutIndex) and
     exists(int argInIndex, FunctionInput inModel | f.hasDataFlow(inModel, outModel) |
       // Taint flows from a pointer to a dereference, which DataFlow does not handle
       // memcpy(&dest_var, tainted_ptr, len)
-      inModel.isInParameterPointer(argInIndex) and
+      inModel.isParameterDeref(argInIndex) and
       exprIn = call.getArgument(argInIndex)
     )
   )
@@ -134,15 +134,15 @@ private predicate exprToDefinitionByReferenceStep(Expr exprIn, Expr argOut) {
   exists(TaintFunction f, Call call, FunctionOutput outModel, int argOutIndex |
     call.getTarget() = f and
     argOut = call.getArgument(argOutIndex) and
-    outModel.isOutParameterPointer(argOutIndex) and
+    outModel.isParameterDeref(argOutIndex) and
     exists(int argInIndex, FunctionInput inModel | f.hasTaintFlow(inModel, outModel) |
-      inModel.isInParameterPointer(argInIndex) and
+      inModel.isParameterDeref(argInIndex) and
       exprIn = call.getArgument(argInIndex)
       or
-      inModel.isInParameterPointer(argInIndex) and
+      inModel.isParameterDeref(argInIndex) and
       call.passesByReference(argInIndex, exprIn)
       or
-      inModel.isInParameter(argInIndex) and
+      inModel.isParameter(argInIndex) and
       exprIn = call.getArgument(argInIndex)
     )
   )

cpp/ql/src/semmle/code/cpp/models/implementations/IdentityFunction.qll

@@ -34,6 +34,6 @@ class IdentityFunction extends DataFlowFunction, SideEffectFunction, AliasFuncti
 
   override predicate hasDataFlow(FunctionInput input, FunctionOutput output) {
     // These functions simply return the argument value.
-    input.isInParameter(0) and output.isOutReturnValue()
+    input.isParameter(0) and output.isReturnValue()
   }
 }

cpp/ql/src/semmle/code/cpp/models/implementations/Inet.qll

@@ -5,8 +5,8 @@ class InetNtoa extends TaintFunction {
   InetNtoa() { hasGlobalName("inet_ntoa") }
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
-    input.isInParameter(0) and
-    output.isOutReturnPointer()
+    input.isParameter(0) and
+    output.isReturnValueDeref()
   }
 }
 
@@ -14,8 +14,8 @@ class InetAton extends TaintFunction, ArrayFunction {
   InetAton() { hasGlobalName("inet_aton") }
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
-    input.isInParameterPointer(0) and
-    output.isOutParameterPointer(1)
+    input.isParameterDeref(0) and
+    output.isParameterDeref(1)
   }
 
   override predicate hasArrayInput(int bufParam) { bufParam = 0 }
@@ -34,8 +34,8 @@ class InetAddr extends TaintFunction, ArrayFunction {
   InetAddr() { hasGlobalName("inet_addr") }
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
-    input.isInParameterPointer(0) and
-    output.isOutReturnValue()
+    input.isParameterDeref(0) and
+    output.isReturnValue()
   }
 
   override predicate hasArrayInput(int bufParam) { bufParam = 0 }
@@ -47,8 +47,8 @@ class InetNetwork extends TaintFunction, ArrayFunction {
   InetNetwork() { hasGlobalName("inet_network") }
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
-    input.isInParameterPointer(1) and
-    output.isOutReturnValue()
+    input.isParameterDeref(1) and
+    output.isReturnValue()
   }
 
   override predicate hasArrayInput(int bufParam) { bufParam = 0 }
@@ -61,10 +61,10 @@ class InetMakeaddr extends TaintFunction {
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
     (
-      input.isInParameter(0) or
-      input.isInParameter(1)
+      input.isParameter(0) or
+      input.isParameter(1)
     ) and
-    output.isOutReturnValue()
+    output.isReturnValue()
   }
 }
 
@@ -72,8 +72,8 @@ class InetLnaof extends TaintFunction {
   InetLnaof() { hasGlobalName("inet_lnaof") }
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
-    input.isInParameter(0) and
-    output.isOutReturnValue()
+    input.isParameter(0) and
+    output.isReturnValue()
   }
 }
 
@@ -81,8 +81,8 @@ class InetNetof extends TaintFunction {
   InetNetof() { hasGlobalName("inet_netof") }
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
-    input.isInParameter(0) and
-    output.isOutReturnValue()
+    input.isParameter(0) and
+    output.isReturnValue()
   }
 }
 
@@ -91,10 +91,10 @@ class InetPton extends TaintFunction, ArrayFunction {
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
     (
-      input.isInParameter(0) or
-      input.isInParameterPointer(1)
+      input.isParameter(0) or
+      input.isParameterDeref(1)
     ) and
-    output.isOutParameterPointer(2)
+    output.isParameterDeref(2)
   }
 
   override predicate hasArrayInput(int bufParam) { bufParam = 1 }
@@ -110,8 +110,8 @@ class Gethostbyname extends TaintFunction, ArrayFunction {
   Gethostbyname() { hasGlobalName("gethostbyname") }
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
-    input.isInParameterPointer(0) and
-    output.isOutReturnPointer()
+    input.isParameterDeref(0) and
+    output.isReturnValueDeref()
   }
 
   override predicate hasArrayInput(int bufParam) { bufParam = 0 }
@@ -124,11 +124,11 @@ class Gethostbyaddr extends TaintFunction, ArrayFunction {
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
     (
-      input.isInParameterPointer(0) or
-      input.isInParameter(1) or
-      input.isInParameter(2)
+      input.isParameterDeref(0) or
+      input.isParameter(1) or
+      input.isParameter(2)
     ) and
-    output.isOutReturnPointer()
+    output.isReturnValueDeref()
   }
 
   override predicate hasArrayInput(int bufParam) { bufParam = 0 }

cpp/ql/src/semmle/code/cpp/models/implementations/Memcpy.qll

@@ -19,22 +19,22 @@ class MemcpyFunction extends ArrayFunction, DataFlowFunction, TaintFunction {
   override predicate hasArrayOutput(int bufParam) { bufParam = 0 }
 
   override predicate hasDataFlow(FunctionInput input, FunctionOutput output) {
-    input.isInParameterPointer(1) and
-    output.isOutParameterPointer(0)
+    input.isParameterDeref(1) and
+    output.isParameterDeref(0)
     or
-    input.isInParameterPointer(1) and
-    output.isOutReturnPointer()
+    input.isParameterDeref(1) and
+    output.isReturnValueDeref()
     or
-    input.isInParameter(0) and
-    output.isOutReturnValue()
+    input.isParameter(0) and
+    output.isReturnValue()
   }
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
-    input.isInParameter(2) and
-    output.isOutParameterPointer(0)
+    input.isParameter(2) and
+    output.isParameterDeref(0)
     or
-    input.isInParameter(2) and
-    output.isOutReturnPointer()
+    input.isParameter(2) and
+    output.isReturnValueDeref()
   }
 
   override predicate hasArrayWithVariableSize(int bufParam, int countParam) {

cpp/ql/src/semmle/code/cpp/models/implementations/Pure.qll

@@ -41,17 +41,17 @@ class PureStrFunction extends AliasFunction, ArrayFunction, TaintFunction, SideE
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
     exists(ParameterIndex i |
-      input.isInParameter(i) and
+      input.isParameter(i) and
       exists(getParameter(i))
       or
-      input.isInParameterPointer(i) and
+      input.isParameterDeref(i) and
       getParameter(i).getUnspecifiedType() instanceof PointerType
     ) and
     (
-      output.isOutReturnPointer() and
+      output.isReturnValueDeref() and
       getUnspecifiedType() instanceof PointerType
       or
-      output.isOutReturnValue()
+      output.isReturnValue()
     )
   }
 
@@ -85,10 +85,10 @@ class PureFunction extends TaintFunction, SideEffectFunction {
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
     exists(ParameterIndex i |
-      input.isInParameter(i) and
+      input.isParameter(i) and
       exists(getParameter(i))
     ) and
-    output.isOutReturnValue()
+    output.isReturnValue()
   }
 
   override predicate neverReadsMemory() { any() }

cpp/ql/src/semmle/code/cpp/models/implementations/Strcat.qll

@@ -19,8 +19,8 @@ class StrcatFunction extends TaintFunction, DataFlowFunction, ArrayFunction {
   }
 
   override predicate hasDataFlow(FunctionInput input, FunctionOutput output) {
-    input.isInParameter(0) and
-    output.isOutReturnValue()
+    input.isParameter(0) and
+    output.isReturnValue()
   }
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
@@ -31,19 +31,19 @@ class StrcatFunction extends TaintFunction, DataFlowFunction, ArrayFunction {
         name = "_mbsncat" or
         name = "_mbsncat_l"
       ) and
-      input.isInParameter(2) and
-      output.isOutParameterPointer(0)
+      input.isParameter(2) and
+      output.isParameterDeref(0)
       or
       name = "_mbsncat_l" and
-      input.isInParameter(3) and
-      output.isOutParameterPointer(0)
+      input.isParameter(3) and
+      output.isParameterDeref(0)
     )
     or
-    input.isInParameterPointer(0) and
-    output.isOutParameterPointer(0)
+    input.isParameterDeref(0) and
+    output.isParameterDeref(0)
     or
-    input.isInParameter(1) and
-    output.isOutParameterPointer(0)
+    input.isParameter(1) and
+    output.isParameterDeref(0)
   }
 
   override predicate hasArrayInput(int param) {

cpp/ql/src/semmle/code/cpp/models/implementations/Strcpy.qll

@@ -55,15 +55,15 @@ class StrcpyFunction extends ArrayFunction, DataFlowFunction, TaintFunction {
       this.hasName("wcscpy")
     ) and
     (
-      input.isInParameterPointer(1) and
-      output.isOutParameterPointer(0)
+      input.isParameterDeref(1) and
+      output.isParameterDeref(0)
       or
-      input.isInParameterPointer(1) and
-      output.isOutReturnPointer()
+      input.isParameterDeref(1) and
+      output.isReturnValueDeref()
     )
     or
-    input.isInParameter(0) and
-    output.isOutReturnValue()
+    input.isParameter(0) and
+    output.isReturnValue()
   }
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
@@ -78,12 +78,12 @@ class StrcpyFunction extends ArrayFunction, DataFlowFunction, TaintFunction {
       this.hasName("_wcsncpy_l")
     ) and
     (
-      input.isInParameter(2) or
-      input.isInParameterPointer(1)
+      input.isParameter(2) or
+      input.isParameterDeref(1)
     ) and
     (
-      output.isOutParameterPointer(0) or
-      output.isOutReturnPointer()
+      output.isParameterDeref(0) or
+      output.isReturnValueDeref()
     )
   }
 }

cpp/ql/src/semmle/code/cpp/models/implementations/Strftime.qll

@@ -6,13 +6,13 @@ class Strftime extends TaintFunction, ArrayFunction {
 
   override predicate hasTaintFlow(FunctionInput input, FunctionOutput output) {
     (
-      input.isInParameter(1) or
-      input.isInParameterPointer(2) or
-      input.isInParameterPointer(3)
+      input.isParameter(1) or
+      input.isParameterDeref(2) or
+      input.isParameterDeref(3)
     ) and
     (
-      output.isOutParameterPointer(0) or
-      output.isOutReturnValue()
+      output.isParameterDeref(0) or
+      output.isReturnValue()
     )
   }
 

cpp/ql/src/semmle/code/cpp/models/implementations/Swap.qll

@@ -8,10 +8,10 @@ class Swap extends DataFlowFunction {
   Swap() { this.hasQualifiedName("std", "swap") }
 
   override predicate hasDataFlow(FunctionInput input, FunctionOutput output) {
-    input.isInParameterPointer(0) and
-    output.isOutParameterPointer(1)
+    input.isParameterDeref(0) and
+    output.isParameterDeref(1)
     or
-    input.isInParameterPointer(1) and
-    output.isOutParameterPointer(0)
+    input.isParameterDeref(1) and
+    output.isParameterDeref(0)
   }
 }

cpp/ql/src/semmle/code/cpp/models/interfaces/FunctionInputsAndOutputs.qll

@@ -13,21 +13,44 @@ class ParameterIndex extends int {
   ParameterIndex() { exists(Parameter p | this = p.getIndex()) }
 }
 
-newtype TFunctionInput =
+private newtype TFunctionInput =
   TInParameter(ParameterIndex i) or
-  TInParameterPointer(ParameterIndex i) or
-  TInQualifier()
+  TInParameterDeref(ParameterIndex i) or
+  TInQualifierObject() or
+  TInQualifierAddress()
 
+/**
+ * An input to a function. This can be:
+ * - The value of one of the function's parameters
+ * - The value pointed to by one of function's pointer or reference parameters
+ * - The value of the function's `this` pointer
+ * - The value pointed to by the function's `this` pointer
+ */
 class FunctionInput extends TFunctionInput {
   abstract string toString();
 
-  predicate isInParameter(ParameterIndex index) { none() }
+  predicate isParameter(ParameterIndex index) { none() }
 
-  predicate isInParameterPointer(ParameterIndex index) { none() }
+  predicate isParameterDeref(ParameterIndex index) { none() }
 
-  predicate isInQualifier() { none() }
+  predicate isQualifierObject() { none() }
+
+  predicate isQualifierAddress() { none() }
 }
 
+/**
+ * The input value of a parameter to a function.
+ * Example:
+ * ```cpp
+ * void func(int n, char* p, float& r);
+ * ```
+ * The `InParameter` with `getIndex() = 0` represents the value of `n` (with type `int`) on entry to
+ * the function.
+ * The `InParameter` with `getIndex() = 1` represents the value of `p` (with type `char*`) on entry
+ * to the function.
+ * The `InParameter` with `getIndex() = 2` represents the "value" of the reference `r` (with type 
+ * `float&`) on entry to the function, _not_ the value of the referred-to `float`.
+ */
 class InParameter extends FunctionInput, TInParameter {
   ParameterIndex index;
 
@@ -35,73 +58,182 @@ class InParameter extends FunctionInput, TInParameter {
 
   override string toString() { result = "InParameter " + index.toString() }
 
+  /** Gets the zero-based index of the parameter. */
   ParameterIndex getIndex() { result = index }
 
-  override predicate isInParameter(ParameterIndex i) { i = index }
+  override predicate isParameter(ParameterIndex i) { i = index }
 }
 
-class InParameterPointer extends FunctionInput, TInParameterPointer {
+/**
+ * The input value pointed to by a pointer parameter to a function, or the input value referred to
+ * by a reference parameter to a function.
+ * Example:
+ * ```cpp
+ * void func(int n, char* p, float& r);
+ * ```
+ * The `InParameterDeref` with `getIndex() = 1` represents the value of `*p` (with type `char`) on
+ * entry to the function.
+ * The `InParameterDeref` with `getIndex() = 2` represents the value of `r` (with type `float`) on
+ * entry to the function.
+ * There is no `InParameterDeref` with `getIndex() = 0`, because `n` is neither a pointer nor a
+ * reference.
+ */
+class InParameterDeref extends FunctionInput, TInParameterDeref {
   ParameterIndex index;
 
-  InParameterPointer() { this = TInParameterPointer(index) }
+  InParameterDeref() { this = TInParameterDeref(index) }
 
-  override string toString() { result = "InParameterPointer " + index.toString() }
+  override string toString() { result = "InParameterDeref " + index.toString() }
 
+  /** Gets the zero-based index of the parameter. */
   ParameterIndex getIndex() { result = index }
 
-  override predicate isInParameterPointer(ParameterIndex i) { i = index }
+  override predicate isParameterDeref(ParameterIndex i) { i = index }
 }
 
-class InQualifier extends FunctionInput, TInQualifier {
-  override string toString() { result = "InQualifier" }
+/**
+ * The input value pointed to by the `this` pointer of an instance member function.
+ * Example:
+ * ```cpp
+ * struct C {
+ *   void mfunc(int n, char* p, float& r) const;
+ * };
+ * ```
+ * The `InQualifierObject` represents the value of `*this` (with type `C const`) on entry to the
+ * function.
+ */
+class InQualifierObject extends FunctionInput, TInQualifierObject {
+  override string toString() { result = "InQualifierObject" }
 
-  override predicate isInQualifier() { any() }
+  override predicate isQualifierObject() { any() }
 }
 
-newtype TFunctionOutput =
-  TOutParameterPointer(ParameterIndex i) or
-  TOutQualifier() or
+/**
+ * The input value of the `this` pointer of an instance member function.
+ * Example:
+ * ```cpp
+ * struct C {
+ *   void mfunc(int n, char* p, float& r) const;
+ * };
+ * ```
+ * The `InQualifierAddress` represents the value of `this` (with type `C const *`) on entry to the
+ * function.
+ */
+class InQualifierAddress extends FunctionInput, TInQualifierAddress {
+  override string toString() { result = "InQualifierAddress" }
+
+  override predicate isQualifierAddress() { any() }
+}
+
+private newtype TFunctionOutput =
+  TOutParameterDeref(ParameterIndex i) or
+  TOutQualifierObject() or
   TOutReturnValue() or
-  TOutReturnPointer()
+  TOutReturnValueDeref()
 
+/**
+ * An output from a function. This can be:
+ * - The value pointed to by one of function's pointer or reference parameters
+ * - The value pointed to by the function's `this` pointer
+ * - The function's return value
+ * - The value pointed to by the function's return value, if the return value is a pointer or
+ *   reference
+ */
 class FunctionOutput extends TFunctionOutput {
   abstract string toString();
 
-  predicate isOutParameterPointer(ParameterIndex i) { none() }
+  predicate isParameterDeref(ParameterIndex i) { none() }
 
-  predicate isOutQualifier() { none() }
+  predicate isQualifierObject() { none() }
 
-  predicate isOutReturnValue() { none() }
+  predicate isReturnValue() { none() }
 
-  predicate isOutReturnPointer() { none() }
+  predicate isReturnValueDeref() { none() }
 }
 
-class OutParameterPointer extends FunctionOutput, TOutParameterPointer {
+/**
+ * The output value pointed to by a pointer parameter to a function, or the output value referred to
+ * by a reference parameter to a function.
+ * Example:
+ * ```cpp
+ * void func(int n, char* p, float& r);
+ * ```
+ * The `OutParameterDeref` with `getIndex() = 1` represents the value of `*p` (with type `char`) on
+ * return from the function.
+ * The `OutParameterDeref` with `getIndex() = 2` represents the value of `r` (with type `float`) on
+ * return from the function.
+ * There is no `OutParameterDeref` with `getIndex() = 0`, because `n` is neither a pointer nor a
+ * reference.
+ */
+class OutParameterDeref extends FunctionOutput, TOutParameterDeref {
   ParameterIndex index;
 
-  OutParameterPointer() { this = TOutParameterPointer(index) }
+  OutParameterDeref() { this = TOutParameterDeref(index) }
 
-  override string toString() { result = "OutParameterPointer " + index.toString() }
+  override string toString() { result = "OutParameterDeref " + index.toString() }
 
   ParameterIndex getIndex() { result = index }
 
-  override predicate isOutParameterPointer(ParameterIndex i) { i = index }
+  override predicate isParameterDeref(ParameterIndex i) { i = index }
 }
 
-class OutQualifier extends FunctionOutput, TOutQualifier {
+/**
+ * The output value pointed to by the `this` pointer of an instance member function.
+ * Example:
+ * ```cpp
+ * struct C {
+ *   void mfunc(int n, char* p, float& r);
+ * };
+ * ```
+ * The `OutQualifierObject` represents the value of `*this` (with type `C`) on return from the
+ * function.
+ */
+class OutQualifierObject extends FunctionOutput, TOutQualifierObject {
   override string toString() { result = "OutQualifier" }
 
-  override predicate isOutQualifier() { any() }
+  override predicate isQualifierObject() { any() }
 }
 
+/**
+ * The value returned by a function.
+ * Example:
+ * ```cpp
+ * int getInt();
+ * char* getPointer();
+ * float& getReference();
+ * ```
+ * The `OutReturnValue` for `getInt()` represents the value returned by `getInt()` (with type
+ * `int`).
+ * The `OutReturnValue` for `getPointer()` represents the value returned by `getPointer()` (with
+ * type `char*`).
+ * The `OutReturnValue` for `getReference()` represents the "value" of the reference returned by
+ * `getReference()` (with type `float&`), _not_ the value of the referred-to `float`.
+ */
 class OutReturnValue extends FunctionOutput, TOutReturnValue {
   override string toString() { result = "OutReturnValue" }
 
-  override predicate isOutReturnValue() { any() }
+  override predicate isReturnValue() { any() }
 }
 
-class OutReturnPointer extends FunctionOutput, TOutReturnPointer {
-  override string toString() { result = "OutReturnPointer" }
+/**
+ * The output value pointed to by the return value of a function, if the function returns a pointer,
+ * or the output value referred to by the return value of a function, if the function returns a
+ * reference.
+ * Example:
+ * ```cpp
+ * char* getPointer();
+ * float& getReference();
+ * int getInt();
+ * ```
+ * The `OutReturnValueDeref` for `getPointer()` represents the value of `*getPointer()` (with type
+ * `char`).
+ * The `OutReturnValueDeref` for `getReference()` represents the value of `getReference()` (with
+ * type `float`).
+ * There is no `OutReturnValueDeref` for `getInt()`, because the return type of `getInt()` is
+ * neither a pointer nor a reference.
+ */
+class OutReturnValueDeref extends FunctionOutput, TOutReturnValueDeref {
+  override string toString() { result = "OutReturnValueDeref" }
 
-  override predicate isOutReturnPointer() { any() }
+  override predicate isReturnValueDeref() { any() }
 }