Merge branch 'rc/1.26' into main-126-merge

Author: james

docs/language/README.rst

@@ -18,7 +18,7 @@ Project structure
 The documentation currently consists of the following Sphinx projects:
 
 - ``learn-ql``–help topics to help you learn CodeQL and write queries
-- ``ql-handbook``–an overview of important concepts in QL, the language that underlies CodeQL analysis
+- ``ql-language-reference``–an overview of important concepts in QL, the language that underlies CodeQL analysis
 - ``support``–the languages and frameworks currently supported in CodeQL analysis
 - ``ql-training``–source files for the CodeQL training and variant analysis examples slide decks
 

docs/language/learn-ql/intro-to-data-flow.rst renamed to docs/language/learn-ql/about-data-flow-analysis.rst

@@ -14,17 +14,17 @@ The following sections provide a brief introduction to data flow analysis with C
 
 See the following tutorials for more information about analyzing data flow in specific languages:
 
-- ":doc:`Analyzing data flow in C/C++ <cpp/dataflow>`"
-- ":doc:`Analyzing data flow in C# <csharp/dataflow>`"
-- ":doc:`Analyzing data flow in Java <java/dataflow>`"
-- ":doc:`Analyzing data flow in JavaScript/TypeScript <javascript/dataflow>`"
-- ":doc:`Analyzing data flow and tracking tainted data in Python <python/taint-tracking>`"
+- ":doc:`Analyzing data flow in C/C++ <cpp/analyzing-data-flow-in-cpp>`"
+- ":doc:`Analyzing data flow in C# <csharp/analyzing-data-flow-in-csharp>`"
+- ":doc:`Analyzing data flow in Java <java/analyzing-data-flow-in-java>`"
+- ":doc:`Analyzing data flow in JavaScript/TypeScript <javascript/analyzing-data-flow-in-javascript>`"
+- ":doc:`Analyzing data flow and tracking tainted data in Python <python/analyzing-data-flow-and-tracking-tainted-data-in-python>`"
 
 .. pull-quote::
 
     Note
 
-    Data flow analysis is used extensively in path queries. To learn more about path queries, see ":doc:`Creating path queries <writing-queries/path-queries>`."  
+    Data flow analysis is used extensively in path queries. To learn more about path queries, see ":doc:`Creating path queries <writing-queries/creating-path-queries>`."  
 
 .. _data-flow-graph:
 
@@ -49,8 +49,8 @@ flow between functions and through object properties. Global data flow, however,
 graph that do not precisely correspond to the flow of values, but model whether some value at runtime may be derived from another, for instance through a string manipulating
 operation.
 
-The data flow graph is computed using `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ to model the program elements that represent the graph's nodes.
-The flow of data between the nodes is modeled using `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ to compute the graph's edges.
+The data flow graph is computed using `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__ to model the program elements that represent the graph's nodes.
+The flow of data between the nodes is modeled using `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ to compute the graph's edges.
 
 Computing an accurate and complete data flow graph presents several challenges:
 
@@ -82,5 +82,5 @@ These flow steps are modeled in the taint-tracking library using predicates that
 Further reading
 ***************
 
-- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
+- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
 

docs/language/learn-ql/beginner/catch-the-fire-starter.rst

@@ -14,7 +14,7 @@ Read the examples below to learn how to define predicates and classes in QL. The
 Select the southerners
 ----------------------
 
-This time you only need to consider a specific group of villagers, namely those living in the south of the village. Instead of writing ``getLocation() = "south"`` in all your queries, you could define a new `predicate <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ ``isSouthern``:
+This time you only need to consider a specific group of villagers, namely those living in the south of the village. Instead of writing ``getLocation() = "south"`` in all your queries, you could define a new `predicate <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ ``isSouthern``:
 
 .. code-block:: ql
 
@@ -41,7 +41,7 @@ You can now list all southerners using:
    where isSouthern(p)
    select p
 
-This is already a nice way to simplify the logic, but we could be more efficient. Currently, the query looks at every ``Person p``, and then restricts to those who satisfy ``isSouthern(p)``. Instead, we could define a new `class <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ ``Southerner`` containing precisely the people we want to consider.
+This is already a nice way to simplify the logic, but we could be more efficient. Currently, the query looks at every ``Person p``, and then restricts to those who satisfy ``isSouthern(p)``. Instead, we could define a new `class <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__ ``Southerner`` containing precisely the people we want to consider.
 
 .. code-block:: ql
 

