-
Learn QL
+
Learn CodeQL
QL for variant analysis
QL tools
Queries
diff --git a/docs/language/learn-ql/about-ql.rst b/docs/language/learn-ql/about-ql.rst
index 145f98ad600..8f2f26018a4 100644
--- a/docs/language/learn-ql/about-ql.rst
+++ b/docs/language/learn-ql/about-ql.rst
@@ -1,11 +1,11 @@
About QL
========
-This section is aimed at users with a background in general purpose programming as well as in databases. For a basic introduction and information on how to get started, see :doc:`Introduction to the QL language
` and :doc:`Learning QL <../index>`.
+This section is aimed at users with a background in general purpose programming as well as in databases. For a basic introduction and information on how to get started, see :doc:`Introduction to QL ` and :doc:`Learning CodeQL <../index>`.
QL is a declarative, object-oriented query language that is optimized to enable efficient analysis of hierarchical data structures, in particular, databases representing software artifacts.
-The queries and metrics used in LGTM are implemented using QL. This ensures that they can be extended or revised easily to keep up with changes in definitions of best coding practice. We continually improve existing queries as we work towards the ultimate goal of 100% precision.
+The queries and metrics used in LGTM are implemented using CodeQL, which uses QL to analyze code. This ensures that they can be extended or revised easily to keep up with changes in definitions of best coding practice. We continually improve existing queries as we work towards the ultimate goal of 100% precision.
You can write queries to identify security vulnerabilities, find coding errors and bugs, or find code that breaks your team's guidelines for best practice. You can also create customized versions of the default queries to accommodate a new framework.
diff --git a/docs/language/learn-ql/advanced/abstract-classes.rst b/docs/language/learn-ql/advanced/abstract-classes.rst
index d616a31395b..32441b35996 100644
--- a/docs/language/learn-ql/advanced/abstract-classes.rst
+++ b/docs/language/learn-ql/advanced/abstract-classes.rst
@@ -4,7 +4,7 @@ Semantics of abstract classes
Concrete classes
----------------
-Concrete QL classes, as described in the QL language handbook topic on `Classes `__, lend themselves well to top-down modeling. We start from general superclasses representing large sets of values, and carve out individual subclasses representing more restricted sets of values.
+Concrete classes, as described in the QL language handbook topic on `Classes `__, lend themselves well to top-down modeling. We start from general superclasses representing large sets of values, and carve out individual subclasses representing more restricted sets of values.
A classic example where this approach is useful is when modeling ASTs (Abstract Syntax Trees): the node types of an AST form a natural inheritance hierarchy, where, for example, there is a class ``Expr`` representing all expression nodes, with many different subclasses for different categories of expressions. There might be a class ``ArithmeticExpr`` representing arithmetic expressions, which in turn could have subclasses ``AddExpr`` and ``SubExpr``.
@@ -57,7 +57,7 @@ Like a concrete class, an abstract class has one or more superclasses and a char
Example
~~~~~~~
-The following example is taken from the standard QL library for Java:
+The following example is taken from the CodeQL library for Java:
.. code-block:: ql
diff --git a/docs/language/learn-ql/advanced/advanced-ql.rst b/docs/language/learn-ql/advanced/advanced-ql.rst
index e9397bd5ab2..67af5a6fb26 100644
--- a/docs/language/learn-ql/advanced/advanced-ql.rst
+++ b/docs/language/learn-ql/advanced/advanced-ql.rst
@@ -8,7 +8,7 @@ Advanced QL
./*
-Topics on advanced uses of QL. These topics assume that you are familiar with the QL language and the basics of query writing.
+Topics on advanced uses of QL. These topics assume that you are familiar with QL and the basics of query writing.
- :doc:`Semantics of abstract classes `
- :doc:`Choosing appropriate ways to constrain types `
diff --git a/docs/language/learn-ql/advanced/constraining-types.rst b/docs/language/learn-ql/advanced/constraining-types.rst
index e150c8ba380..3a8d2e76637 100644
--- a/docs/language/learn-ql/advanced/constraining-types.rst
+++ b/docs/language/learn-ql/advanced/constraining-types.rst
@@ -8,7 +8,7 @@ Type constraint methods
Note
- The examples below use the Java QL library. All QL libraries support using these methods to constrain variables, the only difference is in the names of the classes used.
+ The examples below use the CodeQL library for Java. All libraries support using these methods to constrain variables, the only difference is in the names of the classes used.
There are several ways of imposing type constraints on variables:
diff --git a/docs/language/learn-ql/advanced/determining-specific-types-variables.rst b/docs/language/learn-ql/advanced/determining-specific-types-variables.rst
index ce3c5a9e211..7deadde39c9 100644
--- a/docs/language/learn-ql/advanced/determining-specific-types-variables.rst
+++ b/docs/language/learn-ql/advanced/determining-specific-types-variables.rst
@@ -1,14 +1,14 @@
Determining the most specific types of a variable
=================================================
-It is sometimes useful to be able to determine what QL types an entity has -- especially when you are unfamiliar with the QL library used by a query. To help with this, QL provides a predicate called ``getAQlClass()``, which returns the most specific QL types of the entity that it is called on.
+It is sometimes useful to be able to determine what types an entity has -- especially when you are unfamiliar with the library used by a query. To help with this, there is a predicate called ``getAQlClass()``, which returns the most specific QL types of the entity that it is called on.
This can be useful when you are not sure of the most precise class of a value. Discovering a more precise class can allow you to cast to it and use predicates that are not available on the more general class.
Example
-------
-If you were working with a Java snapshot database, you might use ``getAQlClass()`` on every ``Expr`` in a callable called ``c``:
+If you were working with a Java database, you might use ``getAQlClass()`` on every ``Expr`` in a callable called ``c``:
**Java example**
@@ -23,6 +23,6 @@ If you were working with a Java snapshot database, you might use ``getAQlClass()
and e.getEnclosingCallable() = c
select e, e.getAQlClass()
-The result of this query is a list of the most specific types of every ``Expr`` in that function. You will see multiple results for some expressions because that expression is represented by more than one QL type.
+The result of this query is a list of the most specific types of every ``Expr`` in that function. You will see multiple results for some expressions because that expression is represented by more than one type.
-For example, ``StringLiteral``\ s like ``"Hello"`` in Java belong to both the ``StringLiteral`` QL class (a specialization of the ``Literal`` QL class) and the ``CompileTimeConstantExpr`` QL class. So any instances of ``StringLiteral``\ s in the results will produce more than one result, one for each of the QL classes to which they belong.
+For example, ``StringLiteral``\ s like ``"Hello"`` in Java belong to both the ``StringLiteral`` class (a specialization of the ``Literal`` class) and the ``CompileTimeConstantExpr`` class. So any instances of ``StringLiteral``\ s in the results will produce more than one result, one for each of the classes to which they belong.
diff --git a/docs/language/learn-ql/advanced/equivalence.rst b/docs/language/learn-ql/advanced/equivalence.rst
index 40f00cde00f..bf5efb595d0 100644
--- a/docs/language/learn-ql/advanced/equivalence.rst
+++ b/docs/language/learn-ql/advanced/equivalence.rst
@@ -6,7 +6,7 @@ The two expressions:
#. ``a() != b()``
#. ``not(a() = b())``
-look equivalent - so much so that inexperienced (and even experienced) QL programmers have been known to rewrite one as the other. However, they are not equivalent due to the quantifiers involved.
+look equivalent - so much so that inexperienced (and even experienced) programmers have been known to rewrite one as the other. However, they are not equivalent due to the quantifiers involved.
Thinking of ``a()`` and ``b()`` as sets of values, the first expression says that there is a pair of values (one from each side of the inequality) which are different.
diff --git a/docs/language/learn-ql/advanced/monotonic-aggregates.rst b/docs/language/learn-ql/advanced/monotonic-aggregates.rst
index 515dec6dff0..161776dbcf6 100644
--- a/docs/language/learn-ql/advanced/monotonic-aggregates.rst
+++ b/docs/language/learn-ql/advanced/monotonic-aggregates.rst
@@ -1,7 +1,7 @@
Monotonic aggregates in QL
==========================
-In addition to standard QL aggregates, QL also supports *monotonic* aggregates. These are a slightly different way of computing aggregates which have some advantages, notably the ability to be used recursively, which normal aggregates do not have. You can enable them in a scope by adding the \ ``language[monotonicAggregates]`` pragma on a predicate, class, or module.
+In addition to standard aggregates, QL also supports *monotonic* aggregates. These are a slightly different way of computing aggregates which have some advantages, notably the ability to be used recursively, which normal aggregates do not have. You can enable them in a scope by adding the \ ``language[monotonicAggregates]`` pragma on a predicate, class, or module.
Syntax
------
diff --git a/docs/language/learn-ql/beginner/find-thief-3.rst b/docs/language/learn-ql/beginner/find-thief-3.rst
index 03f7c866230..f8323147cf1 100644
--- a/docs/language/learn-ql/beginner/find-thief-3.rst
+++ b/docs/language/learn-ql/beginner/find-thief-3.rst
@@ -77,4 +77,4 @@ What next?
- Help the villagers track down another criminal in the :doc:`next tutorial `.
- Find out more about the concepts you discovered in this tutorial in the `QL language handbook `__.
-- Explore the libraries that help you get data about code in :doc:`Learning QL <../../index>`.
+- Explore the libraries that help you get data about code in :doc:`Learning CodeQL <../../index>`.
diff --git a/docs/language/learn-ql/beginner/fire-2.rst b/docs/language/learn-ql/beginner/fire-2.rst
index c5380fb0b6b..0c7e4852ae7 100644
--- a/docs/language/learn-ql/beginner/fire-2.rst
+++ b/docs/language/learn-ql/beginner/fire-2.rst
@@ -40,4 +40,4 @@ What next?
- Find out who will be the new ruler of the village in the :doc:`next tutorial `.
- Learn more about predicates and classes in the `QL language handbook `__.
-- Explore the libraries that help you get data about code in :doc:`Learning QL <../../index>`.
+- Explore the libraries that help you get data about code in :doc:`Learning CodeQL <../../index>`.
diff --git a/docs/language/learn-ql/beginner/heir.rst b/docs/language/learn-ql/beginner/heir.rst
index b5efd73fc40..f0f0c315025 100644
--- a/docs/language/learn-ql/beginner/heir.rst
+++ b/docs/language/learn-ql/beginner/heir.rst
@@ -161,4 +161,4 @@ What next?
- Learn more about recursion in the `QL language handbook `__.
- Put your QL skills to the test and solve the :doc:`River crossing puzzle <../ql-etudes/river-crossing>`.
-- Start using QL to analyze projects. See :doc:`Learning QL <../../index>` for a summary of the available languages and resources.
+- Start using QL to analyze projects. See :doc:`Learning CodeQL <../../index>` for a summary of the available languages and resources.
diff --git a/docs/language/learn-ql/beginner/ql-tutorials.rst b/docs/language/learn-ql/beginner/ql-tutorials.rst
index 2ba6e449b86..d97c4d6688e 100644
--- a/docs/language/learn-ql/beginner/ql-tutorials.rst
+++ b/docs/language/learn-ql/beginner/ql-tutorials.rst
@@ -7,18 +7,21 @@ QL detective tutorials
./*
-Welcome to QL! These tutorials are aimed at complete beginners. They teach you how to write QL queries and introduce you to key logic concepts along the way.
+Welcome to the detective tutorials! These are aimed at complete beginners who would like to learn the basics of QL,
+before analyzing code with CodeQL.
+The tutorials teach you how to write queries and introduce you to key logic concepts along the way.
-We recommend you first read the :doc:`Introduction to the QL language <../introduction-to-ql>` page for a basic description of QL.
+We recommend you first read the :doc:`Introduction to QL <../introduction-to-ql>` page for a description of the language and
+some simple examples.
-Currently the following tutorials are available:
+Currently the following detective tutorials are available:
-- :doc:`Find the thief ` - a three part mystery that introduces logical connectives, quantifiers and aggregates
+- :doc:`Find the thief ` - a three part mystery that introduces logical connectives, quantifiers, and aggregates
- :doc:`Catch the fire starter ` - an intriguing search that introduces predicates and classes
- :doc:`Crown the rightful heir ` - a detective puzzle that introduces recursion
Further resources
-----------------
-- For a summary of available learning resources, see :doc:`Learning QL <../../index>`.
+- For a summary of available learning resources, see :doc:`Learning CodeQL <../../index>`.
- For an overview of the important concepts in QL, see the `QL language handbook `__.
diff --git a/docs/language/learn-ql/cobol/introduce-libraries-cobol.rst b/docs/language/learn-ql/cobol/introduce-libraries-cobol.rst
index 8ab24df1edd..2d01200484d 100644
--- a/docs/language/learn-ql/cobol/introduce-libraries-cobol.rst
+++ b/docs/language/learn-ql/cobol/introduce-libraries-cobol.rst
@@ -1,10 +1,10 @@
-Introducing the QL libraries for COBOL
-======================================
+Introducing the CodeQL libraries for COBOL
+==========================================
Overview
--------
-There is an extensive QL library for analyzing COBOL code. The classes in this library present the data from a snapshot database in an object-oriented form and provide abstractions and predicates to help you with common analysis tasks.
+There is an extensive library for analyzing COBOL code. The classes in this library present the data from a CodeQL database in an object-oriented form and provide abstractions and predicates to help you with common analysis tasks.
The library is implemented as a set of QL modules–that is, files with the extension ``.qll``. The module ``cobol.qll`` imports most other standard library modules, so you can include the complete library by beginning your query with:
@@ -12,12 +12,12 @@ The library is implemented as a set of QL modules–that is, files with the exte
import cobol
-The rest of this tutorial briefly summarizes the most important QL classes and predicates provided by this library, including references to the `detailed API documentation `__ where applicable.
+The rest of this tutorial briefly summarizes the most important classes and predicates provided by this library, including references to the `detailed API documentation `__ where applicable.
Introducing the library
-----------------------
-The QL COBOL library presents information about COBOL source code at different levels:
+The CodeQL library for COBOL presents information about COBOL source code at different levels:
- **Textual** — classes that represent source code as unstructured text files
- **Lexical** — classes that represent comments and other tokens of interest
@@ -36,7 +36,7 @@ At its most basic level, a COBOL code base can simply be viewed as a collection
Files and folders
^^^^^^^^^^^^^^^^^
-In QL, files are represented as entities of class `File `__, and folders as entities of class `Folder `__, both of which are subclasses of class `Container `__.
+Files are represented as entities of class `File `__, and folders as entities of class `Folder `__, both of which are subclasses of class `Container `__.
Class `Container `__ provides the following member predicates:
@@ -48,7 +48,7 @@ Note that while ``getAFile`` and ``getAFolder`` are declared on class `Container
Both files and folders have paths, which can be accessed by the predicate ``Container.getAbsolutePath()``. For example, if ``f`` represents a file with the path ``/home/user/project/src/main.cbl``, then ``f.getAbsolutePath()`` evaluates to the string ``"/home/user/project/src/main.cbl"``, while ``f.getParentContainer().getAbsolutePath()`` returns ``"/home/user/project/src"``.
-These paths are absolute file system paths. If you want to obtain the path of a file relative to the snapshot source location, use ``Container.getRelativePath()`` instead. Note, however, that a snapshot may contain files that are not located underneath the snapshot source location; for such files, ``getRelativePath()`` will not return anything.
+These paths are absolute file system paths. If you want to obtain the path of a file relative to the source location in the CodeQL database, use ``Container.getRelativePath()`` instead. Note, however, that a database may contain files that are not located underneath the source location; for such files, ``getRelativePath()`` will not return anything.
The following member predicates of class `Container `__ provide more information about the name of a file or folder:
@@ -68,9 +68,9 @@ For example, the following query computes, for each folder, the number of COBOL
Locations
^^^^^^^^^
-Most entities in a snapshot database have an associated source location. Locations are identified by four pieces of information: a file, a start line, a start column, an end line, and an end column. Line and column counts are 1-based (so the first character of a file is at line 1, column 1), and the end position is inclusive.
+Most entities in a CodeQL database have an associated source location. Locations are identified by four pieces of information: a file, a start line, a start column, an end line, and an end column. Line and column counts are 1-based (so the first character of a file is at line 1, column 1), and the end position is inclusive.
-All entities associated with a source location belong to the QL class `Locatable `__. The location itself is modeled by the QL class `Location `__ and can be accessed through the member predicate ``Locatable.getLocation()``. The `Location `__ class provides the following member predicates:
+All entities associated with a source location belong to the class `Locatable `__. The location itself is modeled by the class `Location `__ and can be accessed through the member predicate ``Locatable.getLocation()``. The `Location `__ class provides the following member predicates:
- ``Location.getFile()``, ``Location.getStartLine()``, ``Location.getStartColumn()``, ``Location.getEndLine()``, ``Location.getEndColumn()`` return detailed information about the location.
- ``Location.getNumLines()`` returns the number of (whole or partial) lines covered by the location.
@@ -104,13 +104,13 @@ The most important member predicates are as follows:
Syntactic level
~~~~~~~~~~~~~~~
-The majority of classes in the QL COBOL library is concerned with representing a COBOL program as a collection of `abstract syntax trees `__ (ASTs).
+The majority of classes in the CodeQL library for COBOL are concerned with representing a COBOL program as a collection of `abstract syntax trees `__ (ASTs).
-The QL class `ASTNode `__ contains all entities representing nodes in the abstract syntax trees and defines generic tree traversal predicates:
+The class `ASTNode `__ contains all entities representing nodes in the abstract syntax trees and defines generic tree traversal predicates:
- ``ASTNode.getParent()``: returns the parent node of this AST node, if any.
-Please note that the QL libraries for COBOL do not currently represent all possible parts of a COBOL program. Due to the complexity of the language, and its many dialects, this is an ongoing task. We prioritize elements that are of interest to queries, and expand this selection over time. Please check the `detailed API documentation `__ to see what is currently available.
+Please note that the libraries for COBOL do not currently represent all possible parts of a COBOL program. Due to the complexity of the language, and its many dialects, this is an ongoing task. We prioritize elements that are of interest to queries, and expand this selection over time. Please check the `detailed API documentation `__ to see what is currently available.
The main structure of any COBOL program is represented by the `Unit `__ class and its subclasses. For example, each program definition has a `ProgramDefinition `__ counterpart. For each ``PROCEDURE DIVISION`` in the program, there will be a `ProcedureDivision `__ class.
diff --git a/docs/language/learn-ql/cobol/ql-for-cobol.rst b/docs/language/learn-ql/cobol/ql-for-cobol.rst
index 12ba25e69f4..f85ff62649e 100644
--- a/docs/language/learn-ql/cobol/ql-for-cobol.rst
+++ b/docs/language/learn-ql/cobol/ql-for-cobol.rst
@@ -1,5 +1,5 @@
-QL for COBOL
-============
+CodeQL for COBOL
+================
.. toctree::
:glob:
@@ -7,14 +7,14 @@ QL for COBOL
introduce-libraries-cobol
-This page provides an overview of the QL for COBOL documentation that is currently available.
+This page provides an overview of the CodeQL for COBOL documentation that is currently available.
- `Basic COBOL query `__ describes how to write and run queries using LGTM.
-- :doc:`Introducing the QL libraries for COBOL ` introduces the standard libraries used to write queries for COBOL code.
+- :doc:`Introducing the CodeQL libraries for COBOL ` introduces the standard libraries used to write queries for COBOL code.
Other resources
---------------
-- For the queries used in LGTM, display a `COBOL query `__ and click **Open in query console** to see the QL code used to find alerts.
-- For more information about the COBOL QL library see the `QL library for COBOL `__.
+- For the queries used in LGTM, display a `COBOL query `__ and click **Open in query console** to see the code used to find alerts.
+- For more information about the library for COBOL see the `CodeQL library for COBOL `__.
diff --git a/docs/language/learn-ql/conf.py b/docs/language/learn-ql/conf.py
index d9b1de5e9fc..94d3bf2205f 100644
--- a/docs/language/learn-ql/conf.py
+++ b/docs/language/learn-ql/conf.py
@@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
-# Learn QL documentation build configuration file, created by
+# Learn CodeQL documentation build configuration file, created by
# on Tuesday Nov 13 2018.
#
# This file is execfile()d with the current directory set to its
@@ -41,16 +41,16 @@ highlight_language = 'ql'
master_doc = 'index'
# General information about the project.
-project = u'Learning QL'
+project = u'Learning CodeQL'
# -- Project-specifc options for HTML output ----------------------------------------------
# The name for this set of Sphinx documents. If None, it defaults to
# " v documentation".
-html_title = 'Learn QL'
+html_title = 'Learn CodeQL'
# Output file base name for HTML help builder.
-htmlhelp_basename = 'Learn QL'
+htmlhelp_basename = 'Learn CodeQL'
# The version info for this project, if different from version and release in main conf.py file.
# The short X.Y version.
diff --git a/docs/language/learn-ql/cpp/conversions-classes.rst b/docs/language/learn-ql/cpp/conversions-classes.rst
index 716991f96b2..016efa50d67 100644
--- a/docs/language/learn-ql/cpp/conversions-classes.rst
+++ b/docs/language/learn-ql/cpp/conversions-classes.rst
@@ -4,12 +4,12 @@ Tutorial: Conversions and classes
Overview
--------
-This topic contains worked examples of how to write queries using the standard QL library classes for C/C++ conversions and classes.
+This topic contains worked examples of how to write queries using the CodeQL library classes for C/C++ conversions and classes.
Conversions
-----------
-Let us take a look at the QL ``Conversion`` class in the standard library:
+Let us take a look at the ``Conversion`` class in the standard library:
- ``Expr``
@@ -128,26 +128,26 @@ Unlike the earlier versions of the query, this query would return each side of t
Note
- In general, QL predicates named ``getAXxx`` exploit the ability to return multiple results (multiple instances of ``Xxx``) whereas plain ``getXxx`` predicates usually return at most one specific instance of ``Xxx``.
+ In general, predicates named ``getAXxx`` exploit the ability to return multiple results (multiple instances of ``Xxx``) whereas plain ``getXxx`` predicates usually return at most one specific instance of ``Xxx``.
Classes
-------
-Next we're going to look at C++ classes, using the following QL classes:
+Next we're going to look at C++ classes, using the following CodeQL classes:
- ``Type``
- - ``UserType``—includes classes, typedefs and enums
+ - ``UserType``—includes classes, typedefs, and enums
- ``Class``—a class or struct
- - ``Struct``—a struct, which is treated as a subtype of Class in QL.
+ - ``Struct``—a struct, which is treated as a subtype of ``Class``
- ``TemplateClass``—a C++ class template
Finding derived classes
~~~~~~~~~~~~~~~~~~~~~~~
-We want to create a query that checks for destructors that should be ``virtual``. Specifically, when a class and a class derived from it both have destructors, the base class destructor should generally be virtual. This ensures that the derived class destructor is always invoked. A ``Destructor`` in QL is a subtype of ``MemberFunction``:
+We want to create a query that checks for destructors that should be ``virtual``. Specifically, when a class and a class derived from it both have destructors, the base class destructor should generally be virtual. This ensures that the derived class destructor is always invoked. In the CodeQL library, ``Destructor`` is a subtype of ``MemberFunction``:
- ``Function``
@@ -221,13 +221,13 @@ Our last change is to use ``Function.isVirtual()`` to find cases where the base
That completes the query.
-There is a similar built-in LGTM `query `__ that finds classes in a C/C++ project with virtual functions but no virtual destructor. You can take a look at the QL code for this query by clicking **Open in query console** at the top of that page.
+There is a similar built-in LGTM `query `__ that finds classes in a C/C++ project with virtual functions but no virtual destructor. You can take a look at the code for this query by clicking **Open in query console** at the top of that page.
What next?
----------
- Explore other ways of querying classes using examples from the `C/C++ cookbook `__.
- Take a look at the :doc:`Analyzing data flow in C/C++ ` tutorial.
-- Try the worked examples in the following topics: :doc:`Example: Checking that constructors initialize all private fields ` and :doc:`Example: Checking for allocations equal to 'strlen(string)' without space for a null terminator `.
+- Try the worked examples in the following topics: :doc:`Example: Checking that constructors initialize all private fields `, and :doc:`Example: Checking for allocations equal to 'strlen(string)' without space for a null terminator `.
- Find out more about QL in the `QL language handbook `__ and `QL language specification `__.
- Learn more about the query console in `Using the query console `__.
diff --git a/docs/language/learn-ql/cpp/dataflow.rst b/docs/language/learn-ql/cpp/dataflow.rst
index 4867f3daf47..89f25913fbc 100644
--- a/docs/language/learn-ql/cpp/dataflow.rst
+++ b/docs/language/learn-ql/cpp/dataflow.rst
@@ -4,10 +4,10 @@ Analyzing data flow in C/C++
Overview
--------
-This topic describes how data flow analysis is implemented in the QL for C/C++ library and includes examples to help you write your own data flow queries.
-The following sections describe how to utilize the QL libraries for local data flow, global data flow and taint tracking.
+This topic describes how data flow analysis is implemented in the CodeQL libraries for C/C++ and includes examples to help you write your own data flow queries.
+The following sections describe how to utilize the libraries for local data flow, global data flow, and taint tracking.
-For a more general introduction to modeling data flow in QL, see :doc:`Introduction to data flow analysis in QL <../intro-to-data-flow>`.
+For a more general introduction to modeling data flow, see :doc:`Introduction to data flow analysis with CodeQL <../intro-to-data-flow>`.
Local data flow
---------------
@@ -166,6 +166,7 @@ The following predicates are defined in the configuration:
- ``isSource``—defines where data may flow from
- ``isSink``—defines where data may flow to
- ``isBarrier``—optional, restricts the data flow
+- ``isBarrierGuard``—optional, restricts the data flow
- ``isAdditionalFlowStep``—optional, adds additional flow steps
The characteristic predicate ``MyDataFlowConfiguration()`` defines the name of the configuration, so ``"MyDataFlowConfiguration"`` should be replaced by the name of your class.
@@ -204,6 +205,7 @@ The following predicates are defined in the configuration:
- ``isSource``—defines where taint may flow from
- ``isSink``—defines where taint may flow to
- ``isSanitizer``—optional, restricts the taint flow
+- ``isSanitizerGuard``—optional, restricts the taint flow
- ``isAdditionalTaintStep``—optional, adds additional taint steps
Similar to global data flow, the characteristic predicate ``MyTaintTrackingConfiguration()`` defines the unique name of the configuration, so ``"MyTaintTrackingConfiguration"`` should be replaced by the name of your class.
diff --git a/docs/language/learn-ql/cpp/expressions-types.rst b/docs/language/learn-ql/cpp/expressions-types.rst
index d6bd0b2c740..1595d594683 100644
--- a/docs/language/learn-ql/cpp/expressions-types.rst
+++ b/docs/language/learn-ql/cpp/expressions-types.rst
@@ -4,12 +4,12 @@ Tutorial: Expressions, types and statements
Overview
--------
-This topic contains worked examples of how to write queries using the standard QL library classes for C/C++ expressions, types, and statements.
+This topic contains worked examples of how to write queries using the standard CodeQL library classes for C/C++ expressions, types, and statements.
Expressions and types
---------------------
-Each part of an expression in C becomes an instance of the QL ``Expr`` class. For example, the C code ``x = x + 1`` becomes an ``AssignExpr``, an ``AddExpr``, two instances of ``VariableAccess`` and a ``Literal``. All of these QL classes extend ``Expr``.
+Each part of an expression in C becomes an instance of the ``Expr`` class. For example, the C code ``x = x + 1`` becomes an ``AssignExpr``, an ``AddExpr``, two instances of ``VariableAccess`` and a ``Literal``. All of these CodeQL classes extend ``Expr``.
Finding assignments to zero
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -26,7 +26,7 @@ In the following example we find instances of ``AssignExpr`` which assign the co
➤ `See this in the query console `__
-The ``where`` clause in this example gets the expression on the right side of the assignment, ``getRValue()``, and compares it with zero. Notice that there are no checks to make sure that the right side of the assignment is an integer or that it has a value (that is, it is compile-time constant, rather than a variable). For expressions where either of these assumptions is wrong, the associated QL predicate simply does not return anything and the ``where`` clause will not produce a result. You could think of it as if there is an implicit ``exists(e.getRValue().getValue().toInt())`` at the beginning of this line.
+The ``where`` clause in this example gets the expression on the right side of the assignment, ``getRValue()``, and compares it with zero. Notice that there are no checks to make sure that the right side of the assignment is an integer or that it has a value (that is, it is compile-time constant, rather than a variable). For expressions where either of these assumptions is wrong, the associated predicate simply does not return anything and the ``where`` clause will not produce a result. You could think of it as if there is an implicit ``exists(e.getRValue().getValue().toInt())`` at the beginning of this line.
It is also worth noting that the query above would find this C code:
@@ -34,7 +34,7 @@ It is also worth noting that the query above would find this C code:
yPtr = NULL;
-This is because the snapshot contains a representation of the code base after the preprocessor transforms have run (for more information, see `Database generation `__). This means that any macro invocations, such as the ``NULL`` define used here, are expanded during the creation of the snapshot. If you want to write queries about macros then there are some special library classes that have been designed specifically for this purpose (for example, the ``Macro``, ``MacroInvocation`` classes and predicates like ``Element.isInMacroExpansion()``). In this case, it is good that macros are expanded, but we do not want to find assignments to pointers.
+This is because the database contains a representation of the code base after the preprocessor transforms have run (for more information, see `Database generation `__). This means that any macro invocations, such as the ``NULL`` define used here, are expanded during the creation of the database. If you want to write queries about macros then there are some special library classes that have been designed specifically for this purpose (for example, the ``Macro``, ``MacroInvocation`` classes and predicates like ``Element.isInMacroExpansion()``). In this case, it is good that macros are expanded, but we do not want to find assignments to pointers.
Finding assignments of 0 to an integer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/language/learn-ql/cpp/function-classes.rst b/docs/language/learn-ql/cpp/function-classes.rst
index e8f0f743722..51f07a8d0f0 100644
--- a/docs/language/learn-ql/cpp/function-classes.rst
+++ b/docs/language/learn-ql/cpp/function-classes.rst
@@ -4,14 +4,14 @@ Tutorial: Function classes
Overview
--------
-The standard QL library for C and C++ represents functions using the ``Function`` class (see :doc:`Introducing the C/C++ libraries `).
+The standard CodeQL library for C and C++ represents functions using the ``Function`` class (see :doc:`Introducing the C/C++ libraries `).
The example queries in this topic explore some of the most useful library predicates for querying functions.
Finding all static functions
----------------------------
-Using the member predicate ``Function.isStatic()`` we can list all of the static functions in a snapshot:
+Using the member predicate ``Function.isStatic()`` we can list all the static functions in a database:
.. code-block:: ql
@@ -26,7 +26,7 @@ This query is very general, so there are probably too many results to be interes
Finding functions that are not called
-------------------------------------
-It might be more interesting to find functions that are not called, using the standard QL ``FunctionCall`` class from the **abstract syntax tree** category (see :doc:`Introducing the C/C++ libraries `). The ``FunctionCall`` class can be used to identify places where a function is actually used, and it is related to ``Function`` through the ``FunctionCall.getTarget()`` predicate.
+It might be more interesting to find functions that are not called, using the standard CodeQL ``FunctionCall`` class from the **abstract syntax tree** category (see :doc:`Introducing the C/C++ libraries `). The ``FunctionCall`` class can be used to identify places where a function is actually used, and it is related to ``Function`` through the ``FunctionCall.getTarget()`` predicate.
.. code-block:: ql
@@ -58,9 +58,9 @@ You can modify the query to remove functions where a function pointer is used to
This query returns fewer results. However, if you examine the results then you can probably still find potential refinements.
-For example, there is a more complicated LGTM `query `__ that finds unused static functions. To see the QL code for this query, click **Open in query console** at the top of the page.
+For example, there is a more complicated LGTM `query `__ that finds unused static functions. To see the code for this query, click **Open in query console** at the top of the page.
- You can explore the definition of an element in the standard QL libraries and see what predicates are available. Use the keyboard **F3** button to open the definition of any element. Alternatively, hover over the element and click **Jump to definition** in the tooltip displayed. The library file is opened in a new tab with the definition highlighted.
+ You can explore the definition of an element in the standard libraries and see what predicates are available. Use the keyboard **F3** button to open the definition of any element. Alternatively, hover over the element and click **Jump to definition** in the tooltip displayed. The library file is opened in a new tab with the definition highlighted.
Finding a specific function
---------------------------
diff --git a/docs/language/learn-ql/cpp/introduce-libraries-cpp.rst b/docs/language/learn-ql/cpp/introduce-libraries-cpp.rst
index 1ab7cdd1498..6bea8d40c2c 100644
--- a/docs/language/learn-ql/cpp/introduce-libraries-cpp.rst
+++ b/docs/language/learn-ql/cpp/introduce-libraries-cpp.rst
@@ -1,23 +1,23 @@
-Introducing the C/C++ libraries
-===============================
+Introducing the CodeQL libraries for C/C++
+==========================================
Overview
--------
-There is an extensive QL library for analyzing snapshots extracted from C/C++ projects. The QL classes in this library present the data from a snapshot database in an object-oriented form and provide abstractions and predicates to help you with common analysis tasks. The library is implemented as a set of QL modules, that is, files with the extension ``.qll``. The module ``cpp.qll`` imports all of the core C/C++ library modules, so you can include the complete library by beginning your query with:
+There is an extensive library for analyzing CodeQL databases extracted from C/C++ projects. The classes in this library present the data from a database in an object-oriented form and provide abstractions and predicates to help you with common analysis tasks. The library is implemented as a set of QL modules, that is, files with the extension ``.qll``. The module ``cpp.qll`` imports all the core C/C++ library modules, so you can include the complete library by beginning your query with:
.. code-block:: ql
import cpp
-The rest of this topic summarizes available QL classes and corresponding C/C++ constructs.
+The rest of this topic summarizes the available CodeQL classes and corresponding C/C++ constructs.
-NOTE: You can find related classes and features using the query console's auto-complete feature. You can also press *F3* to jump to the definition of any element; QL library files are opened in new tabs in the console.
+NOTE: You can find related classes and features using the query console's auto-complete feature. You can also press *F3* to jump to the definition of any element; library files are opened in new tabs in the console.
Summary of the library classes
------------------------------
-The most commonly used standard QL library classes are listed below. The listing is broken down by functionality. Each QL library class is annotated with a C/C++ construct it corresponds to.
+The most commonly used standard library classes are listed below. The listing is broken down by functionality. Each library class is annotated with a C/C++ construct it corresponds to.
Declaration classes
~~~~~~~~~~~~~~~~~~~
@@ -25,7 +25,7 @@ Declaration classes
This table lists `Declaration `__ classes representing C/C++ declarations.
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Example syntax | QL class | Remarks |
+| Example syntax | CodeQL class | Remarks |
+=================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+=======================================================================================================================================================================+====================================================================================================================================================================================================+
| ``int`` *var* ``;`` | `GlobalVariable `__ | |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -154,7 +154,7 @@ Statement classes
This table lists subclasses of `Stmt `__ representing C/C++ statements.
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Example syntax | QL class | Remarks |
+| Example syntax | CodeQL class | Remarks |
+===============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+==================================================================================================================================================================+===================================================================================================================================================================================================================================================================================================+
| ``__asm__ ("`` *movb %bh, (%eax)* ``");`` | `AsmStmt `__ | Specific to a given CPU instruction set |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -215,7 +215,7 @@ Expression classes
This table lists subclasses of `Expr `__ representing C/C++ expressions.
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Example syntax | QL class(es) | Remarks |
+| Example syntax | CodeQL class(es) | Remarks |
+========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+==========================================================================================================================================================================================================+=============================================================================================================================================================================================================================================================================================================+
| ``{`` `Expr `__... ``}`` | | `ArrayAggregateLiteral `__ | |
| | | `ClassAggregateLiteral `__ | |
@@ -417,7 +417,7 @@ Type classes
This table lists subclasses of `Type `__ representing C/C++ types.
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Example syntax | QL class | Remarks |
+| Example syntax | CodeQL class | Remarks |
+=============================================================================================================================================================================================================================================================================================================================================================================================================================================+==================================================================================================================================================================+==================================================================================================================================================================================================================================================================================+
| ``void`` | `VoidType `__ | |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -485,7 +485,7 @@ Preprocessor classes
This table lists `Preprocessor `__ classes representing C/C++ preprocessing directives.
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Example syntax | QL class | Remarks |
+| Example syntax | CodeQL class | Remarks |
+=============================================================================================================================================================================================================================================================================================================================================================================================================================================+==================================================================================================================================================================+===================================================================================================================================================================================================================================================================================+
| ``#elif`` *condition* | `PreprocessorElif `__ | |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -522,6 +522,6 @@ This table lists `Preprocessor `, :doc:`Expressions, types and statements `, :doc:`Conversions and classes `, and :doc:`Analyzing data flow in C/C++ `.
+- Experiment with the worked examples in the CodeQL for C/C++ topics: :doc:`Function classes `, :doc:`Expressions, types and statements `, :doc:`Conversions and classes `, and :doc:`Analyzing data flow in C/C++ `.
- Find out more about QL in the `QL language handbook `__ and `QL language specification `__.
- Learn more about the query console in `Using the query console `__.
diff --git a/docs/language/learn-ql/cpp/private-field-initialization.rst b/docs/language/learn-ql/cpp/private-field-initialization.rst
index 4aa155adeb0..26b57660142 100644
--- a/docs/language/learn-ql/cpp/private-field-initialization.rst
+++ b/docs/language/learn-ql/cpp/private-field-initialization.rst
@@ -4,7 +4,7 @@ Example: Checking that constructors initialize all private fields
Overview
--------
-This topic describes how a C++ query was developed. The example introduces recursive predicates and demonstrates the typical workflow used to refine a query. For a full overview of the topics available for learning to write QL queries for C/C++ code, see :doc:`QL for C/C++ `.
+This topic describes how a C++ query was developed. The example introduces recursive predicates and demonstrates the typical workflow used to refine a query. For a full overview of the topics available for learning to write queries for C/C++ code, see :doc:`CodeQL for C/C++ `.
Problem—finding every private field and checking for initialization
-------------------------------------------------------------------
@@ -29,7 +29,7 @@ We can start by looking at every private field in a class and checking that ever
#. ``f.isPrivate()`` checks if the field is private.
#. ``not exists(Assignment a | a = f.getAnAssignment() and a.getEnclosingFunction() = c)`` checks that there is no assignment to the field in the constructor.
-This QL code looks fairly complete, but when you test it on a project, there are several results that contain examples that we have overlooked.
+This code looks fairly complete, but when you test it on a project, there are several results that contain examples that we have overlooked.
Refinement 1—excluding fields initialized by lists
--------------------------------------------------
@@ -62,7 +62,7 @@ These can be excluded by adding an extra condition to check for this special con
Refinement 2—excluding fields initialized by external libraries
---------------------------------------------------------------
-When you test the revised query, you may discover that fields from classes in external libraries are over-reported. This is often because a header file declares a constructor that is defined in a source file that is not analyzed (external libraries are often excluded from analysis). When the source code is analyzed, the snapshot is populated with a ``Constructor`` entry with no body. This ``constructor`` therefore contains no assignments and consequently the query reports that any fields initialized by the constructor are "uninitialized." There is no particular reason to be suspicious of these cases, and we can exclude them from the results by defining a condition to exclude constructors that have no body:
+When you test the revised query, you may discover that fields from classes in external libraries are over-reported. This is often because a header file declares a constructor that is defined in a source file that is not analyzed (external libraries are often excluded from analysis). When the source code is analyzed, the CodeQL database is populated with a ``Constructor`` entry with no body. This ``constructor`` therefore contains no assignments and consequently the query reports that any fields initialized by the constructor are "uninitialized." There is no particular reason to be suspicious of these cases, and we can exclude them from the results by defining a condition to exclude constructors that have no body:
.. code-block:: ql
diff --git a/docs/language/learn-ql/cpp/ql-for-cpp.rst b/docs/language/learn-ql/cpp/ql-for-cpp.rst
index 909d0e2e323..b1596c7de92 100644
--- a/docs/language/learn-ql/cpp/ql-for-cpp.rst
+++ b/docs/language/learn-ql/cpp/ql-for-cpp.rst
@@ -1,5 +1,5 @@
-QL for C/C++
-============
+CodeQL for C/C++
+================
.. toctree::
:glob:
@@ -13,19 +13,19 @@ QL for C/C++
private-field-initialization
zero-space-terminator
-These topics provide an overview of the QL C/C++ standard libraries and show examples of how to write queries that use them.
+These topics provide an overview of the CodeQL libraries for C/C++ and show examples of how to write queries that use them.
-- `Basic C/C++ QL query `__ describes how to write and run queries using LGTM.
+- `Basic C/C++ query `__ describes how to write and run queries using LGTM.
-- :doc:`Introducing the QL libraries for C/C++ ` introduces the standard libraries used to write queries for C and C++ code.
+- :doc:`Introducing the CodeQL libraries for C/C++ ` introduces the standard libraries used to write queries for C and C++ code.
-- :doc:`Tutorial: Function classes ` demonstrates how to write queries using the standard QL library classes for C/C++ functions.
+- :doc:`Tutorial: Function classes ` demonstrates how to write queries using the standard CodeQL library classes for C/C++ functions.
-- :doc:`Tutorial: Expressions, types and statements ` demonstrates how to write queries using the standard QL library classes for C/C++ expressions, types and statements.
+- :doc:`Tutorial: Expressions, types and statements ` demonstrates how to write queries using the standard CodeQL library classes for C/C++ expressions, types and statements.
-- :doc:`Tutorial: Conversions and classes ` demonstrates how to write queries using the standard QL library classes for C/C++ conversions and classes.
+- :doc:`Tutorial: Conversions and classes ` demonstrates how to write queries using the standard CodeQL library classes for C/C++ conversions and classes.
-- :doc:`Tutorial: Analyzing data flow in C/C++ ` demonstrates how to write queries using the standard QL for C/C++ data flow and taint tracking libraries.
+- :doc:`Tutorial: Analyzing data flow in C/C++ ` demonstrates how to write queries using the standard data flow and taint tracking libraries for C/C++.
- :doc:`Example: Checking that constructors initialize all private fields ` works through the development of a query. It introduces recursive predicates and shows the typical workflow used to refine a query.
@@ -51,6 +51,8 @@ Advanced libraries
Other resources
---------------
-- For examples of how to query common C/C++ elements, see the `C/C++ QL cookbook `__.
-- For the queries used in LGTM, display a `C/C++ query `__ and click **Open in query console** to see the QL code used to find alerts.
-- For more information about the C/C++ QL library see the `QL library for C/C++ `__.
+.. TODO: Rename the cookbooks: C/C++ cookbook, or C/C++ CodeQL cookbook, or CodeQL cookbook for C/C++, or...?
+
+- For examples of how to query common C/C++ elements, see the `C/C++ cookbook `__.
+- For the queries used in LGTM, display a `C/C++ query `__ and click **Open in query console** to see the code used to find alerts.
+- For more information about the library for C/C++ see the `CodeQL library for C/C++ `__.
diff --git a/docs/language/learn-ql/cpp/value-numbering-hash-cons.rst b/docs/language/learn-ql/cpp/value-numbering-hash-cons.rst
index 7a1bbd2888b..e05f93dbae1 100644
--- a/docs/language/learn-ql/cpp/value-numbering-hash-cons.rst
+++ b/docs/language/learn-ql/cpp/value-numbering-hash-cons.rst
@@ -4,7 +4,7 @@ Hash consing and value numbering
Overview
--------
-In C and C++ QL databases, each node in the abstract syntax tree is represented by a separate object. This allows both analysis and results display to refer to specific appearances of a piece of syntax. However, it is frequently useful to determine whether two expressions are equivalent, either syntactically or semantically.
+In C and C++ databases, each node in the abstract syntax tree is represented by a separate object. This allows both analysis and results display to refer to specific appearances of a piece of syntax. However, it is frequently useful to determine whether two expressions are equivalent, either syntactically or semantically.
The `hash consing `__ library (defined in ``semmle.code.cpp.valuenumbering.HashCons``) provides a mechanism for identifying expressions that have the same syntactic structure. The `global value numbering `__ library (defined in ``semmle.code.cpp.valuenumbering.GlobalValueNumbering``) provides a mechanism for identifying expressions that compute the same value at runtime.
diff --git a/docs/language/learn-ql/cpp/zero-space-terminator.rst b/docs/language/learn-ql/cpp/zero-space-terminator.rst
index e977470ea6f..7026d9fa9ae 100644
--- a/docs/language/learn-ql/cpp/zero-space-terminator.rst
+++ b/docs/language/learn-ql/cpp/zero-space-terminator.rst
@@ -4,7 +4,7 @@ Example: Checking for allocations equal to ``strlen(string)`` without space for
Overview
--------
-This topic describes how a C/C++ query for detecting a potential buffer overflow was developed. For a full overview of the topics available for learning to write QL queries for C/C++ code, see :doc:`QL for C/C++ `.
+This topic describes how a C/C++ query for detecting a potential buffer overflow was developed. For a full overview of the topics available for learning to write queries for C/C++ code, see :doc:`CodeQL for C/C++ `.
Problem—detecting memory allocation that omits space for a null termination character
-------------------------------------------------------------------------------------
@@ -32,7 +32,7 @@ Defining the entities of interest
You could approach this problem either by searching for code similar to the call to ``malloc`` in line 3 or the call to ``strcpy`` in line 5 (see example above). For our basic query, we start with a simple assumption: any call to ``malloc`` with only a ``strlen`` to define the memory size is likely to cause an error when the memory is populated.
-Calls to ``strlen`` can be identified using the library `StrlenCall `__ class, but we need to define a new class to identify calls to ``malloc``. Both the library class and the new class need to extend the standard QL class ``FunctionCall``, with the added restriction of the function name that they apply to:
+Calls to ``strlen`` can be identified using the library `StrlenCall `__ class, but we need to define a new class to identify calls to ``malloc``. Both the library class and the new class need to extend the standard class ``FunctionCall``, with the added restriction of the function name that they apply to:
.. code-block:: ql
@@ -52,7 +52,7 @@ Calls to ``strlen`` can be identified using the library `StrlenCall `.
+For a more general introduction to modeling data flow, see :doc:`Introduction to data flow analysis with CodeQL <../intro-to-data-flow>`.
Local data flow
---------------
@@ -548,6 +548,6 @@ This can be adapted from the ``SystemUriFlow`` class:
What next?
----------
-- Learn about the QL standard libraries used to write queries for C# in :doc:`Introducing the C# libraries `.
+- Learn about the standard libraries used to write queries for C# in :doc:`Introducing the C# libraries `.
- Find out more about QL in the `QL language handbook `__ and `QL language specification `__.
- Learn more about the query console in `Using the query console `__.
diff --git a/docs/language/learn-ql/csharp/introduce-libraries-csharp.rst b/docs/language/learn-ql/csharp/introduce-libraries-csharp.rst
index 43e6c11327c..32a782d5034 100644
--- a/docs/language/learn-ql/csharp/introduce-libraries-csharp.rst
+++ b/docs/language/learn-ql/csharp/introduce-libraries-csharp.rst
@@ -1,25 +1,23 @@
-Introducing the C# libraries
-============================
+Introducing the CodeQL libraries for C#
+=======================================
Overview
--------
-The C# QL libraries are a data model for analysis of C# code. QL is an object-oriented language, so the data model is represented as *QL classes*, which are organized into *QL libraries*. The QL classes are a layer of logic built on top of an underlying database.
-
-The core library is imported at the top of each query using:
+There is an extensive library for analyzing CodeQL databases extracted from C# projects. The classes in this library present the data from a database in an object-oriented form and provide abstractions and predicates to help you with common analysis tasks. The library is implemented as a set of QL modules, that is, files with the extension ``.qll``. The module ``csharp.qll`` imports all the core C# library modules, so you can include the complete library by beginning your query with:
.. code-block:: ql
import csharp
-Since this is required for all C# queries, it is omitted from QL snippets below.
+Since this is required for all C# queries, it is omitted from code snippets below.
-The core library contains all the program elements, including `files <#files>`__, `types <#types>`__, methods, `variables <#variables>`__, `statements <#statements>`__, and `expressions <#expressions>`__. This is sufficient for most queries, however additional libraries can be imported for bespoke functionality such as control flow and data flow. See :doc:`QL for C# ` for information about these additional libraries.
+The core library contains all the program elements, including `files <#files>`__, `types <#types>`__, methods, `variables <#variables>`__, `statements <#statements>`__, and `expressions <#expressions>`__. This is sufficient for most queries, however additional libraries can be imported for bespoke functionality such as control flow and data flow. See :doc:`CodeQL for C# ` for information about these additional libraries.
Class hierarchies
~~~~~~~~~~~~~~~~~
-Each section contains a QL class hierarchy, showing the inheritance structure between QL classes. For example:
+Each section contains a class hierarchy, showing the inheritance structure between CodeQL classes. For example:
- ``Expr``
@@ -46,13 +44,13 @@ Each section contains a QL class hierarchy, showing the inheritance structure be
This means that the class ``AddExpr`` extends class ``BinaryArithmeticOperation``, which in turn extends class ``ArithmeticOperation`` and so on. If you want to query any arithmetic operation, then use the class ``ArithmeticOperation``, but if you specifically want to limit the query to addition operations, then use the class ``AddExpr``.
-QL classes can also be considered to be *sets*, and the ``extends`` relation between classes defines a subset. Every member of class ``AddExpr`` is also in the class ``BinaryArithmeticOperation``. In general, QL classes overlap and an entity can be a member of several classes.
+Classes can also be considered to be *sets*, and the ``extends`` relation between classes defines a subset. Every member of class ``AddExpr`` is also in the class ``BinaryArithmeticOperation``. In general, classes overlap and an entity can be a member of several classes.
This overview omits some of the less important or intermediate classes from the class hierarchy.
Each class has predicates, which are logical propositions about that class. They also define navigable relationships between classes. Predicates are inherited, so for example the ``AddExpr`` class inherits the predicates ``getLeftOperand()`` and ``getRightOperand()`` from ``BinaryArithmeticOperation``, and ``getType()`` from class ``Expr``. This is similar to how methods are inherited in object-oriented programming languages.
-In this overview, we present the most common and useful predicates. Consult the reference, QL source code, and autocomplete in the editor for the complete list of predicates available on each class.
+In this overview, we present the most common and useful predicates. Consult the `reference `__, the CodeQL source code, and autocomplete in the editor for the complete list of predicates available on each class.
Exercises
~~~~~~~~~
@@ -72,7 +70,7 @@ Exercise 1: Simplify the following query:
Files
-----
-Files are represented by the QL class `File `__, and directories by the QL class `Folder `__. The database contains all of the source files and assemblies used during the compilation.
+Files are represented by the class `File `__, and directories by the class `Folder `__. The database contains all of the source files and assemblies used during the compilation.
Class hierarchy
~~~~~~~~~~~~~~~
@@ -143,7 +141,7 @@ To list all elements in ``Main.cs``, their QL class and location:
where e.getFile().getShortName() = "Main"
select e, e.getAQlClass(), e.getLocation()
-Note that ``getAQlClass()`` is available on all QL classes and is a useful way to figure out the QL class of something. Often the same element will have several QL classes which are all returned by ``getAQlClass()``.
+Note that ``getAQlClass()`` is available on all entities and is a useful way to figure out the QL class of something. Often the same element will have several classes which are all returned by ``getAQlClass()``.
Locations
---------
@@ -234,7 +232,7 @@ Find declarations containing a username:
Variables
---------
-The QL class `Variable `__ represents C# variables, such as fields, parameters and local variables. The database contains all variables from the source code, as well as all fields and parameters from assemblies referenced by the program.
+The class `Variable `__ represents C# variables, such as fields, parameters and local variables. The database contains all variables from the source code, as well as all fields and parameters from assemblies referenced by the program.
Class hierarchy
~~~~~~~~~~~~~~~
@@ -283,7 +281,7 @@ Find all unused local variables:
Types
-----
-Types are represented by the QL class `Type `__ and consist of builtin types, interfaces, classes, structs, enums, and type parameters. The database contains types from the program and all referenced assemblies including mscorlib and the .NET framework.
+Types are represented by the CodeQL class `Type