docs/language/learn-ql/beginner/cross-the-river.rst

@@ -20,8 +20,8 @@ A solution should be a set of instructions for how to ferry the items, such as "
 across the river, and come back with nothing. Then ferry the cabbage across, and come back with ..."
 
 There are lots of ways to approach this problem and implement it in QL. Before you start, make
-sure that you are familiar with how to define `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__
-and `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ in QL.
+sure that you are familiar with how to define `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__
+and `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ in QL.
 The following walkthrough is just one of many possible implementations, so have a go at writing your
 own query too! To find more example queries, see the list :ref:`below <alternatives>`.
 
@@ -69,7 +69,7 @@ For example, if the man is on the left shore, the goat on the right shore, and t
 shore, the state should be ``Left, Right, Left, Left``.
 
 You may find it helpful to introduce some variables that refer to the shore on which the man and the cargo items are. These
-temporary variables in the body of a class are called `fields <https://help.semmle.com/QL/ql-handbook/types.html#fields>`__.
+temporary variables in the body of a class are called `fields <https://help.semmle.com/QL/ql-language-reference/types.html#fields>`__.
 
 .. container:: toggle
 
@@ -159,12 +159,12 @@ could ferry the goat back and forth any number of times without ever reaching an
 Such a path would have an infinite number of river crossings without ever solving the puzzle.
 
 One way to restrict our paths to a finite number of river crossings is to define a 
-`member predicate <https://help.semmle.com/QL/ql-handbook/types.html#member-predicates>`__
+`member predicate <https://help.semmle.com/QL/ql-language-reference/types.html#member-predicates>`__
 ``State reachesVia(string path, int steps)``.
 The result of this predicate is any state that is reachable from the current state (``this``) via
 the given path in a specified finite number of steps.
 
-You can write this as a `recursive predicate <https://help.semmle.com/QL/ql-handbook/recursion.html>`__,
+You can write this as a `recursive predicate <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__,
 with the following base case and recursion step:
 
   - If ``this`` *is* the result state, then it (trivially) reaches the result state via an
@@ -203,7 +203,7 @@ the given path without revisiting any previously visited states.
     revisiting any previous states, and there is a ``safeFerry`` action from the intermediate state to
     the result state.
     (Hint: To check whether a state has previously been visited, you could check if
-    there is an `index of <https://help.semmle.com/QL/ql-spec/language.html#built-ins-for-string>`__
+    there is an `index of <ql-language-specification#built-ins-for-string>`__
     ``visitedStates`` at which the state occurs.)
 
 .. container:: toggle
@@ -218,7 +218,7 @@ the given path without revisiting any previously visited states.
 Display the results
 ~~~~~~~~~~~~~~~~~~~
 
-Once you've defined all the necessary classes and predicates, write a `select clause <https://help.semmle.com/QL/ql-handbook/queries.html#select-clauses>`__
+Once you've defined all the necessary classes and predicates, write a `select clause <https://help.semmle.com/QL/ql-language-reference/queries.html#select-clauses>`__
 that returns the resulting path.
 
 .. container:: toggle
@@ -230,7 +230,7 @@ that returns the resulting path.
    .. literalinclude:: river-crossing.ql
       :lines: 115-117
 
-The `don't-care expression <https://help.semmle.com/QL/ql-handbook/expressions.html#don-t-care-expressions>`__ (``_``),
+The `don't-care expression <https://help.semmle.com/QL/ql-language-reference/expressions.html#don-t-care-expressions>`__ (``_``),
 as the second argument to the ``reachesVia`` predicate, represents any value of ``visitedStates``.
 
 For now, the path defined in ``reachesVia`` just lists the order of cargo items to ferry.
@@ -254,12 +254,12 @@ Here are some more example queries that solve the river crossing puzzle:
      ➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/659603593702729237/>`__
 
   #. This query models the man and the cargo items in a different way, using an 
-     `abstract <https://help.semmle.com/QL/ql-handbook/annotations.html#abstract>`__
+     `abstract <https://help.semmle.com/QL/ql-language-reference/annotations.html#abstract>`__
      class and predicate. It also displays the resulting path in a more visual way.
 
      ➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/1025323464423811143/>`__
 
-  #. This query introduces `algebraic datatypes <https://help.semmle.com/QL/ql-handbook/types.html#algebraic-datatypes>`__
+  #. This query introduces `algebraic datatypes <https://help.semmle.com/QL/ql-language-reference/types.html#algebraic-datatypes>`__
      to model the situation, instead of defining everything as a subclass of ``string``.
 
      ➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/7260748307619718263/>`__

docs/language/learn-ql/beginner/crown-the-rightful-heir.rst

@@ -106,7 +106,7 @@ You can translate this into QL as follows:
      result = parentOf(ancestorOf(p))
    }
 
-As you can see, you have used the predicate ``ancestorOf()`` inside its own definition. This is an example of `recursion <https://help.semmle.com/QL/ql-handbook/recursion.html>`__.
+As you can see, you have used the predicate ``ancestorOf()`` inside its own definition. This is an example of `recursion <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__.
 
 This kind of recursion, where the same operation (in this case ``parentOf()``) is applied multiple times, is very common in QL, and is known as the *transitive closure* of the operation. There are two special symbols ``+`` and ``*`` that are extremely useful when working with transitive closures:
 

docs/language/learn-ql/beginner/find-the-thief.rst

@@ -48,12 +48,12 @@ There is too much information to search through by hand, so you decide to use yo
 
 #. Open the `query console on LGTM.com <https://lgtm.com/query>`__ to get started.
 #. Select a language and a demo project. For this tutorial, any language and project will do.
-#. Delete the default code ``import <language> select "hello world"``.
+#. Delete the default code ``import <ql-language-specification> select "hello world"``.
 
 QL libraries
 ------------
 
-We've defined a number of QL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ to help you extract data from your table. A QL predicate is a mini-query that expresses a relation between various pieces of data and describes some of their properties. In this case, the predicates give you information about a person, for example their height or age.
+We've defined a number of QL `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ to help you extract data from your table. A QL predicate is a mini-query that expresses a relation between various pieces of data and describes some of their properties. In this case, the predicates give you information about a person, for example their height or age.
 
 +--------------------+----------------------------------------------------------------------------------------+
 | Predicate          | Description                                                                            |
@@ -84,14 +84,14 @@ The villagers answered "yes" to the question "Is the thief taller than 150cm?" T
    where t.getHeight() > 150
    select t
 
-The first line, ``from Person t``, declares that ``t`` must be a ``Person``. We say that the `type <https://help.semmle.com/QL/ql-handbook/types.html>`__ of ``t`` is ``Person``.
+The first line, ``from Person t``, declares that ``t`` must be a ``Person``. We say that the `type <https://help.semmle.com/QL/ql-language-reference/types.html>`__ of ``t`` is ``Person``.
 
 Before you use the rest of your answers in your QL search, here are some more tools and examples to help you write your own QL queries:
 
 Logical connectives
 -------------------
 
-Using `logical connectives <https://help.semmle.com/QL/ql-handbook/formulas.html#logical-connectives>`__, you can write more complex queries that combine different pieces of information.
+Using `logical connectives <https://help.semmle.com/QL/ql-language-reference/formulas.html#logical-connectives>`__, you can write more complex queries that combine different pieces of information.
 
 For example, if you know that the thief is older than 30 *and* has brown hair, you can use the following ``where`` clause to link two predicates:
 
@@ -157,7 +157,7 @@ Notice that we have only temporarily introduced the variable ``c`` and we didn't
 
    Note
 
-   If you are familiar with logic, you may notice that ``exists`` in QL corresponds to the existential `quantifier <https://help.semmle.com/QL/ql-handbook/formulas.html#quantified-formulas>`__ in logic. QL also has a universal quantifier ``forall(vars | formula 1 | formula 2)`` which is logically equivalent to ``not exists(vars | formula 1 | not formula 2)``.
+   If you are familiar with logic, you may notice that ``exists`` in QL corresponds to the existential `quantifier <https://help.semmle.com/QL/ql-language-reference/formulas.html#quantified-formulas>`__ in logic. QL also has a universal quantifier ``forall(vars | formula 1 | formula 2)`` which is logically equivalent to ``not exists(vars | formula 1 | not formula 2)``.
 
 The real investigation
 ----------------------
@@ -218,7 +218,7 @@ You are getting closer to solving the mystery! Unfortunately, you still have qui
 More advanced queries
 ---------------------
 
-What if you want to find the oldest, youngest, tallest, or shortest person in the village? As mentioned in the previous topic, you can do this using ``exists``. However, there is also a more efficient way to do this in QL using functions like ``max`` and ``min``. These are examples of `aggregates <https://help.semmle.com/QL/ql-handbook/expressions.html#aggregations>`__.
+What if you want to find the oldest, youngest, tallest, or shortest person in the village? As mentioned in the previous topic, you can do this using ``exists``. However, there is also a more efficient way to do this in QL using functions like ``max`` and ``min``. These are examples of `aggregates <https://help.semmle.com/QL/ql-language-reference/expressions.html#aggregations>`__.
 
 In general, an aggregate is a function that performs an operation on multiple pieces of data and returns a single value as its output. Common aggregates are ``count``, ``max``, ``min``, ``avg`` (average) and ``sum``. The general way to use an aggregate is:
 

docs/language/learn-ql/cpp/dataflow.rst renamed to docs/language/learn-ql/cpp/analyzing-data-flow-in-cpp.rst

@@ -6,7 +6,7 @@ You can use data flow analysis to track the flow of potentially malicious or ins
 About data flow
 ---------------
 
-Data flow analysis computes the possible values that a variable can hold at various points in a program, determining how those values propagate through the program, and where they are used. In CodeQL, you can model both local data flow and global data flow. For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../intro-to-data-flow>`."
+Data flow analysis computes the possible values that a variable can hold at various points in a program, determining how those values propagate through the program, and where they are used. In CodeQL, you can model both local data flow and global data flow. For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../about-data-flow-analysis>`."
 
 Local data flow
 ---------------
@@ -390,7 +390,7 @@ Exercise 4
 Further reading
 ---------------
 
-- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
+- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
 
 
 .. include:: ../../reusables/cpp-further-reading.rst

docs/language/learn-ql/cpp/basic-query-cpp.rst renamed to docs/language/learn-ql/cpp/basic-query-for-cpp-code.rst

@@ -0,0 +1,42 @@
+CodeQL for C and C++
+====================
+
+Experiment and learn how to write effective and efficient queries for CodeQL databases generated from C and C++ codebases.
+
+.. toctree::
+   :hidden:
+
+   basic-query-for-cpp-code
+   codeql-library-for-cpp
+   functions-in-cpp
+   expressions-types-and-statements-in-cpp
+   conversions-and-classes-in-cpp
+   analyzing-data-flow-in-cpp
+   refining-a-query-to-account-for-edge-cases
+   detecting-a-potential-buffer-overflow
+   using-the-guards-library-in-cpp
+   using-range-analsis-in-cpp
+   hash-consing-and-value-numbering
+
+
+-  :doc:`Basic query for C and C++ code <basic-query-for-cpp-code>`: Learn to write and run a simple CodeQL query using LGTM.
+
+-  :doc:`CodeQL library for C and C++ <codeql-library-for-cpp>`: When analyzing C or C++ code, you can use the large collection of classes in the CodeQL library for C and C++.
+
+-  :doc:`Functions in C and C++ <functions-in-cpp>`: You can use CodeQL to explore functions in C and C++ code.
+
+-  :doc:`Expressions, types, and statements in C and C++ <expressions-types-and-statements-in-cpp>`: You can use CodeQL to explore expressions, types, and statements in C and C++ code to find, for example, incorrect assignments.
+
+-  :doc:`Conversions and classes in C and C++ <conversions-and-classes-in-cpp>`: You can use the standard CodeQL libraries for C and C++ to detect when the type of an expression is changed.
+
+-  :doc:`Analyzing data flow in C and C++ <analyzing-data-flow-in-cpp>`: You can use data flow analysis to track the flow of potentially malicious or insecure data that can cause vulnerabilities in your codebase.
+
+-  :doc:`Refining a query to account for edge cases <refining-a-query-to-account-for-edge-cases>`: You can improve the results generated by a CodeQL query by adding conditions to remove false positive results caused by common edge cases.
+
+-  :doc:`Detecting a potential buffer overflow <detecting-a-potential-buffer-overflow>`: You can use CodeQL to detect potential buffer overflows by checking for allocations equal to ``strlen`` in C and C++.
+
+-  :doc:`Using the guards library in C and C++ <using-the-guards-library-in-cpp>`: You can use the CodeQL guards library to identify conditional expressions that control the execution of other parts of a program in C and C++ codebases. 
+
+-  :doc:`Using range analysis for C and C++ <using-range-analsis-in-cpp>`: You can use range analysis to determine the upper or lower bounds on an expression, or whether an expression could potentially over or underflow.
+
+-  :doc:`Hash consing and value numbering <hash-consing-and-value-numbering>`: You can use specialized CodeQL libraries to recognize expressions that are syntactically identical or compute the same value at runtime in C and C++ codebases.