ECLAIR User’s Manual

About ECLAIR

The development of high-quality software is a tough task: ECLAIR has been designed to assist development and quality assurance teams to achieve that quality, as well as helping quality control teams assess its achievement.

What ECLAIR Is

ECLAIR is a powerful platform for the automatic analysis, verification, testing and transformation of C and C++ programs (with extensions to Java source code and bytecode, and possible extension to other languages).

ECLAIR is very flexible and highly configurable. It can support your software development workflow and environment, whatever they are.

ECLAIR is suitable for light verification tasks that can be run right on the developer’s desktop, as well as for tough semantics-based analyses to be run overnight.

ECLAIR is fit for use in mission- and safety-critical software projects: it has been designed from the outset to exclude false negatives unless the user’s configuration asks for them.

ECLAIR is developed in a rigorous way and carefully checked with extensive internal test suites (numbering tens of thousands of testcases) and industry-standard validation suites (such as Solid Sands SuperTest and The Plum Hall Validation Suite for C).

ECLAIR is based on solid scientific research results and on the best practices of software development.

ECLAIR is developed by a passionate team of experts. Please, do not hesitate to let us have your feedback: you may be surprised to discover just how much your suggestions matter to us.

What ECLAIR Is Not

ECLAIR is not something that will tell you which software analysis, verification and testing activities are appropriate in your field. In particular, it cannot tell you which coding rules are suited to your project. However, the programming language experts at BUGSENG can provide significant help in this respect.

ECLAIR is not a substitute for project management, even though it can be adapted to any software development practice, process and methodology.

ECLAIR Features at a Glance

Note

ECLAIR is a platform for software verification. The platform is instantiated, released and licensed in many different ways depending on the precise needs of each customer. The following description of ECLAIR features is completely general and does not necessarily reflect the functionality of the ECLAIR instance that was licensed to you: see your license for the applicable details.

Automatic Checking of Coding Standards

ECLAIR provides support for automatically checking conformance with respect to a number of widely-used coding standards, including:

  • MISRA-C:1998 [60];

  • MISRA-C:2004 [62];

  • MISRA C:2012 [43];

  • MISRA C:2023 [57];

  • MISRA C:2025 [59];

  • MISRA C++:2008 [64];

  • MISRA C++:2023 [55];

  • AUTOSAR C [24]

  • Barr Group C [7];

  • C Secure:2016 [37];

  • CERT C:2016 [26];

  • ESA/BSSC C/C++ [13];

  • NASA/JPL C [2];

  • The Power of Ten (C) [17].

In addition to these, BUGSENG has developed checkers to verify conformance with respect to several other coding standards, including proprietary company standards and project-specific standards. Coding rules are checked with very general and accurate checkers, which operate on the precise sequences of tokens and abstract syntax trees that are manipulated by the compiler.

Coupled with the fact that ECLAIR always checks each rule in the appropriate context (at the token, declaration, translation unit, whole program or whole system levels), this makes sure that the checkers for decidable rules are exact (neither false positives nor false negatives). For undecidable rules, ECLAIR provides different checkers characterized by different solutions to the tradeoff among computational complexity, number of false positives and number of false negatives [5]. In any case, when false negatives are possible, they are always clearly and unambiguously delimited.

This is in sharp contrast with checkers that are based on pattern matching and imprecise parsing. If, on the one hand, they can deal with programs that do not compile, on the other hand they are plagued by a high number of false positives and, most importantly, false negatives, something that makes them unsuitable to safety-critical and mission-critical contexts. Generally speaking, beware of tools based on obsolete technology: directives such as 90/385/EEC and 93/42/EEC in the medical sector assert that compliance can only be claimed if the generally acknowledged state-of-the-art is followed.

ECLAIR can be configured to produce a variety of outputs:

  • for immediate or later browsing using the very powerful ECLAIR-integrated web-based browser;

  • for immediate browsing, with certain license kinds, in popular IDEs like Eclipse or Microsoft Visual Studio®, MPLAB® X IDE, NetBeans, IAR Embedded Workbench®, IntelliJ IDEA, CLion, Texas Instruments Code Composer Studio™, Visual Studio Code, Keil μVision®, or any suitable editor;

  • for the automatic insertion into issue-tracking systems or any other database;

  • for the automatic production of compliance matrices required to meet industrial standards and guidelines such as IEC 61508, ISO 26262 (automotive), CENELEC EN 50128/50657/50716 (railways), DO-178B/C (aerospace), IEC 60880 (nuclear power), IEC 62304 and FDA norms (medical), ISO 19014 (earth-moving machinery), ISO 25119 (tractors and machinery for agriculture and forestry).

Metrics

For assessing the complexity, readability and maintainability of software, ECLAIR provides comprehensive metrics about the code including the fundamental set defined by the HIS Source Code Metrics [12] document and many of the requirements of the SQALE Method [19] quality model. These measures may be incrementally reported, showing exactly where in the code the value was computed, or aggregated (e.g., maximized, summed, averaged) over a single function, translation unit, program or the whole project.

Semantic Analysis

ECLAIR is equipped with powerful constraint propagation, symbolic model checking, and abstract interpretation engines. Their combined use allows different compromises between computational complexity and precision, so that users can select an optimal cost-benefit tradeoff with respect to their objectives. On the developer’s desktop, only quick analyses are appropriate; but when the alternative is between, e.g., proving absence of run-time errors by hand or by machine, 12 hours of computation time is nothing: ECLAIR has been designed to support the entire spectrum between these two extremes.

Automatic Unit Test Case Generation

ECLAIR can automatically synthesize minimal sets of unit test inputs that reach a specified coverage criterion (or prove that such coverage cannot be reached due to unfeasible conditions in the program). If a human or mechanized “oracle” is available to predict the expected output, then complete unit tests can be synthesized in a fraction of the time required for manual generation.

Requirements Management

ECLAIR provides the means to enforce traceability between requirements and source code through the service B.REQMAN, helping projects meet compliance demands from rigorous software development standards.

Architectural Constraints Management

ECLAIR helps managing complex software projects with architectural and safety constraints. Through its service B.INDEPENDENCE, it enables fine-grained configuration of project structure by defining components and specifying constraints, permissions, and actions between them.

Compiler Qualification

ECLAIR supports compiler qualification with the CerTran extension, which automates the generation of test configuration files based on a scan of the application’s build process. This ensures comprehensive use-case coverage and minimizes manual error.

Other Applications

Semantic matchers and patchers, simplifiers, obfuscators, translators, … these are just a few examples of the plethora of applications that, because of ECLAIR’s highly modular design, can be developed relatively easily at the right level of abstraction.

Proper Integration with the Toolchain

ECLAIR intercepts every invocation of the toolchain components (compilers, linker, assembler, archive manager) and it automatically extracts and interprets the options that the build system has passed to them. This allows for the seamless integration with any build system. Moreover, the user does not need to engage in error-prone activities such as:

  • specifying which files compose the application and where the right header files are located;

  • configuring the static analyzer so that the analysis parameters match the options given to the compilers (several options do affect the program semantics).

All this is automatic and supports build processes that involve the automatic generation of source files that depend on the configuration, without requiring the development and maintenance of a separated analysis procedure: with ECLAIR the existing build procedure can be used verbatim.

One of the key properties of ECLAIR is that it understands all the analysis-relevant options of the supported compilers. The language used to abstractly model such options is so powerful that adding support for a new compiler is no longer a problem.

Web-Based Configuration Interface

All the verification tasks supported by ECLAIR can be specified and refined incrementally by means of a very convenient graphical user interface.

Precise Parsing of Source Files

ECLAIR includes a state-of-the-art parser for C and C++ languages. In particular, for:

  • the pre-standardization K&R C dialect [18];

  • the standardized C languages: C90 [28, 29], C99 [31, 33], C11 [35] and C17/C18 [39], as well as a good portion of C23/C24 [42];

  • the standardized C++ languages: C++98 [30], C++03 [32], C++11 [34], C++14 [36] and C++17 [38], as well as a good portion of C++20 [40] and C++23/C++24 [41]);

  • the language extensions of the GNU C/C++ dialects;

  • the language extensions of the Microsoft C/C++ dialects.

The parser produces an accurate abstract syntax tree (AST) representing all of the information available in the analyzed code. Accuracy means, among other things, that:

  • the AST represents not only the explicit, but also all of the implicit language constructs in the source code: implicit type conversions, compiler-generated functions (e.g., for constructors and destructors), instantiations of function/class templates, etc.;

  • all language constructs are provided with precise location information, enabling the generation of reports to point to the exact sources.

Source location information is not only precise, but also thorough:

  • complete information is available for the chain of file inclusions and, orthogonally, for the chain of macro expansions that enable a lexical token (in the written program) to become a part of the analyzed source code;

  • the well-known difficulty of tracking problems in implicit template instantiations is solved presenting to the user complete yet easily readable information about the full instantiation chain.

Supported Platforms and Development Environments

ECLAIR is available on most modern flavors of UNIX®, Linux, macOS® and Windows®, including Cygwin and MinGW, and can be used with just about any development environment. Thanks to its ability to intercept the toolchain components, it supports virtually any makefile-based, script-based or hybrid build systems. ECLAIR can leverage the availability of computing resources by supporting parallel and distributed program analyses. Most popular C/C++ compilers and cross compilers are supported, including ARM®, CAES™, CodeWarrior™, Cosmic Software, CrossWorks™, Emscripten, Espressif™, GCC and its derivatives, Green Hills®, HighTec, IAR™, Intel®, Keil Software®, Microsoft®, MPLAB®, QNX™, Renesas Electronics, SOFTUNE™, TASKING®, Texas Instruments™, Wind River®, Xilinx™, as well as clang/LLVM and its derivatives.

ECLAIR Is Protected Commercial Software

The entire ECLAIR system is protected commercial software owned by BUGSENG srl. Any reproduction or redistribution of any part of the ECLAIR system not in accordance with the License Agreement is expressly prohibited by law, and may result in severe civil and criminal penalties. Violators will be prosecuted to the maximum extent possible.

Without limiting the foregoing, copying or reproduction of any part of the ECLAIR system to any server or location for further reproduction or redistribution is expressly prohibited. The extensive and systematic use of digital watermarking techniques ensures that each delivered version of ECLAIR, or part thereof, can always be traced back to the original authorized recipient.

Disclaimer

Nobody Can Prove that an Arbitrary Program is Bug-Free

Consider the following C/C++ function:

 1typedef unsigned long T_uint64;
 2
 3T_uint64 gcd(T_uint64 a, T_uint64 b);
 4
 5T_uint64 gcd(T_uint64 a, T_uint64 b) {
 6  if (a != 0UL) {
 7    while (b != 0UL) {
 8      if (a > b) {
 9        a = a - b;
10      }
11      else {
12        b = b - a;
13      }
14    }
15  }
16  return a;
17}

The above function is probably meant to compute the greatest common divisor of two numbers… or perhaps the general content descriptor of… or maybe something related to the grand central dispatch… who can know for sure? Certainly ECLAIR can’t. When given the above piece of code (and nothing else) a suitable version of ECLAIR can do the following, if configured to that effect:

  • check that the code conforms to widely adopted, industrial-strength sets of coding rules;

  • check that the code does not give rise to integer overflows (which, even though well-defined for unsigned integers, are often unwanted);

  • check that some specified assumptions always hold;

  • check that gcd(x, y) will always terminate, no matter what the value of x and y might be;

  • generate unit tests that will satisfy a user-specified coverage criterion.

So, in general, ECLAIR will be able to check the consistency between the code itself or its behavior and some explicitly specified expectations. Although this leads to a dramatic reduction in the number of bugs and helps produce the best possible software, it is not a proof that the program or the expectations are bug-free. Indeed, proving that an arbitrary program is bug-free is an unfeasible task (this was established in the 1930s by Kurt Gödel and Alan Turing).

The moral is: beware of a false sense of security that might result from the use of a powerful tool like ECLAIR. ECLAIR can do a lot to help you making your software safe and secure, but it cannot prove that your software is bug-free.

False Positives and False Negatives

All the users of all program analysis tools may be confronted with a false positive or a false negative.

These may be due to a misunderstanding between the user and those who designed or configured the tool. In many cases the misunderstanding is neither the fault of the user nor of the designers/configurators; just note that all versions of the C and C++ standards have hundreds of documented ambiguities and that most coding rules are ambiguous as well and a constant subject of debate.

False positives and negatives may also be due to fundamental laws of nature: most interesting semantic properties of programs are undecidable so that no tool can avoid both false positives and false negatives for those properties [5]. In other words, those properties can only be approximated. Depending on the application and the desired cost/precision tradeoff two kinds of approximations are commonly employed:

  • quick-to-compute ones possibly resulting into false negatives but no false positive;

  • more expensive ones possibly resulting into false positives but no false negatives.

As an example, consider flagging the presence of unreachable code. Since the termination of loops is undecidable there will never be a tool that will flag all, and only all unreachable code in arbitrary programs. But one can:

  • find some definitely unreachable code using quick syntactic analyses (e.g., a statement immediately following a return statement is unreachable) and ignore loops, either by remaining silent about them (resulting into false negatives) or by flagging all code immediately following them as possibly unreachable (resulting into false posities);

  • do a deep semantic analysis of loops which, despite its depth, will by necessity be inconclusive for some loops and the tool will either flag the code immediately following them as possibly unreachable (resulting, again, into false positives), or not flag it (resulting, again, into false negatives).

Summarizing, the user should be aware of the properties of the checker and of the configuration chosen to analyze the program. Note also that there is a fundamental asymmetry between false positives and false negatives: you can silence a positive you believe is false, but there is nothing you can do about a false negative.

The Fine Print

For a period of 45 (forty five) days from the date of delivery BUGSENG warrants that the software provided has, to BUGSENG’s knowledge, no code that is intended to damage the software and/or the software systems of the licensee.

BUGSENG warrants that the media used to deliver the software is not defective and that a cryptographic digital signature hash will be communicated to allow the licensee to verify content integrity. If, for a period of 45 days (forty five) from the date of delivery, the software media shall prove to be corrupted, BUGSENG will replace them without charge once received back the original media.

BUGSENG warrants that the software provided to the licensee does not violate third-party rights and that it conforms to specifications contained in present document. All discrepancies between the software provided and the present document that are notified in writing to BUGSENG during the period of validity of the maintenance contract and confirmed by BUGSENG personnel will be corrected without charge and without any licensee indemnification.

These are limited warranties and are the only warranties made by BUGSENG; BUGSENG makes no other express or implicit warranty including, without limitation, warranties of merchantability and of fitness for a particular purpose.

Contact Us

Offices

BUGSENG srl
Via Fiorentina 214/C
I-56121 Pisa (PI)
Italy

Email Addresses

General Information:

info@bugseng.com

Sales Inquiries:

sales@bugseng.com

Technical Support:

support@bugseng.com

Training Inquiries:

training@bugseng.com

Consulting Inquiries:

consulting@bugseng.com

Qualification Inquiries:

qualification@bugseng.com

Evaluation Inquiries:

eval@bugseng.com

Partner Inquiries:

partners@bugseng.com

Job Opportunities:

jobs@bugseng.com

Administration:

admin@bugseng.com

Data Protection and GDPR:

privacy@bugseng.com

Customer Support Portal

http://bugseng.com/ contains more contact options, including authenticated access to the issue-tracking system.

BUGSENG Services

BUGSENG provides, among others, services in the following areas:

Custom Checkers

Development of ECLAIR checkers for the automatic verification of conformance with respect to customer-defined coding rules.

Process Integration

On-line/on-site assistance with the installation of ECLAIR and its integration with the customer’s development and build environments.

Training

On-line/on-site training for software developers, build engineers, quality control staff and tool administrators. Courses are designed to ensure participant engagement and to assist long-term retention; they also come with one month of free remote consultancy on the course topics. As an example, check out the detailed description of the Effective MISRA-C course available at http://bugseng.com/

Software Audit Reviews

Assistance in the definition of coding standards; evaluation of defects in the customer’s or suppliers’ code with respect to coding standards; assistance in the definition of a work plan to gradually bring the code base into conformance.

Complex Software Transformations

Leveraging the power of ECLAIR, assistance with the partial automatization of complex refactorings, including the porting to 64-bit architectures and to Unicode text representations.

Changes from Previous Versions

In this chapter we summarize the main changes to each version of ECLAIR from the version before it. Note that major versions can (and often do) contain incompatible changes, so please make sure to read the following carefully. Please do not hesitate to contact BUGSENG for assistance on the upgrade process.

Summary of Changes from Version 3.15.0 to Version 3.16.0

ECLAIR version 3.16.0 contains some new features, enhancements to existing features, and the correction of a few defects.

Newly supported toolchains (FSSCF):

  • Added support for the IAR RH850 toolchain.

  • Added support for the Green Hills for Arm toolchain.

New features (FSSCF):

  • Added global -rtag; use of this feature introduces a backwards-incompatible change in the generation ECLAIR databases. The latest version of eclair_report will still be able to open databases created with older versions of ECLAIR, unless noted otherwise.

  • Added service B.INEXACT_FLT, for the reporting of floating-point literals that have an inexact representation. Enhanced supported floating point literal suffixes.

  • Added JSON output generation to eclair_report.

Enhancements and corrections of existing features and services (FSSCF):

  • Simplified configuration for services using global -context_selector.

  • Added base matcher save(id, matcher) to globals -type_selector, -decl_selector, -entity_selector and -stmt_selector.

  • Added eclair_report option -files and improved the existing -load option to accept a list of files.

  • Fixed metric definition MET.B.CMNTLINE_JFUNC to count comments in function templates.

  • Fixed false positive for service MP2.15.1.4 due to delegating constructors.

  • Improved support for Clang 20 coverage reports in service B.LLVM_COV.

  • Fixed false positives for service B.NOMAGICC.

  • Improved configurability of service MP2.19.6.1 with additional pragma_matcher and pragma_use configuration options.

  • Improved configurability of service B.INDEPENDENCE and clarified documentation.

Other enhancements and corrections of existing features and services:

  • Improved graphical layout of report summary page.

  • Fixed service description link targets to the HTML version of the ECLAIR User Manual from interactive ECLAIR database browser.

  • Updated eclair_format to a more recent version of uncrustify.

Enhancements to license-enforcing mechanisms:

  • Updated the protection mechanisms to Sentinel LDK 10.3.

Security updates:

  • ECLAIR dependencies were updated to address the following CVEs: OpenSSL: CVE-2025-11187, CVE-2025-15467, CVE-2025-15468, CVE-2025-15469, CVE-2025-66199, CVE-2025-68160, CVE-2025-69418, CVE-2025-69419, CVE-2025-69420, CVE-2025-69421, CVE-2026-22795, CVE-2026-22796, CVE-2026-31790, CVE-2026-2673, CVE-2026-28386, CVE-2026-28387, CVE-2026-28388, CVE-2026-28389, CVE-2026-28390, CVE-2026-31789, CVE-2026-45447, CVE-2026-34182, CVE-2026-34183, CVE-2026-35188, CVE-2026-42764, CVE-2026-45445, CVE-2026-7383, CVE-2026-9076, CVE-2026-34180, CVE-2026-34181, CVE-2026-42765, CVE-2026-42766, CVE-2026-42767, CVE-2026-42768, CVE-2026-42769, CVE-2026-42770, CVE-2026-45446. libxml2: CVE-2025-32415, CVE-2025-32414, CVE-2025-27113, CVE-2025-24928, CVE-2025-6021, CVE-2024-56171, CVE-2024-40896, CVE-2024-34459. libxslt: CVE-2025-7424, CVE-2025-11731 Sentinel LDK: CVE-2026-3457 xz: CVE-2026-34743 sqlite: CVE-2025-70873

Summary of Changes from Version 3.14.0 to Version 3.15.0

ECLAIR version 3.15.0 contains new features, many enhancements to existing features, and the correction of several defects.

Newly supported platforms (FSSCF):

  • Added support for macOS 26/aarch64 (Apple silicon).

  • Added support for Ubuntu 24.04/aarch64.

  • Added support for Deabian 12/aarch64.

  • Added support for AlmaLinux OS 10/x86_64.

  • Added support for Debian 13/x86_64.

  • Added support for Debian 13/aarch64.

Dropped support for obsolete platforms:

  • Dropped support for Windows 8/x86_64 and Windows 8.1/x86_64.

  • Dropped support for all macOS versions prior to 26.

  • Dropped support for Debian 10/x86_64.

  • Dropped support for CentOS 8/x86_64.

New features (FSSCF):

  • New service B.NOMAGICC to detect uses of magic constants (i.e., hard-coded number or strings used directly) without an explanation.

  • New service B.UMACROS to output definitions and expansions of macros for each Single Translation Unit.

  • New tool eclair_code_scout to support preliminary evaluation of library qualification scopes.

  • New output modules for selected services to allow output of information in textual, CSV, JSON, YAML and XML formats.

Enhancements and corrections of existing features and services (FSSCF):

  • The services tagged by the identifier MC.R2.6 take into account uses of labels within asm statements as sources of jumps to the label target.

  • Improved documentation and consistency of base matchers for global -context_selector; several base matchers have been renamed and others have been added.

  • Improved consistency of base matchers in global -type_selector; matchers any_inheritance(), enum_underlying_type() and single_inheritance_hierarchy() have been moved to global -decl_selector.

  • Fixed false positives for services MC.D4.7 (all tagged services),MC.R8.6 (all tagged services), MC.R9.1 (all tagged services), MC.R9.2 (all tagged services), MC4.R16.1, MC4.R16.3, MC.R18.6 (all tagged services), MC.R21.19 (all tagged services), MP2.6.8.4, MP2.5.7.2, MP2.6.9.2, MP2.7.0.5, MP2.7.11.2, MP2.10.2.3, MP2.18.4.1, MP2.21.6.2, MP2.28.6.3.

  • Fixed false negatives for service MP2.8.18.2.

  • Fixed crash for services MC.R21.20 (all tagged services), MP2.4.6.1, MP2.25.5.3.

  • Updated rationale-based classification of MISRA~C services taking into account new MISRA~C:2025 services.

  • Improved configuration for services MC.R21.18 (all tagged services) to allow tagging safe uses.

  • Improved configurability of services MC2.5.3, MC2.5.4, MC2.5.5, MC2.5.6, MC2.5.7, MC.R5.6 (all tagged services), MC.R5.7 (all tagged services), MC.R5.8 (all tagged services), MC.R5.9 (all tagged services), MP1.2-10-3, MP1.2-10-4, MP1.2-10-5 to allow tagging matching declarations or macros.

  • Improved configurability of service NC3.6.1.i to allow setting user-defined prefixes for sets of files.

  • Improved configurability of service B.SCOUT to allow tagging matching declarations.

  • Improved configurability and ease of use of service B.REQMAN and MC.D3.1 (all tagged services);

  • Fixed false positives for services MC.R1.3 (all tagged services);

  • Services B.DECLFIND and B.STMTFIND are now available to all users: they provide flexible mechanisms for identifying declarations, expressions and statements that match user-specified criteria.

Other enhancements and corrections of existing features and services:

  • Added link to the eclair_report server URL on standard output when a new instance of the server is launched on a database.

  • Improved logging of HTTP requests made by eclair_report to facilitate debugging of customer installations.

  • Improved handling of non-ascii paths in Windows.

  • Removed the eclair_import tool, which has been replaced by the B.DIAGNOSTICS, B.GCOV and B.LLVM_COV services for parsing tools diagnostics and code coverage reports.

  • Updated eclair_reqman to a more recent version of StrictDoc.

Enhancements to license-enforcing mechanisms:

  • The eclair_licman program has been improved by allowing scope specifications to be applied also to the -I option. This is useful when the local Sentinel server has network access to one or more remote Sentinel servers.

Security updates:

  • ECLAIR dependencies were updated to address the following CVEs: CVE-2024-55549, CVE-2025-6965, CVE-2025-9230, CVE-2025-9231, CVE-2025-9232, CVE-2025-24855, CVE-2025-43715, CVE-2025-55763, CVE-2025-58050.

Summary of Changes from Version 3.13.1 to Version 3.14.0

ECLAIR version 3.14.0 contains new features, many enhancements to existing features, and the correction of several defects.

New features (FSSCF):

  • New versioning scheme simplifies working with the many published versions of MISRA C:2012/2023/2025, including revisions, amendments and technical corrigenda. Now the latest version of, say, MISRA C Rule 21.8 (i.e., the one in MISRA C:2025) is available under MC4.R21.8, the version in MISRA C:2023 is available under MC3.R21.4 and the version after MISRA C:2012 TC1 and before MISRA C:2012 AMD2 is available under MC3R1.R21.8 (where “R1” is short for “Revision 1”) and MC3C1.R21.8 (where “C1” is short for “TC1”). MISRA C:2004 checkers are available under the MC2 prefix (e.g., MC2.14.5) whereas MISRA C:1991 checkers are available under the MC1 prefix (e.g., MC1.32).

  • New service B.FRAMES to verify conditions on the invoked toolchain components and the options passed to them.

  • Now ECLAIR intercepts all supported toolchain components by default. Advanced users can limit interception to selected components (via environment variables CC_ALIASES, CXX_ALIASES, AS_ALIASES, LD_ALIASES, AR_ALIASES, FILEMANIP_ALIASES) and prevent interception of selected components (via environment variables CC_NALIASES, CXX_NALIASES, AS_NALIASES, LD_NALIASES, AR_NALIASES, FILEMANIP_NALIASES). The environment variables CC, CXX, LD, AS, AR and FILEMANIP are now ignored.

  • New eclairit driver allows for greatly simplified ECLAIR use.

  • Added support for MISRA C:2012 Amendment 4, MISRA C:2023 and MISRA C:2025.

  • Added support for MISRA C++:2023.

  • Added new tool Scout (service B.SCOUT) to assess the usage of C/C++ entities within a program.

  • Added support for MISRA C:2012/2023 Appendix E, which recategorizes some MISRA C guidelines when applied to automatically generated code.

  • The ECLAIR parser has been updated to support the most recent versions of C and C++.

  • New service B.UNEVALEFF to report unevaluated side effects inside uses of the typeof, sizeof and alignof operators in C/C++.

  • Added metrics B.CMNTLINE_JFUNC and B.COMF_JFUNC that calculate, respectively, the numer of comment lines assogiated to a function and the ratio of comment lines and logical source lines of code in a function.

Other new features:

  • Added new tool eclair_import to generate XML reports from textual output generated by build systems that can be imported into ECLAIR databases.

  • New ECLAIR Bug Finder services for security have been added.

Enhancements and corrections of existing features and services (FSSCF):

  • Service STD.emptrecd is subsumed by STD.anonstct, therefore it has been removed. The service configurations of JC1.1, MC1.1, MC2.1.1, MC3.R1.1, MC3.R1.2, MP1.1-0-1, MP2.4.1.1, NC3.1.1.a are also affected by this change.

  • Fixed false positives for services MC3.D1.1, MC2.12.2, MC3.R1.5, MC3.R5.3, MC3.R13.2, MC3.R10.1, MC3.R17.7, MC3.R18.2, MC3.R18.6, MP1.5-0-1, NC3.3.3.b, MC3.R20.7, B.CALL.noeffect.

  • Fixed false negatives for services: MC2.R9.1, MC3.R9.1, MC3.R17.2, MC3.R18.2, MP1.0-1-7, MP1.3-2-4, MP1.7-5-4.

  • Service MC3.R7.4 now takes into account the exception introduced by MISRA C:2012 Technical Corrigendum 2.

  • Improved configurability of service MC3.R13.1: added the possibility to tag reports based on the effects found by the analysis.

  • Services STD.nstddirv service and STD.prepdirc have only some minor differences, but they check for the same thing: they are merged into a single service STD.prepdirc.

  • Corrected the semantics of the –accept option to the Un*x installers.

  • Floating point max/min are now printed using finite decimal floating point notation.

  • ECLAIR CerTran has been updated to work with SuperTest Aelbert Cuyp 5.0 Release.

  • Improved deviation mechanism for services: MC3.R5.5 and MC3.R5.7.

  • The clarity of reports involving initializer lists has been improved; this improves services: MC3.R10.1, MC3.R10.2, MC3.R10.3, MC3.R10.4, MC3.R10.5, MC3.R10.6, MC3.R10.7, MC3.R10.8, MC3.R11.7, MC3.R12.2, MC3.R14.4, MC3.R16.7, MC3.R23.6, MP1.4-5-1, MP1.4-5-2, MP1.4-5-3, MP1.5-0-10, MP1.5-0-11, MP1.5-0-12, MP1.5-0-13, MP1.5-0-14, MP1.5-0-20, MP1.5-0-21, MP1.5-0-3, MP1.5-0-4, MP1.5-0-6, MP1.5-0-8, MP1.5-0-9, MP1.5-3-1, MP1.5-3-2, MP1.5-8-1, MP1.6-4-7, MP1.7-2-1, NC3.5.3.c NC3.5.6.a.

  • Improved configurability of -stmt_selector; this affects all services using it.

  • Improved report description of service B.CALL.noeffect.

  • Corrected the report counting of “unfixed” reports for kinds other than violation, caution, information or metric in differential analyses.

  • Fixed some rare crashes affecting services MC3.R21.18 and MC3R1.R21.18.

  • Changed default setting for global -call_properties to consider points-to analysis set to be consisting of all possible locations.

  • Allow matching opaque types by matching the type using the global -type_selector instead of matching the name; this affects services: MC3.R22.5, MC3.R22.12, MC3.R22.5, MC4.R22.5.

  • Extend service MC3.R2.6 to take in account GCC attribute __attribute__((unused)).

  • Corrected the -call_properties global configuration type so as not to desugar its argument by default.

  • Added the possibility of selecting a function call via -call_selector using a statement selectors.

  • Fixed service kind from “rule” to “directive” for the following services: MC3.D1.1, MC3.D2.1, MC3.D3.1, MC3.D4.1, MC3.D4.2, MC3.D4.3, MC3.D4.4, MC3.D4.5, MC3.D4.6, MC3.D4.7, MC3.D4.8, MC3.D4.9, MC3.D4.10, MC3.D4.11, MC3.D4.12, MC3.D4.12, MC3.D4.13, MC3.D4.14, MC3.D4.15.

  • Improved configurability of service MC3.R16.6 with the possibility of specifying a minimum or maximum number of switch clauses that trigger a report.

  • Improved configurability of -area_selector to allow statements to be matched.

  • Reports for service MC3.R2.1 concerning switch statements have been improved.

  • Configurability of the -call_properties global configuration has been enhanced to express more fine-grained assumptions about the impact of a function call.

  • The distribution technology used to package eclair_certran has been uniformed to that used by other Python-based tools.

  • Updated and extended mapping from MISRA C:2023 guidelines to CERT-C:2016 rules and CWE weaknesses.

  • The “ECLAIR Project Organization Checker” has been improved and renamed “ECLAIR Independence Checker”. The service identifier B.INDEPENDENCE shall be used instead of B.PROJORG, which is deprecated but still available as an alias.

  • Improved global configuration -context_selector to add a few configuration alternatives that may be useful in services that depend on on this selector.

  • Renamed the base matcher decl(ENTITY_MATCHER) of global -type_selector to entity(ENTITY_MATCHER).

  • Improved performance for services MC3.D4.5, MC3.R5.2, MC3.R5.3, MP1.2-10-1, MP1.2-10-2, MP1.2-10-6, STD.nexidsig.

Other enhancements and corrections of existing features and services:

  • Changed eclair_report colors to better reflect the severity of the report.

  • Improved report descriptions.

  • Updated eclair_reqman to a more recent version of StrictDoc.

  • Updated eclair_format dependencies to the newest versions.

  • Updated and improved the ECLAIR Qualification Kit.

Newly supported toolchains (FSSCF):

  • Added support for the Renesas CC-RX toolchain.

Enhancements of support for already-supported toolchains (FSSCF):

  • Added support for IAR Embedded Workbench 9.50.2.

  • Updated support for newest version of Renesas CC-RL and CC-RX.

  • Updated support for the newest version of ESP-IDF toolchain.

  • Correctly handle implicit option –cmse on IAR ARM compiler.

  • Improved support for Tasking ctc compilers.

  • Extended support for GCC-based compilers up to version 14.

  • Extended support for QNX SDP up to version 8.0.

  • Improved support for clang-based compilers.

  • Improved support for the Freescale S12Z compiler.

Enhancements and additions to the ECLAIR User’s Manual:

  • Documented the use of ECLAIR_* variables of the the ECLAIR GUI.

  • Improved documentation of service MC3.R12.1 and operator precedence.

  • Improved documentation of global configuration -context_selector.

Enhancements and corrections to the ECLAIR GUI:

  • Added a new advanced mode: by default the GUI now starts in simple mode.

  • Other usability and documentation improvements.

Enhancements and additions to collateral documentation:

  • All guides and brochures have been updated.

  • Updated and improved the ECLAIR Qualification Kit documentation.

Enhancements to license-enforcing mechanisms:

  • Updated the protection mechanisms to Sentinel LDK 10.13.

  • The eclair_licman program has been improved with inspective features: now it can list the Sentinel keys, features and products along with their attributes and properties (-S option).

Enhancements to the integrations with IDEs:

  • Updated the IntelliJ plugin to support the most recent versions of the IDE.

Summary of Changes from Version 3.13.0 to Version 3.13.1

ECLAIR version 3.13.1 contains only minor fixes and documentation improvements.

Enhancements of support for already-supported toolchains (FSSCF):

  • Improved support for “armcc” Keil v5 toolchains: fixed B.PARSER errors caused by inclusions of “stdio.h” and “stdarg.h” (in this order) and by expressions with bracket nesting level higher than 256.

Enhancements and corrections of existing features and services (FSSCF):

  • Fixed service B.TEXTFIND matching ranges in compliance with their specification.

  • Fixed crashes in services MC1.109, MC2.18.2, MC3.R19.1, MC3R1.R19.1, MC3R1.R23.1, MC3R1.R23.7 and MP1.0-2-1.

  • Fixed false positives potentially affecting all services that depend on the recognition of unevaluated contexts, most notably services MC3.R2.1 and MC3R1.R2.1.

  • Improved quality of implementation of services B.AUTOINIT, CC2.EXP33, MC1.30, MC2.9.1, MC3.R9.1, MP2D1.152 MC3R1.R9.1, MP1.8-5-1 and NC3.7.2.a.

Enhancements and additions to collateral documentation:

  • Added a FAQ about the compatibility of the ECLAIR GUI with legacy Linux-based operating systems.

Enhancements and corrections to the ECLAIR GUI:

  • Fixed crash in the ECLAIR GUI that caused the interface to become blank and unresponsive.

Summary of Changes from Version 3.12.0 to Version 3.13.0

ECLAIR version 3.13.0 contains new features, many enhancements to existing features, and the correction of several defects.

Note

Starting from this version, the summary of changes uses the acronym FSSCF, from Functional Safety and Security Certified Feature, in order to distinguish certified/qualifiable features from other features.

New features (FSSCF):

  • Added service B.CERTRAN, basis of a new stand-alone product for the automation of compiler qualification in compliance with functional safety standards.

  • Added service B.MACROS, for the reporting of the macros defined in a particular build (essential for ascertaining that the right configuration has been built).

  • Added service B.REQMAN, for the automatic checking of the traceability between requirements and program entities (this is a clone of existing MISRA C:2012 services MC3.D3.1 and MC3R1.D3.1).

  • Added service B.TEXTFIND, a powerful, user-controllable search facility for the automation of tasks such as the recognition of SPDX identifiers.

  • Added support for MISRA C:2012 Amendment 3, including the addition or revision of the following services: MC3R1.D4.15, MC3R1.R1.5, MC3R1.R6.3, MC3R1.R7.5, MC3R1.R8.15, MC3R1.R8.16, MC3R1.R8.17, MC3R1.R17.9, MC3R1.R17.10, MC3R1.R17.11, MC3R1.R17.12, MC3R1.R17.13, MC3R1.R18.9, MC3R1.R21.22, MC3R1.R21.23, MC3R1.R21.24, MC3R1.R23.1, MC3R1.R23.2, MC3R1.R23.3, MC3R1.R23.4, MC3R1.R23.5, MC3R1.R23.6, MC3R1.R23.7, MC3R1.R23.8.

  • Added support for MISRA C:2012 TC2.

  • Added support for MISRA C:2012 Deviation Permits.

  • Added support for the MISRA C:2012 rationale-based classification: this allows subsetting and prioritizing the work on MISRA compliance for projects with different requirements.

Other new features:

  • Added a tagging system for mapping CWE weaknesses to MISRA guidelines.

  • Added a tagging system for mapping CERT-C:2016 rules and recommendations to MISRA guidelines.

  • Added a requirement management tool distributed and installed along with ECLAIR.

  • Added MISRA C++:2023 services: MP2D1.23, MP2D1.25, MP2D1.42, MP2D1.43, MP2D1.45, MP2D1.46, MP2D1.47, MP2D1.81, MP2D1.82, MP2D1.83, MP2D1.94, MP2D1.103, MP2D1.105, MP2D1.106, MP2D1.107, MP2D1.133, MP2D1.134, MP2D1.135, MP2D1.143, MP2D1.145, MP2D1.146, MP2D1.147, MP2D1.148, MP2D1.149, MP2D1.152, MP2D1.158, MP2D1.159, MP2D1.162, MP2D1.163, MP2D1.165, MP2D1.171, MP2D1.187, MP2D1.191, MP2D1.194, MP2D1.196, MP2D1.199, MP2D1.203, MP2D1.204, MP2D1.207, MP2D1.210, MP2D1.211, MP2D1.212, MP2D1.220, MP2D1.224, MP2D1.225, MP2D1.226, MP2D1.228, MP2D1.301, MP2D1.320, MP2D1.321, MP2D1.325, MP2D1.359, MP2D1.387, MP2D1.395, MP2D1.396, MP2D1.397, MP2D1.403.

  • Reports now are tagged with the frames that trigger the analysis: this greatly facilitates analysis of violations involving macros that are expanded differently in different translation units.

  • The eclair_format program has been extended and improved: it now supports arbitrary user configurations.

  • Added the possibility to compile ECL files and added eclair_env options -config_file, -load_config and -save_config in order to work with compiled ECL files: this facility provides significant speedups in the case of large ECL configurations.

  • Added eclair_report option -server_ext that allows serving arbitrary contents.

  • Added eclair_report commands to export tables from an ECLAIR database in XSLT, XML, PROTOBUF, JSON and YAML formats.

  • Added eclair_report options -add_data and -clean_data allowing the addition and removal of arbitrary data to and from an ECLAIR database.

  • Added eclair_report option -load_xml to permit loading of third-party reports into an ECLAIR database: this allows browsing reports from different sources in a consistent way.

  • Added message-based selectors to -loc_selector and -area_selector: now it is possible to use regular expressions on areas and locations messages.

Enhancements and corrections of existing features and services (FSSCF):

  • Improved the internal C/C++ parser.

  • Improved the support for C++ lambda expressions.

  • Improved support for long paths in Windows.

  • Improved the taken call property: now it is possible to specify the property for each argument index (maybe/never/always).

  • Adapted service MC3R1.R21.21 to work with C++ code.

  • Fixed bug in the tagging system for services MC3.D4.5, MC3R1.D4.5, MC3.R9.1 and MC3R1.R9.1.

  • Fixed false positives for services NC3.3.4, NC3.4.3.b, NC3.8.6.a, MC3.D3.1, MC3R1.D3.1, MC3.D4.7, MC3R1.D4.7, MC3.D4.9, MC3R1.D4.9, MC3.R1.1, MC3R1.R1.1, MC3.R2.1, MC3R1.R2.1, MC3R1.R2.2, MC3.R5.6, MC3R1.R5.6, MC3.R8.3, MC3R1.R8.3, MC3.R9.1, MC3R1.R9.1, MC3.R9.3, MC3R1.R9.3, MC3.R14.3, MC3R1.R14.3, MC3.R17.8, MC3R1.R17.8, MP1.0-1-2, MP1.2-7-1, MP1.3-4-1, MP1.5-0-12, MP1.16-0-4, MP1.16-0-8 and STD.implfunc.

  • Services MC3.D3.1 and MC3R1.D3.1 have been improved.

  • Fixed false negatives for services NC3.4.3.b, MC3.D4.9, MC3R1.D4.9, MC3.D4.10, MC3R1.D4.10, MC3.R1.3, MC3R1.R1.3, MC3.R5.6, MC3R1.R5.6, MC3.R8.3, MC3R1.R8.3, MC3.R9.1, MC3R1.R9.1, MC3.R9.3, MC3R1.R9.3, MC3.R21.12, MC3R1.R21.12, MP1.0-1-2, MP1.2-7-1, MP1.3-1-1, MP1.7-5-4, MP1.8-4-2, MP1.15-3-3, MP1.16-0-8 and MP1.16-2-3.

  • Revised Harrison cyclomatic complexity definition computed by metric service HIS.v_G.

  • Fixed crashes of services MC1.18, MP1.14-6-1 and MP1.14-7-1.

  • Fixed bug in service STD.inclqote: the service configurations behavior did not allow the standard identification c95.

  • Fixed bug in services MC3.R18.6 and MC3R1.R18.4: the bug caused the misinterpretation of call properties defined with -call_properties in case of indirect calls.

  • Avoided duplicated tagging areas for many services.

  • Improved tagging system for MC3.R1.2 and MC3R1.R1.2: now they can accept any tag.

  • Improved report selector handling.

  • Added entity-based tagging for services MC3.R2.1 and MC3R1.R2.1.

  • Improved the efficiency of all services that require points-to analysis.

  • Improved the analysis accuracy of all services that check the use of enumeration constants in case statements.

  • Improved messages of services MC3.R14.2 and MC3R1.R14.2.

  • Improved performance of service B.PROJORG.

  • Improved the analysis accuracy of all services that check asm effects.

  • Improved quality of implementation of services that require macro arguments tracking.

  • Improved quality of implementation of services MC3.R8.3 and MC3R1.R8.3.

  • Improved quality of implementation of service B.CBT: now the service reports warnings if a label is used or declared multiple times.

  • Improved quality of implementation of services MC3.R2.1 and MC3R1.R2.1: now the services allow easily deviating branches that are intentionally unreachable.

  • Improved quality of implementation of service STD.charescp: now it checks preprocessed tokens instead of source-code ones.

  • Improved quality of implementation of service MP1.3-4-1: now the service reports all the declarations of entities to be moved; improved service messages.

  • Improved quality of implementation of services NC3.8.6.a: now the service uses stmt_matchers in its configurations.

  • Improved quality of implementation of service MC3R1.R9.1: removed avoidable cautions due to macro calls.

  • Improved configurability of services MC3.R2.1 and MC3R1.R2.1: now it is possible to deviate particular statements and the services report the statements causing the unreachability.

  • Improved configurability of service MP1.3-4-1: now it is possible to ignore const variables.

  • Improved internal utilities for checkers that require a flow-reachability analysis.

  • Fixed B.PARSER errors due to conversions from _Atomic to non-_Atomic types.

  • Fixed crash due to non standard uses of flexible array members.

  • Improved quality of implementation of services MC3.D4.9 and MC3R1.D4.9: now the checkers do not report macros where the typeof macro is used on an expression where a macro parameter occurs (while the macro can theoretically be replaced by several inline functions, the code quality will clearly suffer).

  • The __public_api_decls selector no longer requires external linkage.

Other enhancements and corrections of existing features and services:

  • Fixed missing cache reloading after changes to the database in the interactive reports view.

  • Improved quality of implementation of service B.CMPREXPR-01: now the service uses stmt_matchers in its configurations.

  • Improved the “unknown tool” warning of eclair_env: now the message specifies the tool kind.

  • Improved the macro expansion tracing feature.

  • Fixed crashes in eclair_format.

  • Updated eclair_format dependencies.

Newly supported toolchains (FSSCF):

  • Added support for the Intel FPGA - NIOS2EDS GCC Altera toolchains up to version 10.3.

  • Added support for the Intel FPGA - x86_64 MinGW32 GCC toolchains up to version 10.3.

  • Added support for CodeWarrior Development Studio for Microcontrollers Kinetis Freescale up to version 4.9.

Enhancements of support for already-supported toolchains (FSSCF):

  • Extended support for Microchip XC32 toolchains up to version 4.30.

  • Extended support for Microchip XC8 toolchains up to version 2.40.

  • Extended support for MSVC up to version 14.30.

  • Extended support for Keil C51 and CX51 compilers up to version 9.60.

  • Extended support for TI ARM compilers up to version 20.2.5. LTS.

  • Extended support for TI Arm Clang compilers up to version 1.3.1 LTS.

  • Extended support for TI C2000 compilers up to version 22.6.0 LTS.

  • Extended support for TI C6000 compilers up to version 8.3.12 LTS.

  • Extended support for TI MSP430 compilers up to version 21.6.0 LTS.

  • Extended support for GCC-based compilers up to version 12.

  • Improved support for Arm Keil MDK v5 toolchains with evaluation licenses.

  • Added support for the GCC pragma GCC system_header.

  • Added support for TASKING VX-Compilers for ARM up to version 6.3r1.

  • Added support for TASKING VX-Compilers for 8051 up to version 6.3r1.

  • Added support for TASKING VX-Compilers for PCP up to version 6.3r1.

  • Added support for Clang-based compilers up to version 16.

  • Improved support for GCC-based toolchains.

  • Improved support for Clang-based toolchains.

  • Improved support for the IAR toolchains.

  • Improved support for the MSVC toolchains.

  • Improved support for XC8-cc toolchains.

  • Improved support for the TASKING toolchains.

  • Improved support for the TI toolchains.

  • Improved support for MinGW-based toolchains.

  • Improved support for compilers based on sparc-rtems-gcc.

New integrations with IDEs, editors and, CI/CD systems:

  • Added plugin for NetBeans-based IDEs (including MPLAB X).

  • Added plugin for IntelliJ-based IDEs (including CLion).

  • Added integration with GitHub, including the support of Sarif outputs compatible with GitHub.

  • Added integration with GitLab, including the support of CodeClimate outputs compatible with GitLab and of GitLab authorization checking.

Enhancements to the integrations with IDEs, editors, and CI/CD systems:

  • Updated the Visual Studio plugin to support the most recent versions of the IDE.

  • Updated the Jenkins plugin to support the most recent versions of the “Analysis Model API Plugin” and “Warning Next Generation Plugin”.

Enhancements and additions to the ECLAIR User’s Manual:

  • Added new chapter on Service Classification and Prioritization.

  • Added new chapter on Adoption of Deviation Permits in ECLAIR.

  • Added new chapter on Requirements Management with ECLAIR.

  • Added new tables detailing undefined behaviors of the C programming language that are prevented by using ECLAIR MISRA C services: all versions of the C standard are covered.

  • Added new section on Running ECLAIR in Docker Containers to chapter Installation.

  • Added new section on Opening an ECLAIR Database to chapter Outputs.

  • Added new section on Integrating ECLAIR with Netbeans-Based IDEs to chapter Integrating ECLAIR with IDEs, Editors, and CI Tools.

  • Added new section on Integrating ECLAIR with IDEs based on the IntelliJ Platform to chapter Integrating ECLAIR with IDEs, Editors, and CI Tools.

  • Added new section on Integrating ECLAIR with Services for Software Development and Continuous Integration to chapter Integrating ECLAIR with IDEs, Editors, and CI Tools.

  • Added section on Running Pipelines Within a Docker Container to chapter Integrating ECLAIR with IDEs, Editors, and CI Tools.

  • Added paragraph on Running Pipelines Within a Docker Container to section Integrating ECLAIR with Jenkins.

  • Updated section Integrating ECLAIR with Visual Studio in chapter Integrating ECLAIR with IDEs, Editors, and CI Tools.

  • Expanded paragraph on Report Summary Pages in chapter Outputs to document the interactive reports chart.

  • Expanded section Integrating ECLAIR with Jenkins to consider a new plugin-free integration possibility.

  • The theme of the HTML version of the manual has been updated for increased readability.

  • Many examples have been added and many have been improved.

  • Added documentation for new commands and configurations.

  • Many other small improvements and corrections.

Enhancements and corrections to the ECLAIR GUI:

  • When setting an empty PATH in the Environment section of the GUI, the system PATH will be used instead of an empty one.

  • Added the possibility to configure the directory where the analysis results are stored.

  • Added the possibility to customize the help message for named settings.

  • The self-contained documentation in the ECLAIR GUI has been improved.

  • The documentation for ECLAIR_FULL_TXT has been corrected.

Enhancements to license-enforcing mechanisms:

  • Updated the protection mechanisms to Sentinel LDK 8.5.

Summary of Changes from Version 3.11.0 to Version 3.12.0

ECLAIR version 3.12.0 contains new features, many enhancements to existing features, and the correction of several defects.

New features:

  • New program eclair_format allows reformatting source code in compliance with most of the code layout guidelines of the BARR-C:2018 coding standard.

  • New “ECLAIR client kit” allows users of centralized ECLAIR analysis services to minimize the installed software base on their PCs.

New services:

  • Added a new service B.TROJANSOURCE that checks for vulnerabilities to Trojan source attacks.

  • Added a new service B.PREPCMNT that can be used to check that conditional inclusion preprocessor directives are closed with an #endif that is commented by the guard.

  • Added a new service B.STATINIT that can be used to check that static storage declarations have a complete initializer (this is useful when using compilers, such as TI’s TMS320C28x C/C++ compiler, that do not zero-initialize static and global variables).

  • Added a new service B.RECUMACR that can be used to check that a program does not contain recursive macro invocations.

  • Added a new service B.MACREXPR that can be used to complete the partial protection provided by MISRA guidelines about argument capture in macro body expansions.

  • Added a new service B.ECL to show unused ECL configurations.

Newly supported toolchains:

  • Added support for the Emscripten compiler toolchain to WebAssembly.

  • Added support for the xPack GNU RISC-V Embedded GCC toolchain.

  • Added support for the MPLAB XC8 C Compiler new driver xc8-cc.

Enhancements to existing services:

  • False positives have been fixed for the following services: MC2.1.1, MC2.9.1, MC2.19.4, MC2.19.7, MC3.R2.2, MC3R1.R2.2, MC3.D4.7, MC3R1.D4.7, MC3.D4.9, MC3R1.D4.9, MC3.R8.5, MC3R1.R8.5 MC3.R8.10, MC3R1.R8.10, MC3.R9.1, MC3R1.R9.1, MC3.R9.2, MC3R1.R9.2, MC3.R10.6, MC3R1.10.6, MC3.R10.7, MC3R1.R10.7, MC3.R10.8, MC3R1.10.8, MC3.R11.2, MC3R1.R11.2, MC3R1.R12.5, MC3.R13.3, MC3R1.R13.3, MC3.R14.2, MC3R1.R14.2, MC3.R17.4, MC3R1.R17.4, MC3.R17.8, MC3R1.17.8, MC3.R18.2, MC3.R18.8, MC3R1.R18.2, MC3.R18.3, MC3R1.R18.3, MC3.R18.6, MC3R1.R18.6, MC3R1.R18.8, MC3.R20.6, MC3R1.R20.6, MC3.R20.7, MC3R1.R20.7, MC3.R20.12, MC3R1.R20.12, MC3R1.R21.19, MC3.R22.5, MC3R1.R22.5, MC3R1.R22.10, MP1.0-1-8, MP1.0-1-9, MP1.3-2-4, MP1.5-0-17, MP1.7-3-5, MP1.8-5-1, MP1.12-8-2, MP1.15-3-4, MP1.16-2-2, NC3.3.1.e, NC3.3.1.m, NC3.3.3.b, NC3.3.4.b.

  • Fixed false negatives in the following services: MC3.D4.4, MC3R1.D4.4, SC1.PROG_003.

  • Fixed false positive and negatives in service SC1.PROG-038.

  • Where ECLAIR cannot be sure if the code is non-compliant, violation reports have been changed to caution reports and some messages have been improved for the following services: MC2.13.5, MC2.13.5L, MC2.17.2, MC3.R14.2, MC3R1.R14.2, MC3.R18.2, MC3R1.R18.2, MC3.R18.3, MC3R1.R18.3, MC3.R22.6, MC3R1.R22.6, MP1.5-0-17.

  • Fixed rare crashes caused by checks for the Clang and GCC error attribute in the following services: MC2.16.10, MC3.D4.7, MC3R1.D4.7, MC3R1.R22.10, MP1.0-3-2.

  • Fixed rare crashes in the following services: MC2.19.7, MC3.R8.9, MC3R1.R8.9, MP1.0-1-8 and MP1.0-2-1.

  • The MC3.D3.1 and MC3R1.D3.1 services have been improved: the configuration parameter requirement_set has an extra field to select the unit or program to be checked for requirements; all reporting is now for the whole project.

  • Service MP1.8-4-3 now avoids reporting the missing return statements in dead branches.

  • Service MC3.R16.1 now reports a violation when there are insufficient case clauses.

  • For services MC3.R7.4 and MC2R1.R7.4, caution reports are now output when the string literal is a function argument and there is no corresponding parameter declaration.

  • Defects have been fixed in the following ancillary services: STD.anonfild, STD.arayzero, STD.pteincmp, STD.ptruse, STD.strincmp, STD.stdtypes.

  • Reports for services MC3.R20.7 and MC3R1.R20.7 have been improved.

  • Reports for services MC2.2.4, MC3.D4.4, MP1.2-7-2, MP1.2-7-3 and NC3.2.1.c have been improved: redundant violations have been removed.

  • Reports for services MP1.0-1-1, MC3.R2.1 and MC2.14.1 have been improved: now do-while(0) constructs and parentheses are not reported as unreachable code.

  • Reports for services MC3.D4.9 and MC3R1.D4.9 have been improved: now they include the values of the function-like macro with their types.

  • Improved some analysis tables to reduce their size.

  • A few bugs in service B.EXPLAIN have been fixed and report messages have been improved.

  • Added new service configurations: MC3.R14.3, MC3R1.R14.3, MC3.R2.1 and MC3R1.R2.1

  • Improved the accuracy of services that require an analysis of potential side effects: MC2.12.13, MC2.12.2, MC2.12.3, MC2.12.4, MC2.13.5L, MC2.13.5, MC2.14.10, MC2.14.1, MC2.14.2, MC2.19.7, MC2.8.9, MC3.D4.9, MC3.R13.1, MC3.R13.2, MC3.R13.3, MC3.R13.5, MC3.R13.6, MC3.R14.2, MC3.R15.7, MC3.R2.1, MC3.R2.2, MC3.R2.3, MC3.R2.4, MC3.R8.6, MP1.0-1-10, MP1.0-1-1, MP1.0-1-3, MP1.0-1 -5, MP1.0-1-8, MP1.0-1-9, MP1.15-3-4, MP1.16-0-4, MP1.3-2-4, MP1.5-0-1, MP1.5-2-10, MP1.5-3-4, MP1.6-4-2, MP1.6-5-1, MP1.6-5-2, MP1.6-5-4, MP1.6-5-5, MP1.6-5-6, MP1.8-3-1, NC3.6.3.a, NC3.8.2.d.

  • All services now follow the convention used in GCC to refer to local classes and lambda functions.

  • A new global configuration parameter tool_tag has been added. The configuration parameter compilers has been modified to accept a list of tool tags; tools with the same tag are taken to be compatible. Note that compilers is an optional configuration parameter for users of: MC2.1.3, MC3.D1.1, MC3R1.D1.1, MP1.1-0-2.

  • Report tags have been added or replaced hide/show tags for some configuration parameters: MC2.19.2, MC2.19.3, MC3.R20.2, MC3.R20.3, MC3R1.R20.2, MC3R1.R20.3, MP1.16-2-4, MP1.16-2-5, MP1.16-2-6, NC3.2.2.b, NC3.2.2.d, NC3.2.2.h, NC3.4.3.b, NC3.4.3.d, NC3.4.3.f, NC3.7.2.c, NC3.8.4.d.

  • Implementation of MC2.19.4, MC3.R20.4 and MC3R1.R20.4 have been improved to check all floating-point literals.

  • The POSIX library can be included as a standard library using a new global configuration parameter stdlib. ECLAIR now supports:

    • the checking for reuse of the identifiers provided by POSIX (services MC2.20.1, MC2.20.2, MC3.R21.1, MC3R1.R21.1, MC3.R21.2, MC3R1.R21.22, MP1.17-0-1, MP1.17-0-2, MP1.17-0-3);

    • the checking of the use of errno just before and following calls to POSIX functions and macros that can modify errno (services MC3R1.R22.9, MC3R1.R22.10);

    • ensuring that there are adequate checks for error values that may be returned by calls to POSIX functions (services MC2.16.10, MC3.D4.7, MC3R1.D4.7 and MP1.0-3-2).

  • For the behavior configurations for the used C/C++ implementation, a warning is now given if a behavior for a tool is specified multiple times. The syntax of these configurations has also been improved and simplified.

  • Improved the etypes and terminals report taggers.

  • Added new selector for calls, contexts, statements, and types that allow to differentiate the matching depending on the language or standard.

  • Added new condition line(LIN_RANGE) to matcher loc that allows selecting locations by line number range.

  • Improved comment-based tagging. The end label of a tagging comment should now always be prefixed by : to permit a more robust syntax checking. Multiline tagging comments are now accepted.

  • The user can now set ECLAIR attributes for types and declarations directly in the source code.

  • Fixed a performance bug in macro name extraction from a macro_selector.

Enhancements to the ECLAIR User’s Manual:

  • The relationship between MC3.R1.1 and MC3.R1.2 (similarly, MC3R1.R1.1 and MC3R1.R1.2) has been clarified and examples have been added.

  • References in the documentation for some MC3A1 and MC3R1 services have been corrected.

  • Added section on “AUTOSAR C Implementation Rules Coverage.”

  • SiFive Freedom Studio has been added to the list of supported IDEs and instructions for the installation of the ECLAIR Eclipse plugin on it have been added.

Enhancements of support for already-supported toolchains:

  • Support for the IAR toolchains has been improved.

  • Support for the ARM/Keil toolchains has been improved: this affects both ARM Compiler 6 (a.k.a. armclang) and ARM Compiler 5 (a.k.a. armcc).

  • Support for the Microsoft Visual C++ toolchain has been improved.

  • Support for the GCC-based toolchains has been improved.

  • Support for the QNX SDP toolchain has been extended to the latest versions.

Enhancements to the ECLAIR GUI:

  • Now it is possible to create multiple build, analysis, and reporting configurations that can subsequently be referred in the Configurations steps.

  • Improved the documentation accessible via the ? buttons.

Enhancements to detailed outputs:

  • A chart for quick visualization of report counts has been added.

  • Selections can now be exported or shared with a link.

  • The selection and sorting of rows and columns for the reports count is now supported.

  • Added a new feature that allows excluding or including reports that match the currently selected text.

  • The commands starting with -report_counts1_ and with -report_counts2_ have been uniformed and they now start with the prefix -report_counts_.

  • The memory consumption of eclair_report and of browsers visualizing detailed outputs has been reduced.

  • Tags applied to a report are now visible in all report kinds. This required a change in the .ecd file format: old .ecd files are thus no longer compatible and should be regenerated from the corresponding .ecb files using the new version of ECLAIR.

  • Rich outputs in HTML, ODT, DOC, XML and pure text format can now be generated with all license coverages (partial and SME), although with different precision in the localization of the involved code locations and corresponding messages: line/column numbers and messages are (as always) only available to SME coverage licensees.

  • Fixed a bug in the Import action feature of the ECLAIR report view.

Enhancements to summary outputs:

  • Added a new by_tag.txt file with tags information to the outputs produced with -summary_txt.

  • The integrated filter mechanism now allows to enable and disable items separately by simple clicking on them.

  • Improved the generation of the FCA 7-Z0072 reports.

Enhancements to the integration with IDEs and editors:

  • The report displayed in the IDE/editor is now also highlighted in the ECLAIR detailed reports page.

  • The eclair_report -auto_shutdown options has been improved: now it no longer stops eclair_report if a client is connected.

  • Improved the logging of all the plugins.

  • Improved positioning in the integration for Visual Studio.

  • Fixed possible eclair_report crash during client connection.

Enhancements to installers:

  • The same installers can now be used independently from the licensed packages, from the license coverage, and from the license-enforcing mechanism.

  • The installation log files generated by Windows installers are now written in UTF-8.

  • The installation log files generated by all (Windows, Linux and OS X) installers are now terminated with a line reporting the system time at completion of the installation process.

Enhancements to license-enforcing mechanisms:

  • Updated the protection mechanisms to Sentinel LDK 8.2.1.

  • Clone-detection has been improved especially for users planning to deploy ECLAIR in Docker or LXC containers.

  • The eclair_licman program is now more general and can be used to work with ECLAIR license keys of any kind; consequently, both the options -d (express detach) and -c (express cancel detach) now take the product numeric id as a mandatory argument.

Summary of Changes from Version 3.10.0 to Version 3.11.0

ECLAIR version 3.11.0 contains several new features, lots of enhancements to existing features, and some bug fixes.

Enhancements to eclair_report:

  • Added the possibility to run an external script directly from the eclair_report interface. The script can be triggered from either browser, GUI or IDE and can perform every type of action exploiting the information of the selected report(s).

  • Added an -auto_shutdown option that allows to turn off eclair_report automatically after a set period of time from when all GUI or browser tabs are closed.

  • The magnifying glass icon next to a report will now save a screenshot of the source code area interested by it in the clipboard.

  • Added options -summary_doc and -full_doc to produce summary outputs in DOC format.

  • Renamed option -metrics_txt.

Enhancements to toolchains support:

  • Added support for the CrossWorks toolchain for ARM: this supports the GCC/cc1 compilation tools, the LLVM/Clang compilation tools, as well as the native (cc) compiler driver.

Enhancements to Linux integration:

  • The Linux installer will add eclair_report and eclair_gui to the application list of the desktop environment.

  • The Linux installer will create an association between the .ecs files and eclair_gui.

  • The Linux installer will create an association between the .ecd files and eclair_report.

Enhancements to the GUI and integration with external IDEs and CI systems:

  • A Visual Studio plugin has been added.

  • Several help-messages in the ECLAIR GUI have been improved and extended with more information.

  • The ECLAIR GUI and all the integration plugins now allow specifying eclair_report server options.

  • Improved loading/saving of .ecs files.

  • Improved support for Windows UNC paths.

  • The interface with Jenkins has been improved in several respects:

    • support for Jenkins pipelines has been added;

    • added ECLAIR Project Home in the left panel of the build view, which links to the eclair_report homepage of the reports database generated by the selected build.

  • The selection of reports has been further improved.

Enhancements to existing services:

  • Analysis speed and memory consumption has been generally improved.

  • The helpers that collect the effects of source code components have been improved; these changes are relevant to:

    • the added MISRA C++ services MP1.0-1-8 and MP1.15-3-4, and

    • other existing services that rely on a knowledge of the effects.

  • False positives have been fixed in the following services: MC3A1.R21.19, MC3R1.R21.19, MC3.R14.3, MC3.R14.3, MC3R1.R14.3, MC3.R18.6, MC3R1.R18.6, MC3.R9.1, MC3R1.R9.1, MC3.R8.5, MC3R1.R8.5, MC3.R5.7, MC3R1.R5.7, MP1.0-1-2, MP1.3-3-1, MP1.2-10-3, MP1.7-5-2.

  • Support for MC3.R3.1 and MC3R1.R3.1 has been improved.

  • The report locations for MC3A1.R21.18 and MC3R1.R21.18 have been improved.

  • A bug leading to wrong report suppression has been fixed.

  • Reports concerning recursive function have improved messages.

  • A new global configuration extra_definitions has been added that allows the user to add information about defined entities when the analyzed source code is incomplete.

  • Improved non-ASCII characters handling.

  • Reimplemented MP1.0-1-12 to better match the rule’s source description.

  • Reimplemented NC3.5.3.c.

Enhancements to documentation:

  • The ECLAIR User’s Manual has been improved and integrated in several aspects:

    • A GEP (Guideline Enforcement Plan) for MISRA C++:2008 has been added;

    • Chapter Custom Get and Run actions in ECLAIR has been added;

    • a list of suggested tagging systems has been added in The Report Tagging System Section;

    • the of Common Features for all the HTML output pages has been improved and completed;

    • all the sections about the integration with IDEs and editors have been revised and updated;

    • the sections about Jenkins integration have been revised and updated;

    • Section Producing DOC Outputs about the generation of outputs in DOC format has been added;

    • Section Producing ODT Outputs about the generation of outputs in ODT format has been extended and improved.

    • Section Metrics Output to Spreadsheet Programs about the generation of spreadsheet files containing the program metrics has been updated.

New services:

  • Services MP1.14-8-1, MP1.14-5-1, MP1.14-6-1, MP1.12-1-1, MP1.0-1-8, MP1.7-4-2 and MP1.15-3-4 for checking compliance with the corresponding MISRA guidelines for C++ have been added.

  • A new metric B.LINES_FILE that counts the number of physical lines in a file has been added and the services MET.B.LINES_FILE and EMET.B.LINES_FILE have been added to the MET and EMET rule sets, respectively.

Summary of Changes from Version 3.9.0 to Version 3.10.0

ECLAIR version 3.10.0 contains several enhancements, some new features, and bug fixes.

Enhancements to detailed outputs:

  • The first table in the Overall Information page shows the static selection and variant, if any, that have been used to produce the reports.

  • The ECLAIR selection panel switch is now visualized in red when the current dynamic selection (i.e., the one operated via the panel itself) is hiding reports.

  • The ECLAIR selection panel now supports message-based selection with regular expressions; this allows working more effectively on projects with many violations.

  • The ECLAIR selection panel now allows to save and load named selections.

  • The summary pages (showing reports counts by service, by first file or by service and first file) now begin with a row containing the totals for each column; such total numbers reflect the current selection (the static one as further refined by the dynamic one, if any).

Enhancements to the GUI and integration with external IDEs and CI systems:

  • Added a File Manipulator setting to the Toolchain Components page of the GUI.

  • The interface with all supported IDEs has been improved: now IDEs can connect to a remote ECLAIR report server.

  • Support for multi-IDE access to an ECLAIR report server has been added: now IDEs from different computers can be connected to the same ECLAIR report server at the same time.

  • The ECLAIR report server has been improved in several respects:

    • HTTPS support has been added (the -ssl option, if present, specifies that the server must run in HTTPS mode; the -ssl_certificate option specifies the path for a PEM certificate for the ECLAIR report server when run in HTTPS mode).

    • Stability and security have been significantly improved (the -actions option specifies whether remote users can perform stop, changing and changed actions on the ECLAIR report server).

    • Logging has been improved.

    • Support for Jenkins and HTPASSWD authorizations have been added (the -auth option specifies which database paths are/aren’t accessible and which need Jenkins or HTPASSWD authentication).

    • Pairing mechanisms have been added to associate browsers with an IDE (the eclair_report server host option specifies the ECLAIR report server hostname/IP address to connect to); the Use local ECLAIR report server as a proxy option specifies whether the remote server is running without a site license and therefore requires a local eclair_report proxy).

  • The interface with Jenkins has been improved in several respects:

    • HTTPS support has been added (the Use ECLAIR SSL mode option specifies whether the ECLAIR report server needs to be launched or is already running in HTTPS mode; the ECLAIR SSL certificate path option specifies the location of the certificate to be used when starting the ECLAIR report server).

    • Efficiency has been considerably improved.

    • The ECLAIR report server stability has been improved under Jenkins (the ECLAIR server ownership option specifies whether the ECLAIR report server is managed by Jenkins).

    • Jenkins logging for the ECLAIR report server has been added.

Enhancements to existing services:

  • Several services for checking compliance with the MISRA C and C++ guidelines have been improved, false positives have been corrected, and messages have been clarified.

  • False negatives of the service for checking compliance with MISRA C:2012 Rule 22.6 (concerning pointers to FILE not to be used after the associated stream has been closed) have been corrected.

  • Several services for checking compliance with the BARR-C:2012 guidelines have been improved as well.

  • False negatives for checking compliance with the BARR-C:2012 Rule 1.5.b when no file was specified by the configuration has been fixed and a caution report is shown if the named file is empty.

  • Service B.PTRUSE that checks for redundant casts has been improved and false positives fixed.

  • Failure when using B.EXPLAIN has been fixed and reports improved.

  • All services concerned with tagging and checking tools in the toolchain will now use the canonical pathname. Note that this may require a change to configuration values that select a tool; for instance, when the value is a regular expression matching a tool name, it will need to be modified to match the tool’s canonical pathname.

Enhancements to toolchain support:

  • Support for the Renesas RX toolchain has been improved.

  • Support for the GNU toolchains and all their variants has been improved.

Enhancements to documentation:

  • The ECLAIR User’s Manual has been integrated and improved.

New services:

  • Services MP1.0-1-2 and MP1.0-1-6 for checking compliance with the corresponding MISRA guidelines for C++ have been added.

  • Service B.REDCAST that checks for redundant casts has been added.

Summary of Changes from Version 3.8.1 to Version 3.9.0

ECLAIR version 3.9.0 contains several enhancements and some bug fixes.

  • A brand new, very effective Jenkins plugin has been added.

  • ECLAIR now provides support for 100% of the guidelines in MISRA C:2012 Revision 1 with Amendment 2.

  • New service B.PROJORG allows checking the project organization and internal dependencies as well as detecting unwanted interference between project components.

  • Support for all MISRA standards has been improved further.

  • Support for BARR-C:2018 has been improved.

  • The models of GNU and derived toolchains have been improved.

  • The models of IAR toolchains have been improved.

  • The ECLAIR GUI has been improved.

  • The ECLAIR workspace default directory has been changed so as to be tied to the particular ECLAIR version; this facilitates users that need to run different versions of ECLAIR.

  • All documentation has been extended and improved.

  • Analysis efficiency has been improved.

  • The ECLAIR Bug Finder messages have been improved.

  • A defect causing crashes in some rare circumstances has been fixed.

  • Sentinel LDK has been updated to the latest version published by Thales, which solves several issues and contains numerous improvements. All user are recommended to upgrade and not skip the installation of Sentinel LDK RTE when/if proposed by the ECLAIR 3.9.0 installer.

Summary of Changes from Version 3.8.0 to Version 3.8.1

ECLAIR version 3.8.1 contains only minor fixes and documentation improvements.

  • The model of ARM Compiler 5 (armcc) has been improved.

  • Defects in the use of the ancillary services have been fixed.

  • The computation of metric HIS.COMF did not correctly account for header files and this has been corrected.

  • For services concerned with entity name checking, the short circuit tagger for selecting the entity name now matches both the entity and its name before the associated report tag is assigned.

  • STM32CubeIDE and Silicon Labs Simplicity Studio have been added to the list of supported IDEs and instructions for the installation of the ECLAIR Eclipse plugin on them have been added to the manual.

  • IDE integration has been improved to support old versions of Eclipse.

  • The manual has been improved.

Summary of Changes from Version 3.7.0 to Version 3.8.0

ECLAIR version 3.8.0 contains numerous enhancements and some bug fixes.

  • Support for MISRA C:2012 Amendment 2 has been added: this allows coding MISRA C compliant projects using any version of the ISO C language standard.

  • Brand new integration technology with Eclipse, Visual Studio Code and Emacs has been added: these features are now available across all ECLAIR licensing schemes.

  • ECLAIR support for HIS and non-HIS metrics has been completely reviewed: a total of 48 function, translation unit, and program metrics are now available and qualifiable also in the context of critical development.

  • Support for all guidelines concerned with the C/C++ implementation, unspecified and undefined behaviors has been improved. Note that this includes changes to the behavior configuration parameters provided by the ancillary services.

  • Support for the BARR-C:2018 coding standard has been further extended and improved. In particular:

    • rules concerning the spacing and alignment of code have been improved;

    • rules concerning the use of identifiers reserved for the standard library have been revised to match the BARR-C source description and avoid false positives.

  • Support for several MISRA C/C++ guidelines has been improved.

  • ECLAIR User’s Guide has been improved. In particular:

    • clickable references to the official coding standard documents have been added so that when the appropriate PDF files are installed in ECLAIR, the document is opened at the right page;

    • a chapter describing the installation and use of the new integration technology (see above) has been added;

    • the section about checking the project vocabulary has been clarified.

  • Support for toolchains has been improved. In particular:

    • support for the ESP-IDF and the IAR MSP430 toolchains has been added;

    • support for other IAR toolchains and the CodeWarrior HC12 toolchain has been improved.

  • A GUI glitch whereby garbled text was sometimes displayed in the run log area has been fixed.

  • All ECLAIR executables in the Windows version are now digitally signed by BUGSENG with an extended validation (EV) code-signing certificate issued by Sectigo (formerly Comodo), a Microsoft partner enrolled and authorized for Kernel Mode Code Signing as part of the Microsoft Trusted Root Certificate Program. In previous versions only the installers and uninstallers were digitally signed.

Summary of Changes from Version 3.6.3 to Version 3.7.0

ECLAIR version 3.7.0 contains numerous enhancements and some bug fixes.

  • Support for the BARR-C:2018 coding standard [7] has been extended and improved. This version of ECLAIR covers, under the prefix NC3, more than 80% of the guidelines.

  • Support for MISRA C:2012 rule 22.3 (see [43] and [49]) has been added.

  • Support has been added to the GUI for computing metrics and consulting the results.

  • The HTML reporting facility has been enhanced to allow easier selection of what should be shown; the documentation in the manual for this has been updated and improved.

  • New rule sets MET for metric reporting and EMET for exceeded metric reporting have been added.

  • Sentinel LDK has been updated to the latest version published by Thales, which solves certain important security issues of Sentinel LDK itself. All user are recommended to upgrade and not skip the installation of Sentinel LDK RTE when/if proposed by the ECLAIR 3.7.0 installer.

  • Checkers concerned with encapsulating and documenting asm statements, have been improved, so that false positives are avoided. Also we have added two configuration parameters whereby the user can select if they wish to allow or disallow an encapsulating macro or function to include both encapsulated asm statements mixed with unencapsulated asm statements.

  • For checkers whose results depend on the, possibly approximate, evaluation of a numeric value, because of an improved evaluation procedure, the number of caution reports have been reduced: both by removing any caution reports that are now known to be false and by upgrading other caution reports to a violation that are now known to be true.

  • Checkers reporting the inclusion of increment-decrement operators in expressions with other potential side effects were falsely reporting the operators when applied to volatile objects. This is now fixed.

  • Checkers concerned with reporting invariant Boolean expressions have been improved so that they are not reported when in a constant context.

  • When showing the include paths, the file locations in the reports depended non-deterministically on the selected paths. Such nondeterminism is now avoided.

  • Crash that occurred when analyzing some preprocessor conditional expressions has been fixed.

  • Report tagging has been changed to allow for the assignment of multiple tags.

  • Keil armcc model now recognizes the inline keyword in C99 mode.

Summary of Changes from Version 3.6.2 to Version 3.6.3

ECLAIR version 3.6.3 contains only minor fixes and documentation improvements.

  • Support for the Wind River DIAB and the Freescale HC12 toolchains has been improved.

  • A chapter about troubleshooting has been added to the manual.

Summary of Changes from Version 3.6.1 to Version 3.6.2

ECLAIR version 3.6.2 contains only minor fixes and documentation improvements.

  • The model of the IAR compiler for ARM has been improved.

  • A glitch in the GUI has been fixed that caused some unwanted scrolls when zoom was applied.

  • A glitch in some goto-related metrics related to indirect gotos has been fixed.

  • The manual formatting and content has been improved.

Summary of Changes from Version 3.6.0 to Version 3.6.1

ECLAIR version 3.6.1 contains only bug fixes and documentation improvements.

  • The manual formatting and content has been improved.

Summary of Changes from Version 3.5 to Version 3.6.0

ECLAIR version 3.6.0 contains numerous enhancements and some bug fixes.

  • Support has been added for MISRA C:2012 Third edition, first revision [49]. Note that this comprises:

    These new guidelines are available under the prefix MC3R1, while the guidelines for MISRA C:2012 [43] and MISRA C:2012 Amendment 1 [44] remain available under the prefixes MC3 and MC3A1, respectively.

  • Support has been added for the BARR-C:2018 coding standard [7]. This support covers more than 75% of the guidelines which are available under the prefix NC3.

  • the configuration parameter user_entity_name, provided for checkers concerned with the syntax of entity names, that specified the allowed format and vocabulary for the entity and macro identifiers, has been split into two and improved.

  • Due to bug fixes, recently noted false negatives are now reported, in particular:

    • for checkers concerned with the initialization of automatic variables;

    • in the checking of undefined and unspecified behavior

    • for checkers that require knowledge about the expected behavior of calls to standard library functions and the variables passed as arguments;

    • for checkers requiring pointee types to be declared const whenever possible;

    • when checking for guards in empty header files.

  • Due to improvements to the checkers and associated tools, the number of false positives has been reduced:

    • for checkers concerned with the initialization of automatic variables;

    • for checkers concerned with functions that return error values and with ensuring the returned value is checked;

    • for checkers concerned with functions that may return the end-of-file indicator EOF and with ensuring the return value is checked;

    • for checkers concerned with standard library functions that provide error information using errno;

    • for checkers that require knowledge about the expected behavior of calls to standard library functions and the variables passed as arguments;

    • for checkers concerned with missing return statements that were wrongly reporting asm statements;

    • for MC2.20.2 and the false reporting of the use of structure names reserved by the standard library;

    • for checkers detecting commented-out code;

    • for checkers concerned with detecting recursive method calls.

    • for checkers concerned with casts removing const or volatile qualification from the type of a pointer or reference.

    • for checkers that report unnecessary use of external linkage

  • Due to improvements to the checkers and associated tools, the number of false caution reports has been reduced and some true caution reports have been converted to violation reports:

    • for checkers concerned with the initialization of automatic variables;

    • for checkers concerned with reporting recursive functions when the function call is indirect or the callee is virtual.

  • Due to improvements to the checkers and associated tools, the report messages have been improved.

  • For checkers when the report concerns an entity and not a specific declaration of the entity, we have added a configuration parameter whereby the user can select if all declarations for that entity should be shown or just a single representative.

Summary of Changes from Version 3.4 to Version 3.5

ECLAIR version 3.5 contains, besides numerous enhancements to all parts of the system, major efficiency improvements: memory consumption has been cut to half and analysis speed has been doubled or more, without any impact on analysis precision (speedups up to 6x have been observed).

Summary of Changes from Version 3.3 to Version 3.4

ECLAIR version 3.4 contains a new web application for viewing reports, several new and revised services and improvements to all aspects of the system.

New services include support for an appreciable part of the BARR-C:2018 coding standard [7]. This replaces ECLAIR support for the previous version [6].

There is a brand new innovative HTML reporting tool providing clear visualization with versatile navigation facilities of all the information concerning an ECLAIR analysis. With this new reporting tool the user has quick access to:

  • information about the build process and the ECLAIR analyses performed;

  • statistics on the various findings;

  • detailed reports about each finding;

  • optionally, full project sources, both before and after preprocessing.

The HTML outputs are compatible with most popular browsers, such as Google Chrome, Internet Explorer, Mozilla Firefox, Safari and Opera.

The configuration language, ECL, has also further improved and simplified. While ECLAIR 3.4 is mostly backward compatible with ECLAIR 3.3, the syntax of some configuration options has changed. As usual, to facilitate users in the transition, BUGSENG provides a free update service: let us have your old configuration files and we will send the new ones to you.

Summary of Changes from Version 3.2 to Version 3.3

ECLAIR version 3.3 contains substantial new functionality over the previous versions and offers significant improvements in all aspects of the system. Most notably:

  • there is a brand new GUI that makes it very simple to configure a project for static analysis with ECLAIR;

  • a new service, called B.EXPLAIN, outputs a natural language description for each ECLAIR configuration in force;

  • configuration templates are provided for global configurations and for each supported service (e.g., coding rule checkers);

  • reports suitable for printing can now be generated in the OpenDocument Text format (which can be easily turned into, e.g., PDF);

  • the suppression mechanisms allow more fine-grained control, which is very useful when dealing with all the not-completely-defined behaviors of C and C++.

The configuration language, ECL, has also further improved and simplified. While ECLAIR 3.3 is mostly backward compatible with ECLAIR 3.2, the syntax of some configuration options has changed. As usual, to facilitate users in the transition, BUGSENG provides a free update service: let us have your old configuration files and we will send the new ones to you.

Summary of Changes from Version 3.1 to Version 3.2

ECLAIR version 3.2 contains many new static analyses, especially targeted at security. Support has been improved and extended for C11, C++11, C++14 and C++1z. The quality of ECLAIR reports has been improved further and their generation has been sped up by more than an order of magnitude.

There are new, very convenient installers both for the Windows and the Linux versions.

The configuration language, ECL, has also been significantly improved and simplified. While ECLAIR 3.2 is mostly backward compatible with ECLAIR 3.1, the syntax of some configuration options has changed. As usual, to facilitate users in the transition, BUGSENG provides a free update service: let us have your old configuration files and we will send the new ones to you.

Summary of Changes from Version 3.0 to Version 3.1

ECLAIR version 3.1 contains significant improvements in the checking of underlying/essential types required by the MISRA coding standards. More generally, the messages in ECLAIR reports have been uniformed and improved.

ECLAIR version 3.1 has improved support for Windows 8.* and Windows 10.

Summary of Changes from Version 2.3 to Version 3.0

ECLAIR version 3.0 contains many new services and major improvements to existing services, most notably those supporting the MISRA C:2012 coding standard [43].

Configurability has also been enhanced and makes it easier to support projects that use C and C++ at the same time and/or use different coding standards on different parts of the project. Deviation mechanisms have also been extended and improved.

New services include the exceedingly useful B.OBJCMP, which allows users to guarantee their changes to make the code compliant do not modify the generated object code (which implies no new bug has been introduced). And B.REMAKE, which automatically builds makefiles that can reproduce a build (and the analysis) at maximum parallelism, even if the project build system does not support parallel builds.

While ECLAIR 3.0 is mostly backward compatible with ECLAIR 2.*, the syntax of some configuration options has changed. As usual, to facilitate users in the transition, BUGSENG provides a free update service: let us have your old configuration files and we will send the new ones to you.

Summary of Changes from Version 2.1 to Version 2.3

The environment variables used to specify the toolchain components to be intercepted have been made uniform between the Windows and the Linux versions of ECLAIR. The following table gives the correspondence between the environment variables for which support has been dropped and those that have taken their place:

ECLAIR 2.1

ECLAIR 2.3

MS_LINK

LD

MS_CL

CC

MS_LIB

AR

CL_ALIASES

CC_ALIASES

LINK_ALIASES

LD_ALIASES

LIB_ALIASES

AR_ALIASES

Summary of Changes from Version 1.2

ECLAIR version 2.* contains major improvements and radical changes in every part of the system. As a consequence, as is often the case for major versions, there is no backward compatibility with respect to ECLAIR version 1.2, the previous released version. In particular, the syntax of many configuration options changed and configuration files for ECLAIR version 1.2 cannot be expected to work with ECLAIR version 2.*. To facilitate users in the transition, BUGSENG provides a free update service: let us have your old configuration files and we will send the new ones to you.

Installation

This chapter describes the hardware/software requirements and the software installation procedures that are applicable to version 3.16.0pre10 of ECLAIR.

Please note that these are purely technical requirements and procedures. See your ECLAIR license for additional requirements.

Hardware Requirements

The machines on which ECLAIR will be run must be equipped with enough CPU cores, RAM memory and hard disk storage to meet the user expectations. Please note that, since this version of ECLAIR is free from artificial limitations concerning the size and complexity of the source files and of the entire project, there is no amount of resources that can be generally declared as sufficient.

That being said, it can be safely assumed that no serious verification work can take place on a machine where less than 8 GB of RAM or less than 32 GB of hard disk storage is available to ECLAIR.

Software Requirements

The version of ECLAIR shipped along with this manual has been tested on the following supported operating systems: Windows 10/x86_64, Windows 11/x86_64, macOS 26/aarch64, Ubuntu 20.04/x86_64, Ubuntu 22.04/x86_64, Ubuntu 24.04/x86_64, Ubuntu 24.04/aarch64, AlmaLinux OS 9/x86_64, AlmaLinux OS 10/x86_64, Debian 11/x86_64, Debian 12/x86_64, Debian 12/aarch64, Debian 13/x86_64, Debian 13/aarch64, CentOS Stream 9/x86_64.

The latest service packs and security updates must be installed.

This version of ECLAIR is also expected to work on the following non-supported operating systems: Windows XP/i686, Windows 7/i686, Windows 7/x86_64, Windows 8/x86_64, Windows 8.1/x86_64, Ubuntu 16.04/x86_64, Ubuntu 18.04/x86_64, Ubuntu 18.10/x86_64, Ubuntu 19.04/x86_64, Ubuntu 19.10/x86_64, Ubuntu 20.10/x86_64, Ubuntu 21.04/x86_64, Ubuntu 21.10/x86_64, Ubuntu 22.10/x86_64, Ubuntu 23.04/x86_64, Ubuntu 23.10/x86_64, Debian 8/i686, Debian 8/x86_64, Debian 9/x86_64, Debian 10/x86_64, CentOS 7/i686, CentOS 7/x86_64, CentOS 8/x86_64, Fedora 25/x86_64, …, Fedora 42/x86_64, RHEL 6.7/i686, RHEL 6.7/x86_64, RHEL 7.2/i686, RHEL 7.2/x86_64, RHEL 7.3/x86_64, RHEL 7.4/x86_64, RHEL 7.5/x86_64, RHEL 7.6/x86_64, RHEL 7.7/x86_64, RHEL 8.1/x86_64, RHEL 8.2/x86_64, RHEL 8.3/x86_64, RHEL 8.4/x86_64, RHEL 8.5/x86_64, RHEL 9/x86_64, RHEL 10/x86_64, openSUSE Leap 42.1/x86_64, openSUSE Leap 42.2/x86_64, openSUSE Leap 42.3/x86_64, openSUSE Leap 15.0/x86_64, openSUSE Leap 15.1/x86_64, openSUSE Leap 15.2/x86_64, openSUSE Leap 15.3/x86_64, openSUSE Leap 15.4/x86_64, openSUSE Leap 15.5/x86_64, openSUSE Leap 15.6/x86_64, openSUSE Leap 16.0/x86_64.

The version of ECLAIR shipped along with this manual is protected using Thales (formerly Gemalto, formerly SafeNet) Sentinel LDK. Its installation is done automatically by the ECLAIR installer.

Note

The installation of the Sentinel LDK run-time environment is known to interfere with some antivirus/anti-malware software. Make sure you disable all antivirus/anti-malware programs before installation and uninstallation of Sentinel LDK run-time environment. Do not forget to re-enable them afterwards.

Interactive ECLAIR analysis HTML outputs and the Sentinel Admin Control Center require a modern web browser. The following browsers are recommended, in decreasing order of preference:

  • Google Chrome, latest version;

  • Mozilla Firefox, latest version;

  • Safari, latest version;

  • Microsoft Edge.

Supported File Systems

ECLAIR must be installed on a local file system that provides file-locking support and atomic file operations. A non-exaustive list is provided below.

Linux: - ext4 - XFS - ZFS

Windows: - NTFS

macOS - APFS

Network/remote filesystems (NFS, CIFS/SMB, etc.) should not be used as targets of the installation directory. Note that this restriction applies also to the installation of the Sentinel LDK runtime environment.

Installation on a Windows Platform

The supported installation procedures for a Microsoft Windows operating system are as follows.

Note

If you are using MSYS2, ensure that the ECLAIR bin directory appears after the MSYS2 directories in your PATH. Having ECLAIR directories before MSYS2 may cause DLL conflicts that prevent MSYS2 tools from functioning correctly.

Installation and Uninstallation with the Windows Installer Program

For ordinary users, the most convenient way to install ECLAIR on a Windows platform is via the installer. The ECLAIR Windows installers and uninstallers can be used both interactively and in silent mode from the command line: we will cover both uses in the next sections.

Installation with the Windows Installer

Whether you choose to use the interactive or the silent installation modes, it is important that you ensure no ECLAIR components are running before starting installation: if in doubt, restart the machine.

It is also strongly recommended that you temporarily disable all anti-malware scanners. The reason is that they can easily interfere with the installation process and can manipulate the installed files in a way that may cause malfunctions. Note that ECLAIR installers as well as all the installed ECLAIR executables are digitally signed by BUGSENG with an extended validation (EV) code-signing certificate issued by Sectigo (formerly Comodo), a Microsoft partner enrolled and authorized for Kernel Mode Code Signing as part of the Microsoft Trusted Root Certificate Program.

Warning

Do not forget to re-enable anti-malware scanners at the end of installation

This is really important: while ECLAIR and its installers are malware-free (besides other obvious considerations, the executables are generated on non-Windows environments that are completely immune to viruses), not re-enabling anti-malware scanners after installation will leave you unprotected.

Interactive Mode

The ECLAIR Windows installers can be used both by Administrator accounts and by accounts configured as Standard user. If installing ECLAIR as a standard user, make sure that the right version of the Sentinel LDK Run-Time Environment has already been installed on the machine because standard users are not able to install it.

Warning

Sentinel LDK RTE is a strong prerequisite

Do not use the ECLAIR Windows installers from a standard user account unless you know that the installer has already been run by an administrator account on the same machine and installation of Sentinel LDK RTE was not skipped.

When the installer starts, it welcomes you with a window like the following:

_images/Windows_Welcome.png

There you can see the ECLAIR version (3.16.0 in this example), the maximal combination of packages the platform may be instantiated upon (MCP), the architecture (w64, for Windows/x86_64), and a license-kind identifier (P in this example, from Professional, as opposed to Trial or Educational or others).

If the installer detects that the very same release of ECLAIR is already installed on the machine, it will display the following instead of the welcome page:

_images/Windows_Already_Installed.png

If you click the OK button, the previous version will be automatically removed and installation will start.

From the welcome page, clicking on the Next button will bring you to the license agreement page:

_images/Windows_License_Agreement.png

Scroll down through the license and, if you agree to its terms, click on the I Agree button. What you will see then is the component selection page, whose appearance depends on whether you are using the installer from an administrator account or from a standard account. In the first case you will see

_images/Windows_Choose_Components_Admin.png

while, in the second case, the Sentinel LDK RTE component cannot be selected.

_images/Windows_Choose_Components_Ordinary.png

If and only if you are running the installer from an administrator account, will you then be brought to a page like the following:

_images/Windows_Choose_Users.png

Here you have the option to install ECLAIR for just your user account or for any user account on the computer.

When installing for your user account only, the proposed install location is within your space, e.g.:

_images/Windows_Choose_Install_Location_Ordinary.png

Otherwise, the proposed location is a system location, e.g.:

_images/Windows_Choose_Install_Location_Admin.png

In any case, you can change the proposed locations, as well as the Start Menu folder for shortcuts:

_images/Windows_Choose_Start_Menu_Folder.png

If you are running the installer from an administrator account you will be notified once the installation of Sentinel RTE is successfully completed.

_images/Windows_Install_Sentinel.png

If you click on the Yes button, the installer for Sentinel LDK RTE will be launched. Note that, in case Sentinel LDK RTE was already installed on the computer, you will be presented with the choice to Repair or Remove the installation: choose the former.

If you had Fingerprint generation checked in the component selection page, you will now be offered the following:

_images/Windows_Collect_Fingerprint.png

Click on Yes if you need a node-locked protection key (as opposed to using a dongle protection key or floating network licenses), in which case you will see

_images/Windows_Fingerprint_Collected.png

In either case, you will then be able to update the PATH environment variable:

_images/Windows_Update_Path_Admin.png

You should normally click on Yes, unless you wish to manually update PATH in the registry or you commit to ensuring the variable is appropriately set before running any ECLAIR component.

At this stage you will be presented with the location where the installation log has been saved:

_images/Windows_Installation_Log.png

At the end of the installation process you will see this page, where a clickable link to the ECLAIR User’s Manual is given for your convenience:

_images/Windows_Completing.png
Silent Mode

The installers can also be run in non-interactive, silent mode from the command line. When used in this mode, the installers:

  • will not install prerequisites;

  • will not collect fingerprints;

  • will update the PATH environment variable;

  • will not generate an installation log.

In order to run the installer in silent mode, you should use the /S option:

"C:\path\to\installer.exe" /S

If you are running the installer from an administrator account, you can use the options /AllUsers and /CurrentUser to select whether you want to install ECLAIR for all users accounts or just for your own user account, respectively, the former being the default.

The use of installers in silent mode is particularly useful in automatic installation batch scripts. Remember, though, that even in silent mode, an installer is a GUI application and the command interpreter will not wait for its completion. If your next step in the script requires installation to be complete, you can invoke the installer as follows:

start "" /WAIT "C:\path\to\installer.exe" /S /AllUsers
Uninstallation with the Windows Uninstaller
Interactive Mode

Using the uninstaller is straightforward. The uninstaller can be invoked in interactive mode in three different but equivalent ways:

  • via the Add/Remove Programs section of the Windows Control Panel;

  • by clicking on the uninstall application of the relevant Start Menu folder;

  • directly, by executing uninstall.exe in the folder previously selected as the installing location.

The landing page of the uninstaller is similar to the following:

_images/Windows_Uninstall.png

By clicking on the Next button you can make sure you are uninstalling the version of ECLAIR you really want to uninstall:

_images/Windows_Uninstall_Confirm_Admin.png

At the end of uninstallation, a completion page will be displayed:

_images/Windows_Uninstall_Completing.png
Silent Mode

Similar to installers, uninstallers can also be run in silent mode by using the /S option, as in

"C:\Program Files\BUGSENG\eclair-3.15.0\uninstall.exe" /S

Note that the ECLAIR uninstallers will never uninstall Sentinel LDK Run-Time Environment (which may be used to protect other applications). When run from an administrator account, the uninstallers will remove BUGSENG add-ons to Sentinel LDK RTE.

Installation from a Zip File

For Windows platforms, ECLAIR can be shipped in the form of a zip file named

ECLAIReclair-DELIVERY-PLATFORM.zip

ECLAIR_VERSION-FEATURES-TARGETLICENSING.tar.gz

where VERSION is a string that identifies the version (e.g., 3.16.0 possibly followed by a customer id), FEATURES is a string that identifies the licenseable features (i.e., MCP allows activation of all features, whereas V only includes a small subset for evaluation purposes) TARGET is a string like w64 (for Windows/x86_64), identifying the platforms under which this distribution of ECLAIR will run. Finally, LICENSING is a single letter, like P, T or E, identifying the licensing terms.

To install ECLAIR, simply unzip the file into a the location PREFIX that has been chosen as the installation prefix. Assuming VERSION is the version installed, the unzip operation will create folder

PREFIX\eclair-VERSION

So, if you installed a specific version of ECLAIR, say 3.16.0, the main executable files will be in folder

PREFIX\eclair-3.16.0\bin

Before proceeding further, make sure the above folder is in your PATH environment variable.

Installation on a Un*x-like System

The supported installation procedures for Un*x-like operating systems are as follows.

Installation and Uninstallation with the Un*x Installer

For most uses, the most convenient way to install ECLAIR on a Un*x-like platform is via an installer.

Installation with the Un*x Installer

The ECLAIR Unix installers can be used both by the root account and by ordinary user accounts. In the second case, the installer will be unable to install the Sentinel LDK Run-Time Environment along with the BUGSENG add-ons, which are prerequisites for the installation of ECLAIR; this is not a problem if both of these have already been installed on the machine.

Warning

Sentinel LDK RTE is a strong prerequisite

Do not use the ECLAIR Un*x installers from an ordinary user account unless you know that the installer has already been run by root (possibly via sudo) on the same machine.

It is important that you ensure no ECLAIR component are running before starting installation: if in doubt, restart the machine.

Running with root Privileges

Let us start with the simplest case, where the installer is run via sudo. In this case, the installer will welcome you as follows:

$ sudo ./ECLAIR_3.16.0-MCP-l64P_Setup.run

This procedure will install ECLAIR 3.16.0 (3.16.0-MCP-l64P).
Hit RETURN to browse the LICENSE AGREEMENT...

There you can see the ECLAIR version (3.16.0 in this example), the maximal combination of packages the platform may be instantiated upon (MCP), the architecture (l64, for Linux/x86_64), and a license-kind identifier (P in this example, from Professional, as opposed to Trial or Educational or others).

Hitting the RETURN key will cause invocation of a text browser on the license agreement:

The entire ECLAIR system is protected commercial software owned by
BUGSENG srl.  Use of the ECLAIR system is only possible in the context
of a LICENSE AGREEMENT between BUGSENG srl and your company ("LICENSEE"
in the sequel).  The essential parts of the LICENSE AGREEMENT are
reproduced below.

Any reproduction or redistribution of any part of the ECLAIR system
not in accordance with the LICENSE AGREEMENT is expressly prohibited
by law, and may result in severe civil and criminal
penalties. Violators will be prosecuted to the maximum extent
possible.

Without limiting the foregoing, copying or reproduction of any part of
the ECLAIR system to any server or location for further reproduction
or redistribution is expressly prohibited.  The extensive and
systematic use of digital watermarking techniques ensures that each
delivered version of ECLAIR, or part thereof, can always be traced
back to the original authorized recipient.

______________________________________________________________________
______________________________________________________________________

ECLAIR LICENSE AGREEMENT
--More--(0%)[Press space to continue, 'q' to quit.]

Scroll down through the license and, if you agree to its terms, type y. You will be then asked for the installation directory:

Please type y to accept, n otherwise: y
Verifying archive integrity... 100%   MD5 checksums are OK. All good.
Uncompressing ECLAIR 3.16.0 (3.16.0-MCP-l64P)  100%

Please select the installation directory
(default /opt/bugseng/eclair-3.16.0):

Whether you accept the default installation directory or provide a different one, the installer will offer to create the required directories. If the last component of the installation path is not eclair, a symbolic link will be created with that name (unless the link is already present):

Please select the installation directory
(default /opt/bugseng/eclair-3.16.0):
'/opt/bugseng', the parent of '/opt/bugseng/eclair-3.16.0', does not exist
Attempt creation of '/opt/bugseng'? [y/N]  y
This step can take several minutes: please do not interrupt the installation process.
gtk-update-icon-cache: Cache file created successfully.
Created symbolic link '/opt/bugseng/eclair' -> '/opt/bugseng/eclair-3.16.0'.

Warning

The chosen installation directory cannot contain spaces, as that would prevent ECLAIR from functioning correctly. If such a path has been chosen, the safest choice is to uninstall the software and rerun the installer.

Note that, if the installation directory already exists, the installer will ask you to choose a different one:

Please select the installation directory
(default /opt/bugseng/eclair-3.16.0):
'/opt/bugseng/eclair-3.16.0' exists: will not overwrite

Please select the installation directory
(default /opt/bugseng/eclair-3.16.0): /new/bugseng/eclair-3.16.0
'/new/bugseng', the parent of '/new/bugseng/eclair-3.16.0', does not exist
Attempt creation of '/new/bugseng'? [y/N]  y
Created symbolic link '/new/bugseng/eclair' -> '/new/bugseng/eclair-3.16.0'.

If you prefer, you can exit the installer, erase the old installation directory tree, and restart the installer.

In any case, the process will continue with the installation/upgrade of Sentinel LDK RTE. Here is, e.g., what this step looks like on an Ubuntu system where Sentinel LDK RTE is not yet present:

Install .DEB on this system
Selecting previously unselected package aksusbd.
(Reading database ... 185799 files and directories currently installed.)
Preparing to unpack .../pkg/aksusbd_10.14-1_amd64.deb ...
Unpacking aksusbd (10.14-1) ...
Setting up aksusbd (10.14-1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/aksusbd.service → /etc/systemd/system/aksusbd.service.
Created symlink /etc/systemd/system/multi-user.target.wants/hasplmd.service → /etc/systemd/system/hasplmd.service.
Install VLIB
Install EMSUrl

Installation of Sentinel LDK RTE 10.14 completed.
Point your browser to http://localhost:1947 to access
the Sentinel Admin Control Center.

When the installer is run with root privileges, it will automatically take care of all aspects of Sentinel LDK RTE installation.

At this stage you will be offered to generate the machine fingerprint. Answer positively if you need a node-locked protection key or if you are installing a machine you want to act as license server. Here is a sample dialogue:

You can now collect the fingerprint of this computer
to enable the installation of a new protection key.
Collect fingerprint? [y/N]  y
Computer fingerprint is in file '/tmp/fingerprint_caFbQw.c2v'.
Please rename it to 'fingerprint_N.c2v' (with N in 1,2,...) and send it
to BUGSENG support services for license activation.

Whatever your answer was to the question about collecting the fingerprint, installation is now complete and the installer prints some information and advice before giving control back to the shell:

ECLAIR 3.16.0 (3.16.0-MCP-l64P) installation complete.

The manual in PDF and HTML format is available in
'/opt/bugseng/eclair-3.16.0/share/doc/manual/ECLAIR_3.16.0-MCP-l64P.pdf'
and '/opt/bugseng/eclair-3.16.0/share/doc/manual/index.html'.

You can add '/opt/bugseng/eclair-3.16.0/bin' or '/opt/bugseng/eclair/bin'
to the PATH environment variable.

A complete installation log is available in '/tmp/ECLAIR_installation_log_LL36mi.txt'
$
Running without root Privileges

When the installer starts, it will check whether it is running with root privileges. If not, it will offer to continue by displaying the commands that have to be executed with root privileges. Here is a sample dialogue:

$ ./ECLAIR_3.16.0-MCP-l64P_Setup.run

This procedure will install ECLAIR 3.16.0 (3.16.0-MCP-l64P).

The entire ECLAIR system is protected commercial software owned by
BUGSENG srl.  Use of the ECLAIR system is only possible in the context
of a LICENSE AGREEMENT between BUGSENG srl and your company ("LICENSEE"
in the sequel).  The essential parts of the LICENSE AGREEMENT are
reproduced below.

[...]

Please type y to accept, n otherwise: y
Verifying archive integrity... 100%   MD5 checksums are OK. All good.
Uncompressing ECLAIR 3.16.0 (3.16.0-MCP-l64P)  100%

Not running as root does not allow directly installing Sentinel LDK RTE,
but the commands to be executed as root can be displayed for later execution.
Do you want to proceed as non-root? [y/N]  y

Please select the installation directory
(default /opt/bugseng/eclair-3.16.0): /home/joe/eclair-3.16.0
This step can take several minutes: please do not interrupt the installation process.
gtk-update-icon-cache: No theme index file.
Created symbolic link '/home/joe/eclair' -> '/home/joe/eclair-3.16.0'.

# Execute the following commands to install Sentinel LDK RTE 10.14.
tar zxf '/home/joe/eclair-3.16.0/reqs/Sentinel_LDK_RTE/aksusbd-10.14.1.tar.gz'
cd 'aksusbd-10.14.1'
sudo ./dinst .

Please install Sentinel LDK RTE 10.14 in order to complete
the installation of ECLAIR 3.16.0 (3.16.0-MCP-l64P).

Once installed, point your browser to http://localhost:1947 to access
the Sentinel Admin Control Center.

At this stage you can also collect the fingerprint of this computer
to enable the installation of a new protection key, e.g. using the command:

'/home/joe/eclair-3.16.0/bin/eclair_licman' -s l -F -o fingerprint_N.c2v

Please substitute N with 1,2,... in 'fingerprint_N.c2v' and send the result
to BUGSENG support services for license activation.

The manual in PDF and HTML format is available in
'/home/joe/eclair-3.16.0/share/doc/manual/ECLAIR_3.16.0-MCP-l64P.pdf'
and '/home/joe/eclair-3.16.0/share/doc/manual/index.html'.

You can add '/home/joe/eclair-3.16.0/bin' or '/home/joe/eclair/bin'
to the PATH environment variable.

A complete installation log is available in '/tmp/ECLAIR_installation_log_YNwIM1.txt'
$

The block of lines starting with

# Execute the following commands to install Sentinel LDK RTE 10.14.

is what you have to send to a sysadmin in order to explain what needs to be done with root privileges.

Manual Uninstallation

Uninstallation is straightforward, unless you want to uninstall Sentinel LDK Run-Time Environment as well, and can be done by simply removing the xdg associations, the installation directory and, possibly, the corresponding eclair symbolic link. If the installer was run with root privileges, this can be done as follows:

# Remove the xdg associations.
sudo /opt/bugseng/eclair-3.15.0/bin/xdg-install.sh -u
# Remove the installation directory.
sudo rm -rf /opt/bugseng/eclair-3.15.0
# Remove the 'eclair' symbolic link, if any.
sudo rm -f /opt/bugseng/eclair

Of course, sudo needs not be used if the installer was run without privileges:

# Remove the xdg associations.
/home/joe/eclair-3.15.0/bin/xdg-install.sh -u
# Remove the installation directory.
rm -rf /home/joe/eclair-3.15.0
# Remove the 'eclair' symbolic link, if any.
rm -f  /home/joe/eclair

If you are sure Sentinel LDK Run-Time Environment is not required by other applications in the system and you want to uninstall it, then the above steps must be preceded by the following commands (where, of course, /opt/bugseng/eclair-3.15.0 should be replaced by the actual installation directory):

cd /tmp
tar zxf '/opt/bugseng/eclair-3.15.0/reqs/Sentinel_LDK_RTE/aksusbd-10.14.1.tar.gz'
cd 'aksusbd-10.14.1'
sudo ./dunst

Installation from a Tarball

ECLAIR can be very easily installed from a tarball, that is, a file named

ECLAIR_VERSION-FEATURES-TARGETLICENSING.tar.gz

where VERSION is a string that identifies the version (e.g., 3.16.0 possibly followed by a customer id), FEATURES is a string that identifies the licenseable features (i.e., MCP allows activation of all features, whereas V only includes a small subset for evaluation purposes) TARGET is a string like l64 or la64 (for Linux/x86_64 or Linux/aarch64, respectively), or m26 for macOS 26 Tahoe), identifying the platforms under which this distribution of ECLAIR will run. Finally, LICENSING is a single letter, like P, T or E, identifying the licensing terms.

Once PREFIX has been chosen as the installation prefix, the steps to be performed are the following:

cd PREFIX
tar zxf eclair-DELIVERY-PLATFORM.tar.gz

Next, ensure that the PATH environment variable contains

PREFIX/eclair/bin

Notice that, on Un*x-like systems, PREFIX/eclair/bin is just a symbolic link to PREFIX/eclair-VERSION/bin, where VERSION is the version of ECLAIR that was installed the latest. So, if you want to use a fixed, specific version of ECLAIR, say 3.16.0, the PATH environment should instead point to

PREFIX/eclair-3.16.0/bin
Post-installation on Linux Systems

In order to accommodate for a possible mismatch between the C library installed in your system and the one expected by the just-installed version of ECLAIR, run the command

postinstall.sh

In order to configure your desktop environment, run the command

xdg-install.sh

The script will:

  • add to your applications list two icons: one for eclair_gui and one for eclair_report;

  • create an association between the .ecs files and eclair_gui, then it will be possible to open a .ecs file simply by double clicking on it;

  • create an association between the .ecd files and eclair_report, then it will be possible to open a database file simply by double clicking on it. eclair_report will open in a new browser tab, and the server will shut down ten seconds after closing all tabs.

If you run the script as superuser the changes will be available for all the users, otherwise they will be available only for the user who launches the script.

xdg-install takes an optional argument -u, running the script with this option all the changes listed above will be reverted, if run as superuser the changes will be reverted for all the users.

The script may exit with status 255, and show the following message:

gtk-update-icon-cache: No theme index file.

Please ignore it, it’s normal. All the features listed above aren’t affected by the error.

Activation of Node-Locked License Keys

If you purchased node-locked license keys, these need to be activated. The activation has two phases: first a machine fingerprint is obtained and sent to BUGSENG; then an activation file sent by BUGSENG should be applied on that machine. Let us suppose 5 node-locked license keys have been purchased and that the machines machine_1, …, machine_5 have been selected to host them. Then the command

eclair_licman -s l -F -o fingerprint_N.c2v

should be executed on machine_N and the resulting file fingerprint_N.c2v should be sent to BUGSENG via the issue-tracking system. BUGSENG will reply by providing the file activation_N.v2c, which should then be installed, either via Sentinel Admin Control Center (using the Update/Attach option), or by executing the command

eclair_licman -A activation_N.v2c -o ack_N.c2v

on machine_N. The resulting file, ack_N.c2v, should be sent to BUGSENG via the issue-tracking system: this is essential for future license keys’ updates and upgrades.

In order to check that the license key has been activated, open the Sentinel Admin Control Center with any web browser.

Activation of Detachable License Keys

If you purchased detachable license keys, these need to be activated. The procedure is very similar, but involves only the machine(s) that will host your license key pool(s): let us call such machines the license servers. The activation has two phases: first a fingerprint of each license server is obtained and sent to BUGSENG; then one activation file for each pool that will be hosted by that license server will be sent by BUGSENG and should be applied on that machine.

The machines that will only use detachable keys, let us call them the client machines, only need installation of the same ECLAIR version and their fingerprint is unneeded.

For information concerning the use of detachable keys, both on the license servers and on the client machines, please consult the relevant section of Sentinel Admin Control Center documentation available at http://localhost:1947/_int_/ACC_help_detach_license.html .

Rehosting Licenses Keys

It is sometimes necessary to transfer a license key from one computer (the source computer) to another (the recipient computer). This is a seven-step procedure, called rehosting, that requires the involvement of BUGSENG support personnel. The procedure steps are the following:

Step 1: Start the Rehosting Process

Open an issue on BUGSENG’s issue-tracking system where you explain why you need to rehost the license key and attach the C2V file for the license in question. You can generate the required C2V either from the Sentinel Admin Control Center or by issuing the following command on the source computer:

eclair_licman -U -o fingerprint_u_source.c2v

You will have to add an option like -sk=376724310135079624 in case you have multiple license keys installed and that the license key to be rehosted is 376724310135079624. You can use the eclair_licman -S K command to list the available license keys.

Step 2: Initialize Rehosting on the Source Computer

You will then receive an email from the BUGSENG EMS Service (ems@bugseng.com) with the subject “LDK-EMS - License Certificate” and containing a V2C file to update your key on the source computer. To install the license update, you can visit the EMS Customer Portal and, with a single click, you can install the update. Alternatively, you can install the update manually using the attached V2C file, through the Update/Attach option of Sentinel ACC. You can also issue a command like the following on the source computer (the name of the V2C file will of course have to be adapted):

eclair_licman -A 376724310135079624.v2c -o ack_ris.c2v
Step 3: Collect Information About the Recipient Computer

Make sure the Sentinel LDK run-time environment is installed and running on the recipient computer. Then, on the recipient computer, execute the command

eclair_licman -s l -I -o fingerprint_i_recipient.c2v

and transfer the generated file fingerprint_i_recipient.c2v to the source computer.

Step 4: Generate the License Key Transfer File

On the source computer, first identify the license key to be transferred using the Sentinel Admin Control Center: suppose the license key is 376724310135079624. Then execute the command

eclair_licman -R 376724310135079624 -r fingerprint_i_recipient.c2v \
  -o rehost_source_recipient.h2h

and transfer the generated file rehost_source_recipient.h2h to the recipient computer.

Step 5: Apply the License Key Transfer File

On the recipient computer, install rehost_source_recipient.h2h, either via Sentinel Admin Control Center, or by executing the command

eclair_licman -A rehost_source_recipient.h2h
Step 6: Prepare for Finalizing the Rehosting Process

Upload to the relevant issue in BUGSENG’s issue-tracking system the C2V file for the just-rehosted license key. You can generate the required C2V either from the Sentinel Admin Control Center or by issuing the following command on the recipient computer:

eclair_licman -U -o fingerprint_u_recipient.c2v

You will have to add an option like -sk=376724310135079624 in case you have multiple license keys installed and that the just-rehosted license key is 376724310135079624.

Step 7: Finalize Rehosting on the Recipient Computer

At this point you will receive another email from the BUGSENG EMS Service (ems@bugseng.com) with the subject “LDK-EMS - License Certificate” and containing a V2C file to update your key on the recipient computer. This update can be installed directly by either by clicking the link in the email, or by installing the update using Sentinel ACC, or by issuing the following command on the recipient computer:

eclair_licman -A 376724310135079624.v2c -o ack_rfr.c2v

and upload the resulting ack_rfr.c2v file to the relevant issue in BUGSENG’s issue-tracking system. As usual, you can check that rehosting took place as expected by using the Sentinel Admin Control Center.

Note

Rehosting, while cumbersome, is a very important operation and in some cases it is the only way to make sure the license key is not lost forever. Do rehost your license keys:

  • at the first sign of likely system failure (e.g., file corruption, unusually noisy fans or hard drives, occasional crashes or boot errors, degraded performance);

  • before replacing hardware components, the BIOS or the operating system (you can always transfer the license key back after the upgrade).

Controlling the Network Activity of Sentinel License Managers

By default, the Sentinel license managers emit broadcast packets in order to sense the presence of remote license keys. This behavior can be changed by accessing the Access to Remote License Managers tab available at http://localhost:1947/_int_/config_to.html . This is the meaning of the options:

Allow Access to Remote Licenses

Enables or disables access to remote network keys.

Broadcast Search for Remote Licenses

Enables or disables access to UDP broadcast search. This kind of search is performed before the Aggressive Search with parameters (see below)

Aggressive Search for Remote Licenses

Will perform a TCP request instead of a UDP; this will intensify network traffic and is not recommended with the Broadcast Search enabled. However, this is useful when used in combination with Specify Search Parameters.

Specify Search Parameters

If Aggressive Search for Remote Licenses is enabled, a TCP search will be performed on the specified addresses.

Running ECLAIR in Docker Containers

Running ECLAIR in Docker containers may be needed in some contexts. Dockerization brings with it a number of advantages such as reproducibility of the build, isolation of the host environment, and shareability.

Docker containers are particularly appropriate for CI/CD workflows.

A very crucial aspect of dockerization is how to link the license to the container, we suggest one of the following possibilities with a preference for the first one (their applicability depends on your environment and licensing):

  • install Sentinel and the keys only in the host environment, and let the ECLAIR instance in the container fetch them via the network. This option is suitable even if the license server is installed on a different machine as long as it is in the same network (this configuration should not be used just to avoid network issues and poor performance).

  • install Sentinel on the container and, when required, detach a license key from a license server (that could be the host itself or another machine). This option requires detachable license keys and if the container does not return the license key, it will remain unavailable until it expires. Set the maximum detach duration accordingly. Once the key is detached and installed in the container this option guarantees the best performance as the features retrieval is local.

We have prepared a Dockerfile for the first option that can be used as a skeleton for your containers:

PREFIX/eclair-VERSION/share/docker/Dockerfile

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation).

Please adapt the Dockerfile where needed and extend it with all the required software to build your project.

Place the ECLAIR installer in the same directory as the Dockerfile, then run the following command to build the Dockerfile:

docker build -t ECLAIR-container .

After building the container, you can execute it with:

docker run -it ECLAIR-container /bin/bash

The second option requires having Sentinel on the container; follow the instructions contained in the Dockerfile to add the Sentinel installation. A small demonstration showing use of ECLAIR in Docker containers for the second option can be found in the following demo:

ECLAIR-MAJ_MIN_demo_crc_Docker

where MAJ_MIN is the major and minor version numbers of ECLAIR separated by a dot (it corresponds to the complete version number by removing the final patch number).

See the REAMDE.txt file contained in the demo for further information.

Warning

You must never move/delete the Sentinel operational directories!

The volumes /var/hasplm and /etc/hasplm defined in the container are the directories where Sentinel LDK RTE stores its configurations and operational files.

The container must be configured to mount these two directories in persistent locations on the host machine.

This is a quite significant point because in this way it is possible to create persistent configurations or use/share already existing instances of Sentinel.

To avoid unexpected behaviors, do not share these directories with machines running at the same time Sentinel (this includes the host machine) and do not provide system directories.

If the container is intended to be used only as license server, please refer instead to the following demo:

ECLAIR-MAJ_MIN_License_Server_Docker

Using ECLAIR from the Command Line

This chapter describes four different commands to use ECLAIR: eclairit, eclair_env, eclair_licman, and eclair_certran. The former is the simplest and quickest way to use ECLAIR, excellent for a first approach to the tool; the second is the “standard” way of using ECLAIR with its wide range of configurations and services; the third is used to manage license keys; the latter is used to run compiler validation test suites automatically.

The eclairit Command

The eclairit command launches the ECLAIR simple driver: it allows to run a build command in an ECLAIR environment to perform some predefined analyses in a very simple way, without requiring any configuration from the user. At the end of the analysis, the results are opened in the default web browser.

The ECLAIR simple driver is invoked as follows:

eclairit [OPTION]... -- COMMAND

Where:

COMMAND is the only mandatory argument: it shall be any command that cleans and (re)builds (part of) a C/C++ project without errors, linking at least one program. The reason is that ECLAIR checkers are run only on those units that are recompiled by the build command. So, to redo the ECLAIR checks on all the compiled files, it is best to clean the project (e.g., with make clean) before (re)building it.

[OPTION]... is a (possibly empty) list of options to configure some aspects of the ECLAIR simple driver (such as -s to select the checks to enable). If no options are given, default configurations are used and the project is analyzed with respect to a selection of BARR-C:2018 rules [7].

Available eclairit Options

The program eclairit can be used without specifying any options, however several are available to tune your analysis. A brief description of such options can be obtained by executing eclairit -h or eclairit --help. In the following sections these options are explained in greater detail.

Option –service_set (-s)
--service_set <SERVICE_SET>, -s <SERVICE_SET>

By default eclairit runs the analysis on a selection of BARR-C guidelines, but via the --service_set or -s options it is possible to select a different set of ECLAIR services to be enabled; the possible values are: - BARR-C - BF - METRICS - MISRA-C - MISRA-Cxx - MISRA-Cxx - sel-BARR-C - sel-BF - sel-METRICS - sel-MISRA-C - sel-MISRA-Cxx

Option –output_dir (-o)
--output_dir <DIR>, -o <DIR>

The output directory of the program eclairit is generated in the current working directory when the command is invoked unless via the --output_dir or -o a different location is specified.

If the option --browse_only is specified then the value of --output_dir shall be the output directory of a previous analysis.

Option –project_root (-p)
--project_root <DIR>, -p <DIR>

The root directory relative to which all files to be analyzed are assumed to be present. It is analogous to the eclair global -project_root.

Option –config (-c)
--config <FILE>, -c <FILE>

This options allows an external .ecl file to be evaluated during the analysis. It is analogous to the eclair global -eval_file.

Option –quiet (-q)
--quiet, -q

This option sets the command not to print any unnecessary information on the standard output.

Option –analyze_only (-a)
--analyze_only, -a

This option sets the command not to visualize the output in the browser, and to end after the generation of the results of the analysis.

Option –browse_only (-b)
--browse_only, -b

The option --browse_only allows visualizing previous generated results without needing to run any additional analysis.

Examples of eclairit uses

Some example of use of the eclairit command:

Example:

eclairit -s BARR-C -- gcc -c -DNDEBUG -m32 p.c

analyze the project with respect to BARR-C:2018 coding standard [7]

Example:

eclairit -s BF -o /tmp/eclairit_BF -- clang -g p.c q.c

analyze the project searching for possible bugs and write the results in /tmp/eclairit_BF

Example:

eclairit -s METRICS -analyze_only -- ./clean_and_build.sh

analyze the project to compute software quality metrics (such as HIS Source Code Metrics [12]) without opening the results at the end of the analysis

Example:

eclairit -s MISRA-C -- make rebuild

analyze the project with respect to MISRA C:2025 coding standard [59]

Example:

eclairit -s MISRA-Cxx -- /opt/gcc-arm-none-eabi/bin/arm-none-eabi-gcc p.c

analyze the project with respect to MISRA C++:2023 coding standard [55]

Example:

eclairit -b

browse the results of the previous analysis

The eclair_env Command

The eclair_env command introduces an environment in which ECLAIR is able to intercept invocations of the key toolchain components and obtain all the information it needs about the project’s programs and/or libraries. ECLAIR is called like this:

eclair_env [OPTIONS] [-- [COMMAND [ARGUMENTS]]]

where OPTIONS is a sequence of eclair_env options and COMMAND is any command with ARGUMENTS as its arguments.

Typical commands include (but are not limited to):

  • compiler and/or linker invocations:

    eclair_env [OPTIONS] -- cc -O2 -g -DNDEBUG=1 -o prog src1.c src2.c

  • invocations of make-like build systems:

    eclair_env [OPTIONS] -- make -j 8

  • invocation of other build systems:

    eclair_env [OPTIONS] -- rpmbuild --rebuild httpd-2.2.10-2.src.rpm

  • invocation of just any script:

    eclair_env [OPTIONS] -- ./build.sh -u kernel=MYKERNEL

When compiling the project code with ECLAIR, it is possible to reduce the CPU time used for compilation by configuring the project build without optimizations.

ECLAIR checkers are run only on those units that are recompiled by the build system. So, to redo the ECLAIR checks on all the compiled files, it is best to run make clean on the build system before invoking ECLAIR.

eclair_env options

The options are:

Option +incremental
+incremental

do not clear previously stored project information and not doing final project wide analysis

Option +clean
+clean

clear any previously stored project information (as without this option) but do not perform the final project wide analysis

Option +project
+project

without clearing previously stored project information, do final project wide analysis (as without this option)

Option +no_default_aliases
+no_default_aliases

do not set default values for the *_ALIASES environment variables, leaving their setting to the user

Other options
-<OPTION>=<VALUE>

where <OPTION> is a global option or a generic service option and <VALUE> is either an individual term or a list of terms enclosed in braces and separated by , or =.

The <OPTION> can be preceded by + or ! or followed by + or - and the different forms have the following semantics:

-<OPTION>=<VALUE>

set or reset the option values to <VALUE> replacing any pre-existing values. If pre-existing values are overwritten a warning will be produced;

-+<OPTION>=<VALUE>

prepend the option value <VALUE> to any pre-existing values;

-<OPTION>+=<VALUE>

append the option value <VALUE> to any pre-existing values;

-<OPTION>-=<VALUE>

delete the option value <VALUE> from any pre-existing values.

-!<OPTION>=<VALUE>

overwrite the option values to <VALUE> replacing any pre-existing values. If pre-existing values are overwritten no warnings will be produced;

Note:

Terms in VALUE should be quoted if they contain characters different from A-Z, a-z, 0-9 or _. If the eclair_env command option is given from the shell command line, the shell quoting rules should be taken into account.

Here, as examples, are some useful global options.

Example:

-eval_file=FILE_NAME,...

loads the configuration contained in file FILE_NAME (see -eval_file).

Example:

-project_name=PROJECT

sets PROJECT to be the project name (see -project_name).

Example:

-project_root=PROJECT_DIRECTORY

sets PROJECT_DIRECTORY as the path for the top source directory of the project named PROJECT, any references to files below this directory are given with a path relative to the directory (see -project_root).

Incremental Configuration

When more than one ECLAIR command options is provided, eclair_env will process them one by one in the specified order (from left to right). For example, the ECLAIR command options can be provided by several configuration files, each included using the command option -eval_file, together with other options written directly on the command line.

This behavior can be usefully exploited; for instance, to incrementally construct a complete configuration composed of smaller pieces, from different configuration files, thereby easing the reuse of common configurations by several different projects:

eclair_env -eval_file=prj_cfg_base.ecl \
  -eval_file=prj_cfg_exp.ecl -- make

Environment Variables

ECLAIR_DIAGNOSTICS_OUTPUT

When defined, its value specifies the output sink receiving the ECLAIR diagnostics output, which defaults to the standard error output stream (see the section on specifying output sinks for more information about output specifications).

ECLAIR_WORKSPACE

When defined, its value is the directory containing the ECLAIR workspace, which defaults to the .eclair subdirectory of user’s home directory. Note that execution privilege is required for the area containing the ECLAIR workspace.

Parallel Builds

Parallel builds (e.g., on make-based build systems, those obtained with make -j [jobs]) are fully supported by eclair_env. For the rare cases where direct textual output is required, the only precaution that should be taken concerns synchronization of the output to the same file of the various instances of eclair_env that are in concurrent execution. Synchronization can be achieved very simply by means of the atomic_append program. An output specification expressing a synchronized output sink has the form |atomic_append FILE (see the section on specifying output sinks for more information about output specifications). A typical invocation of eclair_env on a parallel verification task is:

"-config=B.REPORT.TXT,output='|atomic_append FILE'"

Another possibility is to use a different output file for each analysis frame:

"-config=B.REPORT.TXT,output='FILE_PREFIX@FRAME@.FILE_SUFFIX'"

Note that binary output, requested by service B.REPORT.ECB, is almost always a far superior alternative and does not require any precaution as far as parallel builds are concerned.

The eclair_licman Command

eclair_licman is a command-line tool used for managing ECLAIR license keys. It supports various operations such as license key installation, update, rehosting, and detaching.

Usage:

eclair_licman [OPTIONS]

where OPTIONS is a sequence of eclair_licman options.

Most actions available with this command can also be performed using the Sentinel Admin Control Center, as detailed in the Installation chapter. However, some operations specific to license key rehosting are exceptions (see Rehosting Licenses Keys).

Below you will find some use cases for eclair_licman.

Activation of License Keys

This process consists of three steps that need to be performed on either the machine where the license will be installed (if you have purchased a node-locked license) or the license server (if you have a floating license). These steps include:

  • collecting a fingerprint of the machine where the license key will be installed;

  • sending the fingerprint to BUGSENG and receiving an activation file;

  • applying the activation file to the machine.

See Activation of Node-Locked License Keys for more information.

Detach a Floating License Key

Let us suppose that you have an active floating license key and you want to detach it from the network pool to temporarily assign it to another machine. This can be done with an express detach (-d) operation.

First, we can list the available products that are visible from this host:

eclair_licman -S P

You will be given a list of products with their respective IDs. For example:

Name       Id     Host       IP              Detachable  Cloned
product_1  12345  host_name  XXX.XXX.XXX.XXX true        accepted
product_2  67890  host_name  XXX.XXX.XXX.XXX false       accepted

In this case we can see that product_1 is detachable. We can then detach it with the following command:

eclair_licman -d 12345 -t 3600

where 12345 is the ID of the product to detach. The -t option specifies the detach time in seconds (1 hour in this case) before the detach is automatically canceled and the license key is returned to the network pool. If you don’t specify the -t option, a default value specified in the eclair_licman help (-h option) will be used.

A detach can be explicitly canceled at any time with the following command:

eclair_licman -c 12345

where 12345 is the ID of the product to cancel the detach. The license key will be returned to the network pool.

License Key Rehosting

This procedure allows you to transfer a license key from one machine (the source computer) to another machine (the recipient computer). The process consists in several steps, which are outlined in detail in Rehosting Licenses Keys.

Options for License key installation and update

Option -F
-F

collect and output a fingerprint of a machine to enable the installation of a new protection key.

Option -U
-U

collect and output information to enable the update of an existing protection key.

Option -A
-A <FILENAME>

apply the license (update) contained in <FILENAME>.

Options for License key rehosting

Option -I
-I

collect and output a fingerprint of a machine to enable the rehosting of an existing protection key.

Option -R
-R <KEY_ID>

rehost the protection key <KEY_ID> to another machine.

Option -r
-r <FILENAME>

use the fingerprint in <FILENAME> to identify the destination machine for a rehost or detach.

Options for Floating license key detach and cancel

Option -d
-d <PRODUCT_ID>

express detach.

Option -t
-t <SECONDS>

specify the time, in seconds, for a detach operation (the default value can be found in the help text with the -h option).

Option -c
-c <PRODUCT_ID>

express cancel detach.

Miscellanea Options

Option -S
-S <PAGE>

query the current hasp installation, where <PAGE> is one of:

  • p or P to show the BUGSENG products that are visible from this host

  • f or F to show the features attached to each product key visible on this host. Option -s k=<KEY_ID> can be used to filter the results

  • k or K show the BUGSENG keys that are visible on this host

Use the uppercase variants of <PAGE> to get aligned output.

Option -o
-o <FILENAME>

direct output to <FILENAME> (default to stdout).

Option -v
-v

display version information on stderr and continue.

Option -h
-h

display help text on stderr and exit.

Advanced Options

Option -C
-C <KEY_ID>

cancel the detached license <KEY_ID> and return it to the network pool before the scheduled expiration.

Option -D
-D <PRODUCT_ID>

detach a license key from a pool of network seats to temporarily assign it to another machine.

Option -s
-s <SCOPE>

defines the scope of the key search, where <SCOPE> is one of:

  • u: unrestricted search (default)

  • h: search HL keys only

  • l: search local keys only

  • j: search local HL keys only

  • r: search remote keys only

  • m=<LM_NAME>: specified license manager name

  • i=<LM_IP>: specified license manager IP address

  • k=<KEY_ID>: specified key id

  • p=PRODUCT_ID: specified product id

The eclair_certran Command

eclair_certran is a command-line tool used for reliable compiler qualification by leveraging precise build data automatically generated by ECLAIR. It supports integration with the SuperTest Aelbert Cuyp 5.0 Release.

Usage:

eclair_certran [OPTIONS] build_data.json

where OPTIONS is a sequence of eclair_certran options and build_data.json is the JSON file generated by the ECLAIR B.CERTRAN service.

The tool enables users to validate compilers by running test suites automatically, leveraging configurations derived from the build data.

Options

The following options are available:

-h, --help

display help text on stderr and exit.

-v, --verbose

enable verbose output.

-u, --units

print the number of translation unit entries listed in the build data file, then exit.

-a, --attributes

print the translation unit attributes listed in the build data file, then exit.

-s <ATTRIBUTE>, --show <ATTRIBUTE>

show the values for the specified attribute listed in the build data file, then exit.

-d, --dry-run

show the steps for compiler validation without performing them.

-S <PATH>, --SuperTest <PATH>

use the SuperTest installation in the specified path for compiler validation.

-D, --extra-size-dep

enable validation with data-size-dependent extra tests (time-consuming).

-O, --extra-optim

enable validation with optimization-sensitive extra tests (time-consuming).

-w <PATH>, --work-dir <PATH>

specify the working directory where compiler validation will be performed.

-j <THREADS>

specify the number of parallel threads to use for compiler qualification.

Examples

Example:

eclair_certran -v -S /path/to/SuperTest --work-dir /tmp/certran_work build_data.json

Run compiler validation using the SuperTest installation at /path/to/SuperTest with verbose output.

Example:

eclair_certran -d -w /tmp/certran_work -S /path/to/supertest build_data.json

Perform a dry run of compiler validation, showing the steps without executing them, using /tmp/certran_work as the working directory.

Integration with SuperTest

eclair_certran integrates with SuperTest Aelbert Cuyp 5.0 to automate compiler validation. It generates configurations based on the build data and executes the test suites provided by SuperTest. The tool ensures compatibility with various compiler families and standards, including support for optimization-sensitive and data-size-dependent tests.

Using ECLAIR from the GUI

The eclair_gui launches the graphical user interface of ECLAIR, called the ECLAIR GUI or simply the GUI in the sequel. The ECLAIR GUI facilitates the following tasks:

  • selecting the services to be enabled;

  • selecting the toolchain components to be intercepted;

  • defining the build process;

  • defining sets of files that should not be analyzed or should be considered as uninteresting for the purpose of reporting.

The GUI allows saving an ECLAIR settings file, with filename extension file:.ecs for later use. It also allows running the analysis and browsing the results.

The GUI is invoked as follows:

eclair_gui [OPTIONS] [FILE.ecs]

where OPTIONS is a sequence of eclair_gui options and FILE.ecs is an optional file containing ECLAIR settings, typically produced in the course of a previous GUI session.

Available eclair_gui Options

Option –headless, (-h)

--headless, -h

run in headless mode;

Option –run, (-r)

--run <CONF>, -r <CONF>

run the specified configuration <CONF> of FILE.ecs;

Option –server, (-s)

--server <URL>, -s <URL>

set <URL> as the URL for communication with the eclair_report server (default is http://127.0.0.1:3786);

Option –version, (-v)

--version, -v

print the GUI version number and exit.

The GUI is self-explanatory: in particular, all GUI elements provide on hover context-sensitive help messages. Moreover, detailed information about using the GUI for the visualization and navigation of the ECLAIR HTML outputs can be found in HTML Outputs.

Environment Variables and Output Control Flags

The advanced step “Environment” of the GUI allows customizing environment variables. There you can, for instance, redefine PATH to ensure the intended versions of relevant tools (such as compilers) are found.

In addition, there are several Boolean control flags that can be used to customize the analysis outputs. While they are implemented as environment variables, their significance is limited to the GUI. These output control flags are:

ECLAIR_verbose

set to true to (significantly) increase the analysis log verbosity (leaving it unset is equivalent to setting it to false);

ECLAIR_explain

set to true to enable the generation of configuration explanation (leaving it unset is equivalent to setting it to true);

ECLAIR_summary_doc, ECLAIR_summary_odt, ECLAIR_summary_txt

set to true to enable the generation of .doc, .odt and textual summary outputs, respectively (leaving them unset is equivalent to setting them to false);

ECLAIR_metrics_tab

set to true to enable the generation of .xlsm and .ods metrics spreadsheets, respectively (leaving them unset is equivalent to setting them to true);

ECLAIR_reports_tab

set to true to enable the generation of .xlsm and .ods report spreadsheets, respectively (leaving them unset is equivalent to setting them to false);

ECLAIR_full_txt

set to true to enable the generation of full textual output (leaving it unset is equivalent to setting it to false);

ECLAIR_full_txt_areas

set to true to enable the presentation of detailed areas in full textual output (leaving it unset is equivalent to setting it to true). Note that, independently from this flag, the presentation of detailed areas is only possible with a site/multisite/enterprise license.

ECLAIR_full_doc, ECLAIR_full_odt

set to true to enable the generation of full output in .doc and .odt formats, respectively (leaving them unset is equivalent to setting them to false);

ECLAIR_full_doc_areas

set to true to enable the presentation of detailed areas in .doc and .odt full output formats (leaving it unset is equivalent to setting it to false). Note that, independently from this flag, the presentation of detailed areas is only possible with a site/multisite/enterprise license. Note also that including detailed areas is likely to make such reports so big and heavy to the point of being unmanageable.

Integrating ECLAIR with IDEs, Editors, and CI Tools

The ECLAIR platform is extremely powerful and can be configured to perform a wide variety of automated software verification tasks. The platform can be used in isolation: besides the development toolchain and an editor, all that is required is an ordinary web browser for the analysis HTML outputs and an office suite to peruse the metrics in spreadsheet format and the printable summary outputs. ECLAIR can also be integrated with other tools. In this chapter we present the integration with IDEs, extensible editors and Continuous Integration (CI) tools.

Different Phases of the Work with ECLAIR

It is useful to distinguish different phases of the work with ECLAIR:

Static analysis

consists in running the build procedure under eclair_env, which will produce (possibly exploiting parallelism) a number of ECLAIR binary output files (see Section The eclair_env Command). Static analysis can take place on the developer’s desktop or on a remote server, wherever the build takes place.

Database generation

is performed using eclair_report: ECLAIR binary output files are assembled into one ECLAIR database file (see Section The eclair_report Command). This can take place on any machine, but it is worthwhile taking into account that the compressed binary output files are usually much smaller than the resulting database file. In other words, if the generation of outputs must take place on a machine different from the one where static analysis took place, transferring the compressed binary outputs is cheaper than transferring the database.

Output generation

is performed, again, using eclair_report to produce various kinds of outputs (see Chapter Outputs). Output generation can take place anywhere the ECLAIR database file is. We further distinguish two kinds of output generation:

offline output generation

is when eclair_report is used in batch mode to produce outputs in an external format (such as pure text or ODT summaries or, depending on the license, HTML or XML detailed outputs);

online output generation

is when eclair_report is used in client-server mode to interact with a web browser, an IDE or an extensible editor (these topics are further elaborated later in this chapter).

Output perusal

is of course performed on the developer’s desktop machine. If the perusal of detailed outputs is performed using an IDE or an extensible editor in order to be able to directly modify the program sources, then there are two possibilities:

  1. The static analysis machine and the developer’s desktop machines are the same, in which case, unless the program sources have been modified after the analysis, the outputs perfectly match the sources because the source files are the same.

  2. The static analysis machine and the developer’s desktop machines are not the same, but the working copy of the program sources in the developer’s desktop correspond to those that were analyzed (modulo a possibly different project root). This is the typical situation when static analysis is performed on an integration server and a version control system is used to maintain consistency between the working copies on different machines.

Different Ways of Working with ECLAIR

The flexibility of ECLAIR design allows supporting all sorts of workflows and distribution patterns. The following sections briefly illustrate the range of possibilities, which are of course not mutually exclusive.

Note that each possibility has technical requirements and licensing requirements. For example, the possibility of generating HTML detailed outputs is only available with certain license kinds: once detailed HTML outputs are generated, they can be browsed anywhere with the help of any web browser. As another example, a solution that requires running different ECLAIR components at the same time on different machines requires license keys to be available (maybe temporarily) on all the involved machines.

All ECLAIR Software Runs on the User’s Desktop

In this scheme only the user’s PC is involved. The main advantages are:

  1. only an individual user license is required;

  2. the user has full control of the analysis configuration and execution.

There are disadvantages as well:

  1. the user’s PC might not be powerful enough to perform the analysis of large projects with any combination of ECLAIR services in a time that is compatible with the work to be done;

  2. the user must be competent enough to operate ECLAIR configuration and execution, or someone has to setup everything up in the user’s PC.

Regarding the first disadvantage, the following points have to be taken into account:

  • If the user is not charged with the task of changing the code or the ECLAIR configuration (e.g., quality assurance personnel in charge of assessing a project under an existing configuration), then the analysis time may not be an issue (e.g., it can be done overnight).

  • If the user has to make source code changes in order to fix software errors and/or to improve compliance with respect to coding standards, he or she will typically work on one or a few source code files at a time. If the build system supports incremental builds, only the portion of the software affected by changes will be recompiled and thus, with the proper ECLAIR configuration, only that portion will be reanalyzed. If the ECLAIR configuration only enables single translation unit checkers the analysis time may be compatible with most sensible workflows.

In order to execute the analysis on his or her own PC, the user has two possibilities: using the ECLAIR GUI or using a script. GUI usage is described in Chapter Using ECLAIR from the GUI. Many demonstration projects available in BUGSENG’s issue-tracking system exemplify both possibilities, providing GUI configuration files as well as batch files, shell scripts, and ECL command files.

No ECLAIR-Connected IDE or Editor Involved

In this scenario, the user has performed the analysis either via the GUI or via scripting and will browse analysis HTML outputs using any web browser, either launched by the GUI or by simple scripting using the -browser and -server options of the eclair_report program.

The interaction with analysis outputs in the browser is described in Section HTML Outputs. If changes have to be made, the ECLAIR detailed reports will provide all the information required to manually direct the IDE or the editor to the program points where modifications have to be made.

External Build, Visualization Inside the IDE or the Editor

This scenario is similar to the previous one, with the difference that the user can visualize the reports inside the IDE or editor. Once ECLAIR has been installed within an IDE or editor, ECLAIR can be enabled by choosing the enable option from the dedicated ECLAIR menu. If the server is local and no server is running, the enable option will start an eclair_report server. Note that once ECLAIR is enabled, the ECLAIR menu will change to include a disable option together with a number of navigation options described below.

We now assume that an IDE or editor is installed, ECLAIR is enabled and that a browser window containing ECLAIR reports is open.

The browser window that has had the most recent interaction with the IDE or editor is called the driving browser window. It is important to understand the following points:

  • The perspective that is available under the IDE or editor is the one of the driving browser window. For instance, if you used the features described in Section HTML Outputs and, in particular, Section Common Features, to hide all information reports, you will not see them in the IDE or editor.

  • Only one IDE or editor can be enabled at any one given time. For instance, if you are using Eclipse and at some stage you choose the Enable option from the ECLAIR menu of Visual Studio Code, you will see that this action disabled Eclipse; if you later want to use Eclipse again, you have to manually re-enable it.

In order to visualize the reports in the IDE or editor, the web browser needs to be paired and should be open in a report or source file view (see Sections Selected Reports Pages and Source File Pages).

If the browser is correctly paired a small ✎ icon is shown in the browser tab title.

Then, by Ctrl+Click or Alt+Click (under Windows and Linux), or Cmd+Click (under macOS) with the mouse on any report area link or any point in a source code view, the user can direct the enabled IDE or editor to take control at exactly that position.

Similarly, holding Ctrl+Click or Alt+Click (under Windows and Linux), or Cmd+Click (under macOS) and then moving the mouse over any source code area the user can select the corresponding program text both in the browser and in the IDE or editor.

An alternative way to direct the IDE or editor to a report area is to use the Edit this area option of the ☰ icon shown near any main report area, in both report and source code views (see Sections Selected Reports Pages and Source File Pages).

The details of how the visualization is displayed depends on the enabled IDE or editor, however many aspects are common by design. The ECLAIR plugin menu will contain the following commands:

Disable

disables this IDE or editor (presumably because the user wants to enable a different IDE or editor).

Stop server

stops all running instances of eclair_report. The interaction with IDEs and editors makes use of a persistent eclair_report server; this covers in the best possible way the usual workflow whereby a user works on one project at a time, making changes, reanalyzing, browsing reports. The only way to stop the server, is to select this command of the ECLAIR menu: use it when switching to a different project or when you stop working on a project and you prefer not having an unused process running on your system.

Pair browser

open a page on the default browser to associate browser with IDE or editor (only if eclair_report server is remote).

First report

goes to the source code for the first report that was shown in the driving browser windows (the perspective of the driving browser window applies to this as well as the following commands).

Previous report

goes to the source code for the previous report.

Next report

goes to the source code for the following report.

Last report

goes to the source code for the last report.

Previous area

goes to the source code for the previous area of the current report.

Next area

goes to the source code for the next area of the current report.

Add tagging comment

adds a tagged comment covering the current report area: see Section Mark Locally and Justify for information on tagged comments.

Run

shows a list of possible Run action that you have set. If you click on an action, ECLAIR will call your custom script passing to it a .eca file containing all the information about the report, the violation, and the rule. For more details see Section Custom Get and Run actions in ECLAIR.

Get on browser

shows a list of possible Get action that you have set. If you click on an action, ECLAIR will download a .eca file containing all the information about the report, the violation, and the rule. For more details see Section Custom Get and Run actions in ECLAIR.

Include in browser selection

shows all the selections not matching the current report. Click on a selection to include in that selection the reports having the same fingerprint of the current report.

Exclude from browser selection

shows all the selections matching the current report. Click on a selection to exclude from that selection the reports having the same fingerprint of the current report.

How to reach the plugin settings panel may differ between the IDEs (read the section dedicated to your IDE).

Build and Visualization from Inside the IDE or the Editor

In this scenario, the build is controlled from within the IDE or the editor. This involves scripting that is dependent on the actual IDE or editor, whose specificities will be treated in the dedicated sections later in this chapter.

The visualization of the reports is as explained in the previous section, with the added benefit of being able to directly perform incremental builds after editing the sources.

All ECLAIR Work Done on the Server

This scheme is the opposite of the one described in Section All ECLAIR Software Runs on the User’s Desktop and comes with dual advantages:

  1. the server is typically a very powerful machine and the user’s PC resources will not be involved;

  2. ordinary users do not need to be able to operate ECLAIR configuration and execution: only the person setting up the server needs to be competent on these aspects of ECLAIR.

Disadvantages are also dual:

  1. a license allowing the generation of detailed outputs in HTML format is required;

  2. the user has no control of the analysis configuration (this is not really a disadvantage in strictly-controlled environments) and execution and can only peruse the resulting detailed outputs.

In order to set up such a scheme, suitable scripting should be developed that performs the analysis upon a given triggering condition (e.g., continuously, every hour, upon a condition based on the version-control system in use). The script should terminate with the generation of HTML outputs as described in Section Producing HTML Outputs and their publication on a web site that is reachable from the local area networks that are compatible with the ECLAIR license.

Faster ECLAIR Analyses on the User’s Desktop, the Others on the Server

This scenario mixes the one presented in Section All ECLAIR Software Runs on the User’s Desktop and the one presented in Section All ECLAIR Work Done on the Server in order to obtain the best of both worlds.

The user would run ECLAIR on the PC, performing incremental analyses that only enable single translation unit checkers. In the most common case the user is working at a specific translation unit, so that a reanalysis will only involve that translation unit and be quite fast.

Full project analyses will be run on the integration server, where all the work done by individual developers is committed. Perusal of the reports generated by such full analyses can take place as described in Section All ECLAIR Work Done on the Server.

Of course, this scenario requires equipping both the user’s PC and the integration server with suitable ECLAIR license keys.

Integrating ECLAIR with Eclipse-Based IDEs

This section is for anyone who uses an IDE based on Eclipse for C/C++ and now needs to know how to use ECLAIR from within that IDE. These instructions have been tested on many Eclipse-based IDEs going back to 2010 and even before.

Installation and Basic Configuration

Installing the ECLAIR Eclipse plugin is done in a very similar way for all Eclipse-based IDEs. We devote a section to each of the main ones.

How to reach the plugin settings panel may differ between the IDEs (read the section dedicated to your IDE), but the settings are still the same. Under that you will find:

  • a field named Command to run eclair_report to be filled with the path of eclair_report;

  • a field named Arguments for eclair_report that allows you to provide to eclair_report additional options and arguments;

  • a field named ECLAIR report server host that allows you to provide the server host where eclair_report is running. By default the value is localhost;

  • a field named Use local ECLAIR report as proxy to be enabled if (and only if) the Eclipse is on a remote machine without an ECLAIR site/multisite/enterprise license. When this option is enabled you need to execute eclair_report -server, e.g., by invoking it from a command line;

  • a field named Force https for ECLAIR report server connection to be enabled if (and only if) eclair_report server should use only HTTPS protocol;

  • a field named Project root directory that allows you to specify the project root path. Leave it empty if the value should be the one provided by the server;

  • a field named Message area tagging that allows you to specify the pattern of the message that will be inserted using the Tagging comment feature (see Selected Reports Pages).

In case the correct version of eclair_report is not the one that is selected via the PATH environment variable, fill the Command to run eclair_report field in the settings panel with the absolute path of the correct version of eclair_report. How to reach the plugin settings panel may differ between the IDEs, read the section dedicated to your IDE.

Arm Development Studio

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Add; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

CodeWarrior Development Studio

Since CodeWarrior Development Studio (at least up to version 11.1) is based on older versions of Eclipse that do not support JRE 8, a special version of the ECLAIR plugin is provided and the installation procedure is different from the standard one.

Open the CodeWarrior Development Studio IDE installation folder (for example: C:\\Freescale\\CW MCU v11.1), then locate its eclipse subfolder.

If a dropins subfolder does not already exist, create it. Copy the ECLAIR plugin JAR from the installation tree into that folder:

PREFIX/eclair-VERSION/share/eclipse/com.bugseng.eclair-jre-6.jar

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation). Finally, restart CodeWarrior Development Studio if it was running to complete the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

CrossCore Embedded Studio

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click OK; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

Eclipse IDE for C/C++ Developers from the Eclipse Foundation

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Add; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

HighTec Development Platform

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Add; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

MCUXpresso IDE

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Add; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the MCUXpresso IDE menu by selecting Preferences…, then choose ECLAIR in the left navigation panel.

QNX Momentics Tool Suite

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Add; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Momentics menu by selecting Preferences…, then choose ECLAIR in the left navigation panel.

Renesas e2studio

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click OK; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

SiFive Freedom Studio

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Add; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

Silicon Labs Simplicity Studio

In order to install the ECLAIR Eclipse plugin, type the Ctrl+3 key combination when the Simplicity Studio main window has focus and start typing Install New Software… until you can select it. Then click on Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click OK; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

STM32CubeIDE

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Add; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

TASKING TriCore Eclipse IDE

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Add; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

Texas Instruments Code Composer Studio

Eclipse-based versions (12.8.1 and earlier)

Code Composer Studio up to version 12.8.1 is based on Eclipse. Follow the instructions below for installation and configuration.

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Add; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

Theia-based versions (20.0.0 and later)

Starting from version 20.0.0, Code Composer Studio is based on Theia, an IDE framework that is compatible with VS Code extensions. For those versions, use the VS Code extension (VSIX file) instead of the Eclipse plugin. Refer to Section Integrating ECLAIR with Visual Studio Code for installation instructions.

Xilinx Vitis IDE

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Add; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Help menu by clicking on Install New Software…, choose Manage…, then choose ECLAIR in the left navigation panel.

DAVE (Infineon)

In order to install the ECLAIR Eclipse plugin, from the Help menu choose Install New Software…, then Add…, then Archive…, then select

PREFIX/eclair-VERSION/share/eclipse/eclair.zip

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Add; once that is done, select ECLAIR plugin, click Next twice, review the license agreement and accept its terms if you wish to continue, click Finish and then click Restart Now to conclude the installation.

You can reach the ECLAIR plugin settings from the Window menu by selecting Preferences, then choose ECLAIR in the left navigation panel.

Visualizing and Editing

Assuming that a browser window containing ECLAIR reports is open and ECLAIR is enabled as detailed in External Build, Visualization Inside the IDE or the Editor, the main region of Eclipse will contain the selected source code. If ECLAIR is selected in the control bar for the lower region, this region will contain the report message. Source code can now be edited and the changes saved in the usual way.

Note that if the code is not syntactically present in the source file, the report area will be labelled as <preprocessed ...> and the IDE will block any attempts to edit the code, displaying the Read-Only message in the bottom bar.

Running ECLAIR Analysis from within the IDE

Sample scripting for running the ECLAIR analysis from within an Eclipse-based IDE can be found in the corresponding Windows and Linux demos ECLAIR-MAJ_MIN_demo_crc_Windows_GCC_Eclipse_CDT and ECLAIR-MAJ_MIN_demo_crc_Linux_GCC_Eclipse_CDT.

where MAJ_MIN is the major and minor version numbers of ECLAIR separated by a dot (it corresponds to the complete version number by removing the final patch number).

For further information about the demo projects see chapter ECLAIR Demo Projects of the ECLAIR Evaluation Guide.

The most important file in the demos is README.txt, which explains how to proceed.

In essence, for each of the project existing configurations that should undergo static analysis, two new configurations must be added. For simplicity, let us suppose that there is just one existing project configuration. Then the sample scripting can be used to build two new configurations, called, e.g.,

ECLAIR

runs an incremental analysis (that is, only what is compiled/linked is analyzed) of the existing configuration;

ECLAIR_STU

as above, but only analyzing with respect to guidelines supported by single translation unit checkers to reduce analysis time;

ECLAIR_FINAL

as ECLAIR, but this also generates textual reports;

ECLAIR_FILE

runs an analysis of the currently opened file.

See Sections All ECLAIR Software Runs on the User’s Desktop and Faster ECLAIR Analyses on the User’s Desktop, the Others on the Server to understand in which scenarios the second configuration is interesting.

Integrating ECLAIR with Netbeans-Based IDEs

This section is for anyone who uses an IDE based on Netbeans and now needs to know how to use ECLAIR from within that IDE. These instructions have been tested on NetBeans 14 and MPLABX v6.00.

Installation and Basic Configuration

Installing the ECLAIR Netbeans plugin is done in a very similar way for all NetBeans-based IDEs. We devote a section to each of the main ones.

How to reach the plugin settings panel may differ between the IDEs (read the section dedicated to your IDE), but the settings are still the same. Under that you will find:

  • a field named Command to run eclair_report to be filled with the path of eclair_report;

  • a field named Arguments for eclair_report that allows you to provide to eclair_report additional options and arguments;

  • a field named ECLAIR report server host that allows you to provide the server host where eclair_report is running. By default the value is localhost;

  • a field named Use local ECLAIR report as proxy to be enabled if (and only if) the IDE is on a remote machine without an ECLAIR site/multisite/enterprise license. When this option is enabled you need to execute eclair_report -server, e.g., by invoking it from a command line;

  • a field named Force https for ECLAIR report server connection to be enabled if (and only if) eclair_report server should use only HTTPS protocol;

  • a field named Project root directory that allows you to specify the project root path. Leave it empty if the value should be the one provided by the server;

  • a field named Message area tagging that allows you to specify the pattern of the message that will be inserted using the Tagging comment feature (see Selected Reports Pages).

In case the correct version of eclair_report is not the one that is selected via the PATH environment variable, fill the Command to run eclair_report field in the settings panel with the absolute path of the correct version of eclair_report. How to reach the plugin settings panel may differ between the IDEs, read the section dedicated to your IDE.

NetBeans IDE

In order to install the ECLAIR plugin, from the Tools menu in the top menu bar, choose Plugins, then open the Downloaded tab, then click on Add Plugins, then select

PREFIX/eclair-VERSION/share/netbeans/eclair-plugin-VERSION-netbeans.nbm

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Open; once that is done, select ECLAIR plugin, click Install and follow the installation wizard.

The plugin may be shown as self-signed, but the signature is available by selecting the Show details button after expanding the self-signed node and selecting the plugin’s name.

You can reach the ECLAIR plugin settings from the Tools menu by selecting Options, then choose ECLAIR in the top navigation panel.

MPLAB X IDE

In order to install the ECLAIR plugin, from the Tools menu in the top menu bar, choose Plugins, then open the Downloaded tab, then click on Add Plugins, then select

PREFIX/eclair-VERSION/share/netbeans/eclair-plugin-VERSION-mplabx.nbm

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); then click Open; once that is done, select ECLAIR plugin, click Install and follow the installation wizard.

The plugin may be shown as not signed, but the signature can be verified by running the command jarsigner --verify eclair-plugin-3.16.0-mplabx.nbm.

You can reach the ECLAIR plugin settings from the Tools menu by selecting Options, then choose ECLAIR in the top navigation panel.

Usage

A new ECLAIR menu will appear in the top menu bar of the IDE, and an ECLAIR tab in the Output window is created. When the user selects Enable a new tab titled ECLAIR will open (if not, it can be opened by clicking on Window->ReportView). When a report is selected from the browser, it will appear inside this window.

Assuming that a browser window containing ECLAIR reports is open and ECLAIR is enabled as detailed in External Build, Visualization Inside the IDE or the Editor, the main region of NetBeans will contain the selected source code. If ECLAIR is selected in the control bar for the lower region, this region will contain the report message. Source code can now be edited and the changes saved in the usual way.

Note that if the code is not syntactically present in the source file, the report area will be labelled as <preprocessed ...> and the IDE will block any attempts to edit the code.

All actions except Add tagging comment, Run and Get on browser can be associated with a keybining by setting entries in the Tools->Options->Keymap settings page. All ECLAIR options are under the ECLAIR and ECLAIR/AreaNode categories.

Running ECLAIR Analysis from within MPLABX

Sample scripting for running the ECLAIR analysis from within MPLABX IDE can be found in the corresponding Windows and Linux demos ECLAIR-MAJ_MIN_demo_crc_Windows_XC32_MPLABX and ECLAIR-MAJ_MIN_demo_crc_Linux_XC32_MPLABX.

where MAJ_MIN is the major and minor version numbers of ECLAIR separated by a dot (it corresponds to the complete version number by removing the final patch number).

For further information about the demo projects see chapter ECLAIR Demo Projects of the ECLAIR Evaluation Guide.

The most important file in the demos is README.txt, which explains how to proceed.

Select the ECLAIR Tasks entry on the project tree panel, and then double-click on one of the four available tasks:

ECLAIR_FULL

runs an incremental analysis (that is, only what is compiled/linked is analyzed) of the existing configuration;

ECLAIR_STU

as above, but only analyzing with respect to guidelines supported by single translation unit checkers to reduce analysis time;

ECLAIR_FINAL

as ECLAIR_FULL, but this also generates textual reports;

ECLAIR_FILE

runs an analysis of the currently opened file.

The task logs will be displayed on the Output windows under the Scripting tab.

See Sections All ECLAIR Software Runs on the User’s Desktop and Faster ECLAIR Analyses on the User’s Desktop, the Others on the Server to understand in which scenarios the second configuration is interesting.

Additional notes

  • When navigating a report, if the currently selected area’s text is not displayed in the editor, then double click on that area to update the view.

  • An additional restart of the IDE may be needed when installing or uninstalling the plugin.

Integrating ECLAIR with IDEs based on the IntelliJ Platform

This section is for anyone who uses an IDE based on the IntelliJ Platform and now needs to know how to use ECLAIR from within that IDE. These instructions have been tested on IntelliJ IDEA 2022.2.3 (Community Edition), CLion 2021.3.4 and Android Studio 2022.2.1.

Installation and Basic Configuration

Installing the ECLAIR IntelliJ plugin is done in a very similar way for all IDEs based on the IntelliJ Platform.

In order to install the ECLAIR plugin, select the File menu in the top menu and bar choose Settings, then open the Plugins tab on the left side, click on the gear icon next to the Installed tab and select Install Plugin from Disk. Select the file

PREFIX/eclair-VERSION/share/intellij/eclair-plugin-VERSION-VARIANT.jar

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); VARIANT is the variant of the plugin to select depending on IntelliJ Platform version of the IDE (IC-2023.1-or-later or IC-2022.3-or-earlier).

A new ECLAIR menu will appear in the top menu bar of the IDE, and a new tool window titled ECLAIR will appear in the bottom bar of the IDE (next to other tool windows, such as Problems or Terminal); if the component is not shown or has been hidden by mistake, enable it from View->Tool Windows->ECLAIR. Installing the plugin will add a new status bar component as well, showing whether the plugin is connected to a report server. The visibility of such a component can be toggled by selecting ECLAIR status from the View->Appearance->Status Bar Widgets menu.

The ECLAIR plugin settings can be reached from the ECLAIR menu in the top menu bar, by selecting the Settings item, or by clicking on the status bar widget.

Under that you will find:

  • a field named Command to run eclair_report to be filled with the path of eclair_report;

  • a field named Arguments for eclair_report that allows you to provide to eclair_report additional options and arguments;

  • a field named ECLAIR report server host that allows you to provide the server host where eclair_report is running. By default the value is localhost;

  • a field named Use local ECLAIR report as proxy to be enabled if (and only if) the IDE is on a remote machine without an ECLAIR site/multisite/enterprise license. When this option is enabled you need to execute eclair_report -server, e.g., by invoking it from a command line;

  • a field named Force https for ECLAIR report server connection to be enabled if (and only if) eclair_report server should use only HTTPS protocol;

  • a field named Project root directory that allows you to specify the project root path. Leave it empty if the value should be the one provided by the server;

  • a field named Message area tagging that allows you to specify the pattern of the message that will be inserted using the Tagging comment feature (see Selected Reports Pages).

In case the correct version of eclair_report is not the one that is selected via the PATH environment variable, fill the Command to run eclair_report field in the settings panel with the absolute path of the correct version of eclair_report.

Any modification to the plugin settings is applied only to the current project, so it is recommended to check them before enabling the plugin.

Usage

Assuming that a browser window containing ECLAIR reports is open and the ECLAIR tool window is visible in the bottom bar of the IDE, the plugin functionality can be activated by selecting the ECLAIR->Enable action and wait for the status bar to show ECLAIR ONLINE. Selecting a report from the browser as detailed in External Build, Visualization Inside the IDE or the Editor will cause the IDE to open an editor tab containing the relevant source code. Source code can now be edited and the changes saved in the usual way.

Note that if the code is not syntactically present in the source file, the file will be labelled as <...> and the IDE will block any attempts to edit the code, such as adding a tagging comment. The same holds for files not present in the machine running the IDE; in that case, they will be labelled as @....

The tool window contains two content tabs: one showing the plugin log, and a panel showing a list of available actions of the left side, as well as a tree containing the currently selected report and its areas. If no report has been selected, the panel will be empty.

If the ECLAIR->Enable action fails, check the plugin log in the ECLAIR tool window to see the error message.

Keybindings can be associated to any action defined by the plugin. To do so, open the File->Settings->Keymap panel, and select Main Menu->ECLAIR from the tree; new bindings can be defined by right-clicking on the desired item. Be aware that the Add tagging comment, Run, Get on browser, Include in browser selection and Exclude from browser selection menus will be populated dynamically by defining the corresponding entities in the browser.

Running ECLAIR Analysis from within IDEs based on the IntelliJ Platform

Sample scripting for running the ECLAIR analysis from within IntelliJ IDE can be found in the corresponding Linux demos ECLAIR-MAJ_MIN_demo_crc_Linux_GCC_CLion.

where MAJ_MIN is the major and minor version numbers of ECLAIR separated by a dot (it corresponds to the complete version number by removing the final patch number).

For further information about the demo projects see chapter ECLAIR Demo Projects of the ECLAIR Evaluation Guide.

The most important file in the demos is README.txt, which explains how to proceed.

Once the project has been set up, you can launch the following tasks from the menu Tools->ECLAIR Tools

ECLAIR_FULL

runs an incremental analysis (that is, only what is compiled/linked is analyzed) of the existing configuration;

ECLAIR_STU

as above, but only analyzing with respect to guidelines supported by single translation unit checkers to reduce analysis time;

ECLAIR_FINAL

as ECLAIR_FULL, but this also generates textual reports;

ECLAIR_FILE

runs an analysis of the currently opened file.

The task logs will be displayed in a tab inside the Run tool window at the bottom of the screen.

See Sections All ECLAIR Software Runs on the User’s Desktop and Faster ECLAIR Analyses on the User’s Desktop, the Others on the Server to understand in which scenarios the second configuration is interesting.

Additional notes

  • If more than one IDE window is opened on different projects, the plugin can be used indipendently in each window, given that the target eclair_report server host is different (e.g. eclairit.com and localhost).

  • The plugin will be automatically disabled when its settings are changed

Integrating ECLAIR with Visual Studio

This section is for anyone who uses Visual Studio 2017, Visual Studio 2019 or Visual Studio 2022 and now needs to know how to use ECLAIR from within that IDE.

Installation and Basic Configuration

In order to install the ECLAIR Visual Studio plugin: if you are using Visual Studio 2017 and Visual Studio 2019 double click on

PREFIX/eclair-VERSION/share/visualstudio/Eclair-VS17.vsix

if you are using Visual Studio 2022 double click on

PREFIX/eclair-VERSION/share/visualstudio/Eclair-VS22.vsix

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); Select the Visual Studio versions in which you want to install the plugin, then choose Install.

To reach the plugin settings page click on the Tools menu select Options…, then click on ECLAIR in the left panel. You will find:

  • a field named Eclair report command to be filled with the path of eclair_report. Here you can also add any additional options and argument to eclair_report;

  • a field named Eclair report command arguments to be filled with a list of arguments and options for eclair_report.

  • a field named ECLAIR report host that allows you to provide the server host where eclair_report is running. By default the value is localhost;

  • a field named Force SSL to be enabled if (and only if) eclair_report server should use only HTTPS protocol;

  • a field named Project root that allows you to specify the project root path. Leave it empty if the value should be the one provided by the server;

  • a field named Tag area message that allows you to specify the pattern of the message that will be inserted using the Tagging comment feature (see Selected Reports Pages);

  • a field named Use proxy to be enabled if (and only if) Visual Studio is on a remote machine without an ECLAIR site/multisite/enterprise license. When this option is enabled you need to execute eclair_report -server, e.g., by invoking it from a command line.

In case the correct version of eclair_report is not the one that is selected via the PATH environment variable, fill the Eclair Report Command field with the absolute path of the correct version of eclair_report.

Visualizing and Editing

Assuming that a browser window containing ECLAIR reports is open and ECLAIR is enabled as detailed in External Build, Visualization Inside the IDE or the Editor, the main section of Visual Studio will contain the selected source code. If ECLAIR is selected in the control bar for the lower section, this section will contain the report message. Source code can now be edited and all changes can be saved in the usual way.

Note that if the code is not syntactically present in the source file, the report area will be labelled as <preprocessed ...> and the IDE will block any attempts to edit the code.

Integrating ECLAIR with Visual Studio Code

This section is for anyone who uses Visual Studio Code for C/C++ and now needs to know how to use ECLAIR from within the editor.

Installation and Basic Configuration

In order to install the ECLAIR Visual Studio (VS) Code plugin, you should bring up the Extensions view. There are three ways of doing that:

  1. Clicking on the Extensions icon in the activity bar on the left-hand side of VS Code

    _images/vs-code-extensions-view-icon.png

  2. Typing the key combination Ctrl Shift X.

  3. From the File menu, choosing Preferences, then Extensions.

Once in the Extensions view, click on the … icon on its top-right corner and select Install from VSIX…, then direct the file browser to

PREFIX/eclair-VERSION/share/vscode/eclair-X.Y.Z.vsix

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation), whereas X.Y.Z is the version number of ECLAIR VS Code plugin. Once that file is selected, click on Install. Installation will try to connect to an existing eclair_report server: if none exist an error message will be displayed, which can be safely ignored. In any case, the installation process should result into the appearance of ECLAIR X.Y.Z followed by BUGSENG in the Extensions view and in the display of the following message in the bottom-right corner of VS Code’s window: Completed installing the extension ECLAIR.

To reach the plugin settings page click on the Manage gear button to the right of BUGSENG in the Extensions view, then choose Extension Settings. You will find:

  • a field named Eclair Report Command to be filled with the path of eclair_report. Here you can also add any additional options and argument to eclair_report;

  • a field named ECLAIR Report Host that allow you to provide the server host where eclair_report is running. By default the value is localhost;

  • a field named Proxy to be enabled if (and only if) Visual Studio Code is on a remote machine without an ECLAIR site/multisite/enterprise license. When this option is enabled you need to execute eclair_report -server, e.g., by invoking it from a command line;

  • a field named Force SSL to be enabled if (and only if) eclair_report server should use only HTTPS protocol;

  • a field named Project Root that allow you to specify the project root path. Leave it empty if the value should be the one provided by the server;

  • a field named Tag Area Message that allow you to specify the pattern of the message that will be inserted using the Tagging comment feature (see Selected Reports Pages).

In case the correct version of eclair_report is not the one that is selected via the PATH environment variable, fill the Eclair Report Command field with the absolute path of the correct version of eclair_report.

Visualizing and Editing

Assuming that a browser window containing ECLAIR reports is open and ECLAIR is enabled as detailed in External Build, Visualization Inside the IDE or the Editor, the main region will contain the selected source code. If ECLAIR REPORT is selected in the control bar for the lower region, this region will contain the report message. Source code can now be edited and the changes saved in the usual way.

Note that if the code is not syntactically present in the source file, the report area will be labelled as <preprocessed ...> and the editor will block any attempts to edit the code, displaying the Cannot edit in read-only editor message in a pop-up window.

Running ECLAIR Analysis from within Visual Studio Code

Sample scripting for running the ECLAIR analysis from within VSCode can be found in the corresponding Windows and Linux demos ECLAIR-VERSION_demo_crc_Linux_GCC_VSCode and ECLAIR-VERSION_demo_crc_Windows_GCC_VSCode.

where MAJ_MIN is the major and minor version numbers of ECLAIR separated by a dot (it corresponds to the complete version number by removing the final patch number).

For further information about the demo projects see chapter ECLAIR Demo Projects of the ECLAIR Evaluation Guide.

The most important file in the demos is README.txt, which explains how to proceed.

Under Terminal on the window menu bar select Run Task or press F1 and select Task: Run Task. The menu shown will have 3 ECLAIR options:

ECLAIR prepare

selecting this prepares the project for the build;

ECLAIR build

selecting this after an edit does an incremental build of the project;

ECLAIR STU build

as above, but only analyzing with respect to guidelines supported by single translation unit checkers to reduce analysis time.

ECLAIR clean

selecting this cleans the project.

Integrating ECLAIR with Emacs

This section is for anyone who uses the emacs editor and now needs to know how to use ECLAIR from within emacs.

Installation and Basic Configuration

In order to install the ECLAIR Emacs plugin, you should load into Emacs

PREFIX/eclair-VERSION/share/emacs/eclair.elc

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation); The most convenient way for doing so is to include Emacs Lisp code like the following into the .emacs file located into your home directory:

;; Load the ECLAIR Emacs plugin.
(setq eclair_plugin_filename "/opt/bugseng/eclair/share/emacs/eclair.elc")
(if (file-exists-p eclair_plugin_filename)
    (load eclair_plugin_filename))

Then open Emacs in the usual way. There will now be an extra option ECLAIR in the window menu bar.

In case the correct version of eclair_report is not the one that is selected via the PATH environment variable, provide the correct path editing to Eclair Report Command in the plugin options.

To reach the plugin options click on the Options menu, select Customize Emacs and then Browse Customization Groups. If you expand the Eclair group, you will see:

  • an option named Eclair Report Command to be filled with the path of eclair_report and an optional list arguments;

  • an option named ECLAIR Host that allow you to provide the server host where eclair_report is running. By default the value is localhost;

  • an option named Eclair Proxy to be enabled if (and only if) Emacs is on a remote machine without an ECLAIR site/multisite/enterprise license. When this option is enabled you need to execute eclair_report -server, e.g., by invoking it from a command line;

  • an option named Eclair Force Ssl to be enabled if (and only if) eclair_report server should use only HTTPS protocol;

  • an option named Eclair Preview where you can enable or disable area preview on mouse over;

  • an option named Eclair Project Root that allow you to specify the project root path. Leave it empty if the value should be the one provided by the server;

  • an option named Eclair Tag Format that allow you to specify the pattern of the message that will be inserted using the Tagging comment feature (see Selected Reports Pages).

  • an option named Eclair Mode where you can enable or disable the ECLAIR menu;

  • a series of graphical options.

Visualizing and Editing

Assuming that a browser window containing ECLAIR reports is open and emacs is enabled as detailed in External Build, Visualization Inside the IDE or the Editor, two emacs windows will open: one containing the report message and the other containing the source code. Source code can now be edited and the changes saved in the usual way.

Note that if the code is not syntactically present in the source file, the report area will be labelled as <preprocessed ...> and emacs will block any attempts to edit the code, indicating in the minibuffer region Buffer is read only.

Integrating ECLAIR with Jenkins

This section is for anyone who uses Jenkins and needs to know how to integrate ECLAIR with Jenkins. This will allow quickly finding the changes that caused a certain violation, obtaining some statistical information about reports over time and so on. We assume the reader is familiar with Jenkins.

The ECLAIR Jenkins plugin relies on Warning Next Generation Plugin: here we will describe only the features related to the ECLAIR Jenkins plugin: the reader is referred to Warning Next Generation Plugin full documentation for more details.

Due to some limitations of the Warning Next Generation Plugin the plugin can efficiently handle projects with a limited number of violations.

We suggest using the plugin only if the project contains reports in the order of tens of thousands, for bigger databases we suggest using the general solution proposed in Integrating ECLAIR with Services for Software Development and CI.

A small demonstration of some ECLAIR capabilities when used from within Jenkins can be found in the corresponding Windows and Linux demos ECLAIR-MAJ_MIN_demo_crc_Windows_Jenkins_GCC and ECLAIR-MAJ_MIN_demo_crc_Unix_MC3_GCC_Jenkins.

where MAJ_MIN is the major and minor version numbers of ECLAIR separated by a dot (it corresponds to the complete version number by removing the final patch number).

For further information about the demo projects see chapter ECLAIR Demo Projects of the ECLAIR Evaluation Guide.

The most important file in the demos is README.txt, which explains how to proceed.

Installation and Global Configuration

To install the ECLAIR Jenkins plugin, from the Plugin Manager page choose Advanced…, then under Upload Plugin select

PREFIX/eclair-VERSION/share/jenkins/eclair-JenkinsJENKINS_VERSION.hpi

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation). JENKINS_VERSION is the Jenkins version: for example 2.3 is for Jenkins versions from 2.3XX.Y to 2.4XX.Y excluded, while 2.4 for Jenkins versions starting from from 2.4XX.Y.

Click the Upload button and, once installation is done, restart Jenkins.

Once you have installed the plugin you need to setup it, so from the Manage Jenkins page, choose Configure System and locate a section named ECLAIR.

Under that you will find:

  • a field named ECLAIR server ownership to be enabled if (and only if) the eclair_report server needs to be launched and managed by Jenkins;

  • a field named ECLAIR report command to be filled with the path of eclair_report or left empty if you have already added the directory which contains the file to Jenkins PATH (which you can do via Manage Jenkins, Configure System, Global properties, Environment variables);

  • a field named ECLAIR report command additional args that allow you to provide to eclair_report additional options and arguments;

  • a field named Use ECLAIR report proxy mode to be enabled if (and only if) the Jenkins server is on a remote machine without an ECLAIR site/multisite/enterprise license. When this option is enabled you need to execute eclair_report -server, e.g., by invoking it from a command line;

  • a field named Use ECLAIR SSL mode to be enabled if (and only if) eclair_report server should use only HTTPS protocol;

  • a field named ECLAIR SSL certificate path to be filled if ECLAIR server ownership and Use ECLAIR SSL Mode are enabled, to specify the certificate file path for the eclair_report server. The default certificate is in PREFIX/eclair-VERSION/lib/ssl/eclair_report.pem;

  • a field named Allow ECLAIR actions be enabled only if you want to force eclair_report server launched by Jenkins to be administered by remote clients. (relevant only if ECLAIR server ownership is enabled).

Job Configuration

We assume that you already have an analysis script with which you run ECLAIR on your project and builds the corresponding ECLAIR database. To this you should add the generation of the Jenkins report file using -reports_jenkins.

On Windows, the resulting script might have the following form:

analyze.bat
 1@echo off
 2setlocal EnableDelayedExpansion
 3rem Absolute path of the ECLAIR bin directory.
 4set ECLAIR_BIN_DIR=C:\Program Files\BUGSENG\eclair-3.15.0\bin
 5
 6rem Directory where this script resides: usually in a directory named "ECLAIR".
 7set SCRIPT_DIR=%~dp0
 8rem Directory where to put all ECLAIR output and temporary files.
 9set ECLAIR_OUTPUT_DIR=%SCRIPT_DIR%out
10
11rem Absolute path of the toolchain bin directory.
12set TOOLCHAIN_BIN_DIR=C:\Program Files\gcc-arm-none-eabi-8-2018-q4-major\bin
13rem Absolute paths of toolchain components that ECLAIR should intercept.
14set CC_ALIASES="%TOOLCHAIN_BIN_DIR%/arm-none-eabi-gcc.exe"
15set CXX_ALIASES="%TOOLCHAIN_BIN_DIR%/arm-none-eabi-g++.exe"
16set AS_ALIASES="%TOOLCHAIN_BIN_DIR%/arm-none-eabi-as.exe"
17set AR_ALIASES="%TOOLCHAIN_BIN_DIR%/arm-none-eabi-ar.exe"
18set LD_ALIASES="%TOOLCHAIN_BIN_DIR%/arm-none-eabi-ld.exe"
19
20rem ECLAIR workspace.
21set ECLAIR_WORKSPACE=%ECLAIR_OUTPUT_DIR%\eclair_workspace
22rem Destination file for the ECLAIR diagnostics.
23set ECLAIR_DIAGNOSTICS_OUTPUT=%ECLAIR_OUTPUT_DIR%\DIAGNOSTICS.txt
24rem ECLAIR binary data directory and project database.
25set ECLAIR_DATA_DIR=%ECLAIR_OUTPUT_DIR%\.data
26
27rem Identifies the particular build of the project.
28set ECLAIR_PROJECT_NAME=MyProject_Release
29rem All paths mentioned in ECLAIR reports that are below this directory
30rem will be presented as relative to ECLAIR_PROJECT_ROOT.
31set PARENT_DIR=%SCRIPT_DIR%..
32set ECLAIR_PROJECT_ROOT=%PARENT_DIR%\MyProject
33
34rem Erase and recreate the output directory and the data directory.
35rd /s /q "%ECLAIR_OUTPUT_DIR%" 2>nul
36md "%ECLAIR_DATA_DIR%" || exit /b
37
38rem Clean the build, so that the project will be rebuilt from scratch.
39pushd "%ECLAIR_PROJECT_ROOT%\build\Release"
40make clean || exit /b
41
42rem Perform the build (from scratch) in an ECLAIR environment.
43"%ECLAIR_BIN_DIR%\eclair_env" "-eval_file='%SCRIPT_DIR:\=\\%analysis.ecl'" ^
44                              -- make || exit /b
45popd
46
47rem Create the project database.
48set PROJECT_ECD=%ECLAIR_DATA_DIR%\PROJECT.ecd
49"%ECLAIR_BIN_DIR%\eclair_report" "-create_db='%PROJECT_ECD:\=\\%'" ^
50        "%ECLAIR_DATA_DIR:\=\\%\\FRAME.*.ecb" ^
51        -load || exit /b
52
53rem Create the Jenkins reports file.
54set JENKINS_XML=%SCRIPT_DIR%\jenkins.xml
55"%ECLAIR_BIN_DIR%\eclair_report" "-db='%PROJECT_ECD:\=\\%'" ^
56        "-reports_jenkins='%JENKINS_XML:\=\\%'" || exit /b
57endlocal

On Linux, the resulting script might have the following form:

analyze.sh
 1#!/bin/bash
 2# Stop immediately if any executed command has exit status different from 0.
 3set -e
 4
 5# Absolute path of the ECLAIR bin directory.
 6ECLAIR_BIN_DIR="/opt/bugseng/eclair-3.15.0/bin"
 7
 8# Directory where this script resides: usually in a directory named "ECLAIR".
 9SCRIPT_DIR="$(cd "$(dirname $0)" ; echo ${PWD})"
10# Directory where to put all ECLAIR output and temporary files.
11ECLAIR_OUTPUT_DIR="${SCRIPT_DIR}/out"
12
13# Absolute path of the toolchain bin directory.
14TOOLCHAIN_BIN_DIR="/opt/gcc-arm-none-eabi-8-2018-q4-major/bin"
15# Absolute paths of toolchain components that ECLAIR should intercept.
16export CC_ALIASES="\"${TOOLCHAIN_BIN_DIR}/arm-none-eabi-gcc\""
17export CXX_ALIASES="\"${TOOLCHAIN_BIN_DIR}/arm-none-eabi-g++\""
18export AS_ALIASES="\"${TOOLCHAIN_BIN_DIR}/arm-none-eabi-as\""
19export AR_ALIASES="\"${TOOLCHAIN_BIN_DIR}/arm-none-eabi-ar\""
20export LD_ALIASES="\"${TOOLCHAIN_BIN_DIR}/arm-none-eabi-ld\""
21
22# ECLAIR workspace.
23export ECLAIR_WORKSPACE="${ECLAIR_OUTPUT_DIR}/eclair_workspace"
24# Destination file for the ECLAIR diagnostics.
25export ECLAIR_DIAGNOSTICS_OUTPUT="${ECLAIR_OUTPUT_DIR}/DIAGNOSTICS.txt"
26# ECLAIR binary data directory and project database.
27export ECLAIR_DATA_DIR="${ECLAIR_OUTPUT_DIR}/.data"
28
29# Identifies the particular build of the project.
30export ECLAIR_PROJECT_NAME="MyProject_Release"
31# All paths mentioned in ECLAIR reports that are below this directory
32# will be presented as relative to ECLAIR_PROJECT_ROOT.
33PARENT_DIR="$(dirname "${SCRIPT_DIR}")"
34export ECLAIR_PROJECT_ROOT="${PARENT_DIR}/MyProject"
35
36# Erase and recreate the output directory and the data directory.
37rm -rf "${ECLAIR_OUTPUT_DIR}"
38mkdir -p "${ECLAIR_DATA_DIR}"
39(
40    # Clean the build, so that the project will be rebuilt from scratch.
41    cd "${ECLAIR_PROJECT_ROOT}/build/Release"
42    make clean
43
44    # Perform the build (from scratch) in an ECLAIR environment.
45    "${ECLAIR_BIN_DIR}/eclair_env" "-eval_file='${SCRIPT_DIR}/analysis.ecl'" \
46                                   -- make
47)
48# Create the project database.
49PROJECT_ECD="${ECLAIR_DATA_DIR}/PROJECT.ecd"
50"${ECLAIR_BIN_DIR}/eclair_report" "-create_db='${PROJECT_ECD}'" \
51                                  "${ECLAIR_DATA_DIR}"/FRAME.*.ecb \
52                                  -load
53
54# Create the Jenkins reports file.
55JENKINS_XML="${SCRIPT_DIR}/jenkins.xml"
56"${ECLAIR_BIN_DIR}/eclair_report" "-db='${PROJECT_ECD}'" \
57                                  "-reports_jenkins='${JENKINS_XML}'"

Note that these are just examples: the only essential thing is that the script generates the ECLAIR database as described in Section The eclair_report Command and the corresponding Jenkins report file. Said that, we recommend the following:

  • place the analysis script in a directory named ECLAIR just under the project root;

  • generate the ECLAIR database and diagnostic output in a subdirectory of ECLAIR named out (as you will see we will configure Jenkins to archived this directory);

  • generate the Jenkins report file directly under ECLAIR (so it will not be archived: archiving it would be pointless).

If you decide to use the above scripts as a starting point, please make sure you adapt at least the highlighted lines to your use case.

In the sequel, assume that you have configured an ECLAIR job on Jenkins which produces an ECLAIR database and the Jenkins report file, and that you have tested that such machinery works as expected: there is no point in going forward until this is not the case.

These are the steps to be followed in order to adapt your ECLAIR job for using the ECLAIR Jenkins plugin:

  1. Add a Post-build Action called Archive the artifacts and select the path where the job writes the ECLAIR database.

  2. Add a Post-build Action called Record compiler warnings and static analysis results selecting ECLAIR on the Tool field.

  3. Fill the Report File Pattern with the relative path of the Jenkins reports file that is generated by analysis script (e.g., ECLAIR/jenkins.xml).

  4. If necessary, edit ECLAIR database path. If you have followed the above advice, you do not need to change the default ECLAIR/out/PROJECT.ecd otherwise it should be set to actual relative path of the ECLAIR database.

Usage

In a build page of a job configured for ECLAIR, the left-hand side panel will contain:

  • an ECLAIR Project Home link pointing to the eclair_report homepage of the reports database generated by the selected build (see Section HTML Outputs).

  • an ECLAIR Warnings link pointing to the page with the ECLAIR reports generated for the current build.

In ECLAIR Warnings, the second word is hard-coded in the Warning Next Generation Plugin. This a bit unfortunate, as not all ECLAIR reports are meant to convey warnings.

Note that, in order to browse the ECLAIR reports an eclair_report server must be running on the Jenkins machine. Enabling the option ECLAIR server ownership Jenkins will automatically start a new eclair_report server. If a server is already running, this will be killed. In addition, if the Jenkins server is on a remote machine without an ECLAIR site/multisite/enterprise license, a locally running eclair_report server must be available and the ECLAIR report proxy must be enabled as described above.

When you are in the ECLAIR Warnings page of the build, in the Modules tab you will see the report counts by service, whereas in the Folders, Files, Categories, Types tab you will see the report counts by directories, files, categories and types respectively.

In the Issues tabs, if the license allows that, you can consult ECLAIR detailed reports clicking on file names will open a new browser tab on the named file, in the context of that report. Just hovering on the file name will display a preview area in the current browser tab, unless you disable Mouse over preview. Alternatively, if you enable Preview window, a new browser window will be opened, and previews will always be shown in that window. If your license does not allow you access to detailed reports, disabling both Mouse over preview and Preview window will spare you from seeing blank previews.

Running Pipelines Within a Docker Container

Running pipelines in a Docker container avoids the need for every user to have direct access to the CI/CD server and unifies the build and test environments across all machines.

Jenkins provides a very easy-to-use plugin and detailed documentation, see Using Docker with Pipeline.

ECLAIR, the toolchain and other dependencies should be installed during the pipeline or directly in the Docker image, see Running ECLAIR in Docker Containers.

Integrating ECLAIR with Services for Software Development and CI

This section is for anyone who uses an Internet hosting service for software development and continous integration like GitHub, GitLab and Jenkins.

In particular, for the GitHub, GitLab and Jenkins platforms, we provide all the required files and instructions to:

  • create an automatic analysis that runs at every push on a specific branch;

  • create an automatic analysis that runs at every push on the source branch of a pull-request (not applicable for Jenkins);

  • create a manual analysis that generates several artifacts in various formats;

  • collect and show the analysis results on an informative page provided by a customizable web server handled by eclair_report. The web server also allows the navigation of the analysis results and provides counts of both fixed and new reports compared to the previous analysis;

  • publish comments on the pull-request and commit threads with useful information about the analysis (not applicable for Jenkins);

  • provide detailed logging about the analysis.

Please note that pull-request is a GitHub-specific term, the equivalent concept in GitLab is merge-request. In the context of this section, we will generally use the first term.

Please note that runner is a GitHub and GitLab-specific term, the equivalent concept in Jenkins is agent. In the context of this section, we will generally use the first term.

We assume the reader is familiar with git and the CI/CD system provided by the chosen service.

Generally, every service with CI/CD possibilities has some concept of user-defined tasks that usually can be defined by means of a special platform-dependent syntax and triggered by a wide range of events on the underlying repository or on the platform itself. An example of the first one could be a push or a commit, for the second one a pull request or a click on a specific button.

As each service has its own name for these tasks (e.g. action in GitHub, pipeline in GitLab and Jenkins), for simplicity, we will use the term action.

Demo projects showing all the integration possibilities can be found in:

Note

For Jenkins an ad-hoc plugin is also provided (see Integrating ECLAIR with Jenkins). The plugin is a very powerful and ready-made solution and we definitely suggest using it to quickly integrate ECLAIR in your pipelines. The plugin can efficiently handle projects with a limited number of reports in the order of tens of thousands.

The current general solution is more flexible (it can be fully customized) and scalable (it can be used with very large projects), it provides a common platform for all CI/CD services.

Carefully choose whether to use the plugin or the current solution according your requirements and needs, in case of doubt, contact the ECLAIR support.

The two solutions cannot be used together.

Configuration of the integration

Configuring the provided integration depends on many aspects:

  • the specific CI/CD service in use;

  • the setup of the machines involved in the infrastructure;

  • eventual Dockerization of the CI/CD components;

  • other security/safety considerations.

For these reasons, providing a trivial step-by-step guide is not possible, but the following list can be considered as an overview of the operations required. Any operation will be fully explained in a dedicated section (that may be further expanded to discriminate the specific CI/CD service in use).

Setup of the CI/CD infrastructures:

for this first step, we assume that the CI/CD service has already been configured and the projects for which the ECLAIR tasks should be integrated are already configured and ready to use. Here is a quick overview of the components of the infrastructure:

  • the CI/CD server: this is the physical machine where the CI/CD service is running. It can be a self-hosted machine or not depending on the service and the customer’s needs;

  • the runner: this is the environment where the CI/CD tasks run. It could be a physical machine or a virtual environment (such as a Docker container). This machine requires a licensed installation of ECLAIR. See Installation of the Runner for further details;

  • the ext server: this is the machine where the artifacts are stored and from which the analysis results are provided. Since the feature of exposing the analysis results on a web interface is part of eclair_report, this machine requires a licensed installation of ECLAIR. By renouncing any remote navigation of the results, this component can be avoided. See The ext Web Server for further details.

Note that these components do not need to be on different machines and use of a common machine may lessen the required number of license keys.

Creation of the artifacts directory:

the artifacts directory is the location in the ext server where the artifacts of a specific project are stored. For each project, an artifacts directory (its name must end with .ecdf) must be created and the variable artifactsDir in the action.settings file should be amended with the correct path (see Action Settings).

Creation of the wtoken:

in the artifacts directory of any project a special wtoken file should be created. This file will be used to authenticate the operations in the directory. See Authentication to the ext server of the POST requests.

Upload the passphrase used to generate the wtoken:

create a masked variable (be sure that it is visible to the target project) named WTOKEN containing the passphrase used to generate the wtoken file. See Authentication to the ext server of the POST requests.

Creation of the impersonation/API token:

this operation is only required in GitLab and Jenkins if the creation of summary messages in the pipeline pages is enabled. In order to communicate with the GitLab/Jenkins API, the integration requires impersonating a platform user. We suggest creating an ad-hoc account with enough privileges on the target project and calling it, for example, ECLAIR. See Impersonation Token, API Token.

Enable Safe HTML formatter:

this operation is only required in Jenkins and if the creation of summary messages in the pipeline pages is enabled. The integration produces these reports in HTML format, this means that the Jenkins descriptions should be interpreted as HTML. See OWASP Markup Formatter.

Upload the impersonation token:

this operation is only required in GitLab. Once the impersonation token has been created, provide it to the integration. See Impersonation Token.

Start the ext server:

before running the actions, the ext server should be configured and started. See Starting the ext server.

Prepare the analysis scripts

prepare the scripts to run the analysis and to produce the desired artifacts. The following sections assume that an analyze.sh script that performs such operations is present in the repository. The script should ideally take an argument ANALYSIS_KIND to discriminate between the artifacts being produced, see Action push and Action pull_request.

Configure the actions:

copy and adapt the files for your platform in the repository to create the analysis actions. All the platform-independent operations required by the actions have been encapsulated in scripts documented in Action Scripts. The operation required to create the actions are platform-dependent, see the section dedicated to your platform: Creation of GitLab Pipelines, Creation of GitHub actions or Creation of Jenkins Pipelines.

Installation of the Runner

A runner is an application that runs the job contained in the actions that come from the CI/CD system.

Generally, a runner can be run:

  • on hosted virtual environments provided by the platform.

  • on self-hosted environments.

Since ECLAIR requires a license key to work, the choice between these two options is particularly delicate and depends on the type of license the user has. We suggest, whenever possible, using the second option and installing Sentinel and the license keys on the same machine where the jobs are executed.

The first option requires particular attention to the procedures to link the license key to the virtual environment.

For both options, the runner must satisfy the following requirements:

  • the software required to build the project is installed;

  • ECLAIR is installed;

  • a license key for ECLAIR is somehow available.

The installation is platform-dependent so, for this reason, follow the steps reported in the section dedicated to your platform:

Running Actions Within a Docker Container

Running actions within a Docker container is the best option as these platforms are generally intended for collaborative projects that may involve people from multiple companies. In such complex working contexts, where people from other businesses have access to the code (e.g., write permission on the repository) and are able to create actions and run code on your server, protecting the action is definitely recommended.

Leaving aside malicious intentions, non-expert users could crash the server making it unavailable for the next actions or, in the worse case, unintentionally modify configurations making the server unusable and requiring manual work by the system administrators.

In the particular context of ECLAIR, a very crucial point is how to provide the license. Several options are possible, see Running ECLAIR in Docker Containers.

Since running actions within a Docker container is platform-dependent, follow the steps reported in the section dedicated to your platform:

The ext Web Server

Internet versioning services like GitHub and GitLab provide limited capabilities in terms of representing the analysis results and it is definitely recommended that eclair_report is used for this.

Jenkins, instead, has a wide range of plugins and addons for this task. We provide an ad-hoc plugin for this purpose (see Integrating ECLAIR with Jenkins).

The ECLAIR plugin for Jenkins is definitely a very powerful and self-contained solution for integrating ECLAIR, but, due to intrinsic limitations of the platform, it cannot handle projects with hundreds of thousands of reports. For this reason, we suggest using the plugin only if the project contains a limited number of reports (in the order of tens of thousands).

The tool eclair_report can be used to handle a web server able to provide the analysis results and all the required summary information. Where the ext server is installed is up to the user, provided the machine is licensed for ECLAIR and exposed to the runners.

The interactions between the actions and the ext server are the following:

  • each database generated by an action is sent to the web server with other information about the action itself by means of a dedicated POST request.

  • the POST request is handled by the server. From the database, differential statistics such as the numbers of new/fixed/unfixed reports are extracted and static HTML pages with the information are generated. The ext server also links the previous and next action pages. The reports in the databases are also tagged with the information (see -diff_full_txt).

  • HTML pages and artifacts are stored. They can then be made available to any authorized CI/CD user. It is recommended links to these resources are placed in appropriate locations in the platform like commit and pull-request threads and README files.

A reference implementation of a node server with such capabilities can be found in:

PREFIX/eclair-VERSION/share/ci/ext

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation).

The server is written in TypeScript, but any language can be used. Correctly handling the requests defined in The ext Web Server APIs is the only requirement to be satisfied by any alternative implementation.

Note that the TypeScript files cannot be interpreted directly and must be converted to JavaScript. An already converted file is also provided. Since the server has been designed to be easily adapted to the customer’s needs, the rest of this section explains how the delivered JavaScript file was obtained.

The procedure requires Node.js to be installed; it can be downloaded from the Node.js website. Let SCRIPT_PATH be the directory path of the reference ext server mentioned above. The steps for the conversion are the following:

cd ${SCRIPT_PATH}
npm install
npm run build

Note

The ability to provide ECLAIR databases and files under directories ending with .ecdf is not related to the ext server, but it is always present in any eclair_report server.

Authentication to the ext server of the POST requests

Each POST request sent by an action needs to be authenticated by means of a special token. The token must be created with -htpasswd and then placed in the artifacts directory (.ecdf directory). The ext server will look for a file .wtokens in the artifacts directory and if the token matches the request will be authenticated.

Example:

# Ext server
cd /project_artifacts/PROJECT.ecdf
eclair_report -htpasswd=.wtokens,all,passphrase

Warning

Store the passphrase used to generate the token in an action variable named WTOKEN. The value of this variable should not appear in plain text inside logs; how to accomplish this depends on the CI/CD service in use. These are the recommended methods for GitLab, GitHub and Jenkins:

Authentication to the ext of CI/CD users to obtain resources

Each resource request (HTML pages, analysis results, etc …) from a CI/CD user to the ext server should be authenticated before being dispatched. eclair_report provides several mechanisms, see -auth.

Warning

If the eclair_report server is externally exposed, providing a strong authentication policy is recommended.

To discover the most appropriate authentication method to use with your CI/CD service, see the section dedicated to your platform:

Starting the ext server

After node has been installed and the server file has been prepared, run the eclair_report server with the -server_ext and the most appropriate authentication method, see Authentication to the ext of CI/CD users to obtain resources:

eclair_report  -auth=... -server_ext={EXT_SOCKET},node,{SCRIPT_PATH}/ext.js,{EXT_SOCKET}

Note

By default, the extension server will use /opt/bugseng/eclair/bin/eclair_report to perform operations on the incoming data. If you want to specify a different binary to be used, set and export the variable ECLAIR_PATH to the appropriate ECLAIR installation directory when launching the report server as shown above. It is strongly advised to use the same binary that is used to run the report server.

The first argument EXT_SOCKET is the pathname of the socket/named pipe file used by the ext server to communicate with eclair_report, then follows the command and the arguments to launch the server node SCRIPT_PATH/ext.js EXT_SOCKET. The socket/named pipe file should not be created manually, it will be generated by the ext server when required.

The ext Web Server APIs

The server APIs consist of two methods:

  • POST:/ext/update_push;

  • POST:/ext/update_pull_request.

The following arguments are common to both methods:

artifactsDir

is the directory in the ext server where the artifacts of the repository are to be stored. It must end with .ecdf otherwise the web server cannot provide the files, see -auth;

wtoken

is the authentication token. This token will be used to authenticate the user sending the request. The server will search for it in the .wtoken file in the artifactsDir. See Authentication to the ext server of the POST requests

subDir

is the subdirectory inside the artifactsDir where to store the files. It could be the branch name, some characteristic of the build or of the analysis (e.g. main_Debug, main_Release, develop_MC3, …).

jobId

is the identifier of the action job;

jobHeadline

is the headline used for the jobId/index.html page;

badgeLabel

is the badge label used for the jobId/badge.svg badge.

keepOldAnalyses

is the number of analyses stored by the ext server. Older analyses will be deleted. If set to 0 all analyses will be kept.;

autoPRRepository

is the target repository of the auto PR pull request. If autoPRBranch is defined, all commits from other branches or repositories will be considered pull-requests to autoPRBranch of autoPRRepository.

autoPRBranch

is the target branch of the auto PR pull request. If autoPRBranch is defined, all commits from other branches or repositories will be considered pull-requests to autoPRBranch of autoPRRepository.

db

is the ECLAIR database file.

POST:/ext/update_push has the following specific argument:

commitId

is the identifier of the base branch’s last commit;

POST:/ext/update_pull_request has the following specific argument:

baseCommitId

is the identifier of the most recent merge point in the source branch without conflicts;

After handling the requests, the artifacts directory will contain:

  • a commits directory containing symbolic links for each commit job directory;

  • a directory for each subDir, containing a directory for each job;

  • symbolic link to the last job.

Each job directory includes:

  • the provided database with the POST request;

  • a badge badge.svg with the analysis results;

  • a file fixedReports.txt containing the number of fixed reports;

  • a file index.html containing useful information about the job and the analysis. It includes also links to the previous and next job.

  • a file newReports.txt containing the number of new reports;

  • a file unfixedReprts.txt containing the number of fixed reports;

  • symbolic links for the next and previous job directories.

Since both methods perform write operations on the server, it is fundamental to authenticate the user sending the request. Our implementation uses an authentication token (typically all platforms have a concept of masked variables or secrets where these tokens can be stored), see Authentication to the ext server of the POST requests.

Action Scripts

Many operations can easily be generalized for all the platforms, for that reason we gathered them in a series of scripts:

  • PREFIX/eclair-VERSION/share/ci/action_log.sh, for more information, see Action Logging;

  • PREFIX/eclair-VERSION/share/ci/action_pull_request.sh, for more information, see Action pull_request;

  • PREFIX/eclair-VERSION/share/ci/action_push.sh, for more information, see Action push;

  • PREFIX/eclair-VERSION/share/ci/action.helpers, for more information, see Action Helpers;

  • PREFIX/eclair-VERSION/share/ci/action.settings, for more information, see Action Settings.

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation).

Action Settings

The script action.settings defines all the variables required by the other action scripts: some of them are information extracted by the runner environment, the others are user settings to configure the actions. The script is included by the other action scripts and hence executed at each action.

Here the main work in terms of generalization has already been done. In fact, many configurations depend on the variable ci that is assumed to be assigned with the platform name by action.helpers. Currently only the GitHub, GitLab and Jenkins are natively supported, but the script can be easily extended to support any CI/CD service.

Changes to the platform-dependent sections should not be required unless the intention is to extend it to new platforms.

The variables include repository information, platform information, and ext server information.

Now a detailed description of these settings follows:

repository

is the repository name; All platforms provide an environment variable containing this information;

event

is a string denoting the event being handled. It could be push or pull_request. All platforms provide an environment variable containing this information;

variantSubDir

is the name of the variant subdirectory. It takes its value from the environment variable VARIANT. It could be the repository name, some characteristic of the build or the analysis (e.g. main_Debug, main_Release, develop_MC3, …);

variantHeadLine

is a string that will be appended to the action headline;

jobDir

is the directory where the generated artifacts related to a specific job are stored. We suggest using the default value;

jobId

is the identifier of the running job. All platforms provide an environment variable containing this information;

jobHeadLine

is the string that will be used as the headline for the analysis page, its value will vary, depending on the action information. We suggest using the predefined values;

subDir

is the name of the directory where the artifacts are stored, its value will depend on event and variantSubDir. We suggest using the predefined values;

badgeLabel

is the label of the analysis badge. We suggest using the default value;

keepOldAnalyses

is the number of analyses stored by the ext server. Older analyses will be deleted. If set to 0 all analyses will be kept.;

artifactsRoot

is the root directory where the artifactsDir in the ext server is created. This variable should be adapted according to the infrastructure setup, see Configuration of the integration;

artifactsDir

is the directory where the generated artifacts related to the project are stored; it must end with .ecdf. We suggest using the default value;

eclairReportUrlPrefix

is the URL of the machine running the ext server. It must include the port. This variable should be adapted according to the infrastructure setup, see Configuration of the integration;

updateLog

is the file where the logs of the POST requests to the ext server are stored. We suggest using the default value;

commentLog

is the file where the logs of the POST requests to platform APIs for the creation of the comments are stored. We suggest using the default value;

indexHtmlUrl

is the file where the HTML page showing the job results is stored. We suggest using the default value;

summaryTxt

is the file where the job results are stored. We suggest using the default value;

Variables that must be defined only if event is pull_request:

pullRequestId

is the identifier of the pull-request. All platforms provide an environment variable containing this information;

pullRequestHeadRef

is the name of the source branch of the pull-request. All platforms provide an environment variable containing this information;

pullRequestHeadRepo

is the name of the source repository of the pull-request. All platforms provide an environment variable containing this information;

pullRequestBaseRef

is the name of the target branch of the pull-request. All platforms provide an environment variable containing this information;

pullRequestUser

is the user that requested the pull-request. All platforms provide an environment variable containing this information.

headCommitId

is the merge point in the source branch of the pull-request. Not all platforms provide an environment variable containing this information. In such cases, the same technique used for GitHub can be used.

baseCommitId

is the merge point in the target branch of the pull-request. Not all platforms provide an environment variable containing this information. In such cases, the same technique used for GitHub can be used.

Variables that must be defined only if event is push:

branch

is the name of the branch. All platforms provide an environment variable containing this information.

GitLab-specific settings:

gitlabApiUrl

is the URL where to send the GitLab API requests for adding comments in the commit and pull-request threads with the analysis results. The value is generated starting from GitLab variables, only the version should be amended (the default is v4).

gitlabBotToken

is the GitLab impersonation token used to authenticate the API requests when the CI_JOB_TOKEN cannot be used. This variable should be adapted according to the infrastructure setup, see Impersonation Token.

Action Helpers

The action.helpers file contains a series of helpers used by the other scripts, many of them are platform-specific.

This file does not require adaptations unless the intention is to extend the existing helpers to new platforms.

Action Logging

Both the push and the pull-request actions log the output of the analysis and report phases into the CI/CD console.

To generalize this task we have prepared the action_log.sh script which is intended to be executed directly from the actions.

Its behavior has been adapted to the specific platform used to ensure the maximum level of integration.

action_log.sh takes four arguments:

SECTION_ID

is an arbitrary identifier for the section

SECTION_NAME

is the name of the section that will be displayed in the console

FILE

is the log file that will be displayed in the console

EXIT_CODE

is an integer number that represents the exit code of the action we are logging. If the provided number is 0, the section will be pre-collapsed (the platform must support that feature)

Action push

This action is intended to perform all the operations needed to analyze the project after a specific push on the repository. The integration implements two different kinds of analysis: one that is automatically triggered at each commit called ECLAIR_normal, one that should be manually triggered called ECLAIR_final. Both the analysis kinds are intended to analyze the project, but ECLAIR_final is intended to generate a wide range of artifacts that may be unwanted for each analysis.

The action is intended to perform the following steps:

  1. set up the environment to build the project;

  2. build and analyze the project;

  3. log the eclair_env diagnostics on the CI/CD console;

  4. log the eclair_report diagnostics on the CI/CD console;

  5. send to the ext server the analysis artifacts and other useful information about the push, see The ext Web Server;

  6. log summary information about the analysis on the CI/CD console;

  7. add a comment with the same summary information on the commit thread in Github and Gitlab and in the pipeline page in Jenkins; This function can be disabled by setting an environment variable called ENABLE_ECLAIR_BOT to no, false, n, 0 or f. If the variable is not defined or defined otherwise, the feature is enabled.

  8. upload the artifacts on the platform.

While these steps except for the last one are platform-independent, the operations required to set up the action are not, please see the relevant section:

Steps 1 and 2 are project-specific; we assume that the user has already prepared specific scripts that take the ANALYSIS_KIND (in our example ECLAIR_final or ECLAIR_normal) variable and completed these tasks. Remember that the runner environment must be prepared with all required softwares, like ECLAIR, the toolchain and other dependencies. It also should be able to retrieve a license for ECLAIR, see Installation of the Runner and Running Actions Within a Docker Container. Under the aforementioned assumptions, the first two steps should look like:

set -eu

# Export the following variable to disable the summary messages
# from the ECLAIR bot.
# export ENABLE_ECLAIR_BOT=n

# Prepare the environment
${SCRIPT_DIR}/prepare.sh "${ANALYSIS_KIND}" ARGS
# Analyze the project
ex=0
${SCRIPT_DIR}/analyze.sh ARGS || ex=$?

The use of the ex variable is required since we are assuming that in the rest of the procedure, other steps are performed independently from its success (set -e interrupts the script at the first error).

Steps 3 and 4 are very similar, we have prepared a script action_log.sh that performs the required logging, see Action Logging.

We assume that analyze.sh redirects in two separate files the logs of the analysis and report phases.

"${SCRIPT_DIR}/action_log.sh" ANALYSIS_LOG \
                            "ECLAIR analysis log" \
                            "${OUTPUT_DIR}/ANALYSIS.log" \
                            "${ex}"
"${SCRIPT_DIR}/action_log.sh" REPORT_LOG \
                        "ECLAIR report log" \
                        "${OUTPUT_DIR}/REPORT.log" \
                        "${ex}"

Now it should be clearer why we have masked the exit code of analyze.sh with the ex variable: we want to log these two files also in case of failure.

Consider now steps 5, 6 and 7 that should not be executed if the analysis fails. We have prepared a script action_push.sh that performs the required actions. Its behavior depends on the settings in action.settings, so make sure it is properly configured. See Action Scripts for general information about this set of scripts.

[ "${ex}" = 0 ] || exit "${ex}"
"${SCRIPT_DIR}/action_push.sh" "${WTOKEN}" "${OUTPUT_DIR}"

action_push.sh takes two arguments:

WTOKEN is the token used to authenticate the POST requests to the ext web server. See The ext Web Server.

OUTPUT_DIR is the directory where the analysis artifacts are located.

Step 8 is obviously platform-specific, see the dedicated section.

Action pull_request

This action is intended to perform all the operations required to analyze the project after a specific pull-request or change in the source branch of an existing one on the repository. The integration implements two different kinds of analysis: one, called ECLAIR_normal, that is automatically triggered and one, called ECLAIR_final, that should be manually triggered. Both the analyses are intended to analyze the project, but ECLAIR_final will also generate a wide range of artifacts that may not always be wanted.

Note

This action is not available in Jenkins.

The action is intended to perform the following steps:

  1. set up the environment to build the project;

  2. build and analyze the project using the branch obtaining merging the source with the target. Please note that in case of conflicts this is not possible;

  3. log the eclair_env diagnostics on the CI/CD console;

  4. log the eclair_report diagnostics on the CI/CD console;

  5. send to the ext server the analysis artifacts and other useful information about the pull-request, see The ext Web Server;

  6. log summary information about the analysis on the CI/CD console;

  7. add a comment with the same summary information on the pull-request thread; This function can be disabled by setting an environment variable called ENABLE_ECLAIR_BOT to no, false, n, 0 or f. If the variable is not defined or defined otherwise, the feature is enabled.

  8. upload the artifacts on the platform.

While these steps except for the last one are platform-independent, how to set up the action is not, please see the dedicated section:

Steps 1 and 2 are project-specific; we assume that the user has already prepared scripts that take at least the ANALYSIS_KIND variable (in our example ECLAIR_final or ECLAIR_normal) and completed these tasks. Remember that the runner environment must be prepared with all required software like ECLAIR, the toolchain and other dependencies. It also should be able to retrieve a license for ECLAIR, see Installation of the Runner and Running Actions Within a Docker Container.

The code to be analyzed should be the code resulting from the merge between the source and the target branches. Usually, all platforms instantiate the job on this temporary branch, please ensure this holds (GitLab does provide merged results pipelines only with the Premium and Ultimate tiers ).

Under the aforementioned assumptions, the first two steps should look like:

set -eu

# Export the following variable to disable the summary messages
# from the ECLAIR bot.
# export ENABLE_ECLAIR_BOT=n

# Prepare the environment
${SCRIPT_DIR}/prepare.sh "${ANALYSIS_KIND}" ARGS
# Analyze the project
ex=0
${SCRIPT_DIR}/analyze.sh ARGS || ex=$?

The use of the ex variable is required since this is assumed by the rest of the procedure; later steps are performed independently of the success of this step (set -e interrupts the script at the first error).

Steps 3 and 4 are very similar, we have prepared a script action_log.sh that performs the required logging, see Action Logging.

We assume that analyze.sh redirects in two separate files the logs of the analysis and report phases.

"${SCRIPT_DIR}/action_log.sh" ANALYSIS_LOG \
                            "ECLAIR analysis log" \
                            "${OUTPUT_DIR}/ANALYSIS.log" \
                            "${ex}"
"${SCRIPT_DIR}/action_log.sh" REPORT_LOG \
                        "ECLAIR report log" \
                        "${OUTPUT_DIR}/REPORT.log" \
                        "${ex}"

Now it should be clearer because we have masked the exit code of analyze.sh with the ex variable: we want to log these two files also in case of failure.

Now we have steps 5, 6 and 7, but this time we do not want to execute them if the analysis fails. We have prepared a script action_pull_request.sh that performs the required actions. Its behavior depends on the settings in action.settings, make sure to configure it properly. See Action Scripts for general information about this set of scripts.

[ "${ex}" = 0 ] || exit "${ex}"
"${SCRIPT_DIR}/action_pull_request.sh" "${WTOKEN}" "${OUTPUT_DIR}"

action_pull_request.sh takes two arguments:

WTOKEN

is the token used to authenticate the POST requests to the ext web server. See The ext Web Server.

OUTPUT_DIR

is the directory where the analysis artifacts are located.

Step 8 is obviously platform-specific, see the dedicated section.

Integrating ECLAIR with GitHub

This section is for anyone who uses GitHub and now needs to know how to integrate ECLAIR with it.

The section assumes that all the platform-independent sections of Integrating ECLAIR with Services for Software Development and CI have been already read, as this section represents an instantiation of them for GitHub.

A demo project showing all the integration possibilities can be found in BUGSENG/eclair_demo.

Installation of the GitHub Runner

For the instruction on how to install a runner in a self-hosted machine see Using self-hosted runners in a workflow.

Using Docker Containers in GitHub

GitHub offers hosted virtual machines to run workflows either directly on virtual machines or in Docker containers, see About GitHub-hosted runners. The installations of ECLAIR, the toolchain and other dependencies become part of the workflow.

If you prefer to run workflows in a self-hosted machine, see About self-hosted runners.

In this case, ECLAIR, the toolchain and other dependencies can be installed during the pipeline or directly in the Docker image. The skeleton provided in Running ECLAIR in Docker Containers can be used with a minimal change: use the myoung34/github-runner Docker image as parent image for your Dockerfile. See Docker Github Actions Runner for further information.

Creation of GitHub actions

In GitHub, the actions are defined through special YAML files.

We have prepared three actions, respectively for the manual, the push and the pull-request events:

PREFIX/eclair-VERSION/share/ci/github/ECLAIR_final.yml

PREFIX/eclair-VERSION/share/ci/github/ECLAIR_normal.yml

PREFIX/eclair-VERSION/share/ci/github/ECLAIR_pull_request.yml

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation).

The above actions create a very deep interaction between GitHub and ECLAIR and do not simply perform an analysis every time they are triggered. The contents of the provided files will be discussed later.

Please remember that they are just examples, or if you prefer, skeletons for your custom actions to be adapted to match your needs.

The files should be placed in

.github/workflows

if the directory does not exist create it.

Now, the actions are ready and at every manual, push and pull_request event, they will be executed.

See GitHub actions documentation for more details.

Actions ECLAIR_final and ECLAIR_normal in GitHub

This section is an instantiation of Action push to GitHub.

ECLAIR_final and ECLAIR_normal are essentially the same action, they differ only in some settings. For this reason, they will be discussed together.

The actions are defined in the following file:

PREFIX/eclair-VERSION/share/ci/github/ECLAIR_final.yml

PREFIX/eclair-VERSION/share/ci/github/ECLAIR_normal.yml

The first lines of both files define an arbitrary name for the action and a list of events that trigger it. We used workflow_dispatch and push: the first one is required to trigger the action from other workflows, the second one triggers the action at every push on the repository.

See Available events for an exhaustive list of them.

See push for an exhaustive description of the push event.

See workflow_dispatch for an exhaustive description of the workflow_dispatch event.

Then, there is the env section. This section is instead used to define environment variables required by the next steps. In our case, we need:

GITHUB_TOKEN contains a secret token to authenticate the requests to the GitHub API required by the integration. The value of the token can be retrieved using the internal variables ${ secrets.GITHUB_TOKEN }

ANALYSIS_KIND contains the kind of analysis. This variable is used to discriminate the operations to perform by analyze.sh for ECLAIR_final and ECLAIR_normal

ENABLE_ECLAIR_BOT enables or disables the ECLAIR messages with summary information on the pipeline page. This feature can be disabled by setting the variable to no, false, n, 0 or f. If the variable is not defined or defined otherwise, the feature is enabled.

See Environment variables for more details.

Now we have reached the most interesting part, where the job is defined. The job name is Analyze, it should run on a specific runner called eclairit (how to set up a runner is described in Installation of the GitHub Runner) and it is composed of seven separate sub-actions:

  • Checkout repository;

  • Build and analyze with ECLAIR;

  • ECLAIR analysis log;

  • ECLAIR report log;

  • Upload ECLAIR artifacts;

  • Upload ECLAIR SARIF;

  • Upload ECLAIR results.

See Using jobs in a workflow for more details.

The first action Checkout repository simply checkout the repository, so the workflow can access it.

It is a standard action defined in the following repository actions/checkout, for our basic usage, we only provide submodules: 'true' in order to checkout also eventual submodules.

Build and analyze with ECLAIR is the most important step where the analysis is actually made.

Assuming analyze.sh takes the ANALYSIS_KIND and creates two log files for the analysis and the report phases, we use two simple cat instructions to log them to the GitHub console. We decided to do that using two sub-actions in order to have two separate collapsable sections in the console.

if: always() is used to ensure that the logging actions will be executed indefinitely from failures during the analysis. For this reason, masking the possible error of analyze.sh as shown in Action push is unnecessary.

The next step is Upload ECLAIR Artifact that simply uploads the produced artifacts so that they will be available from the action page in GitHub under section Artifacts.

It is a standard action defined in the following repository actions/upload-artifact, for our basic usage we only provide name and path that are respectively the name and the path of the artifacts to upload. All the artifacts are created and stored in ECLAIR_out by analyze.sh. Since for debugging reasons is useful having the artifacts also in case of failure, we use if: always().

The next action is Upload ECLAIR SARIF which uploads the SARIF output, that we assume is generated by eclair_report in analyze.sh using -reports_sarif.

The upload is performed by a re-usable workflow defined in BUGSENG/codeql-action, which is a modified version of the standard action github/codeql-action. For our basic usage we only provide sarif_file which is the the path of the SARIF file to upload.

The final step is Publish ECLAIR results, which is performed by action_push.sh, see Action push. This step requires to define the following variable in the enviroment:

WTOKEN is the authentication token. It must be an Encrypted secret. This token will be used to authenticate the user sending the request. The server will search it in the .wtoken file that must be present in the artifactsDir. Create and manipulate the file with -htpasswd

The script is provided with the variables WTOKEN and the directory containing the ECLAIR artifacts.

Action ECLAIR_pull_request in GitHub

This section is an instantiation of Action pull_request to GitHub.

The action is defined in the following file:

PREFIX/eclair-VERSION/share/ci/github/ECLAIR_pull_request.yml

The first lines define an arbitrary name for the action and the events that trigger it. In this case, we set only the pull_request event that has different types, we are interested in opened and synchronize. The first is emitted when a pull-request is opened, the second when a pull request’s head branch is updated. See Available events for an exhaustive list of the events. See pull_request for a detailed description of the pull_request event.

The env section requires the same variable needed in the push action, see Actions ECLAIR_final and ECLAIR_normal in GitHub for a detailed description.

Now we have reached the most interesting part, where the job is defined. The job is defined similarly to the one in the push action, the only difference is in the Publish ECLAIR results action that is specific to the event. We proceed to describe only this different part, for the remaining see Actions ECLAIR_final and ECLAIR_normal in GitHub.

Unlike the other action we have seen, this requires some variables to collect information about the pull-request. These are:

PR_HEAD_REF contains the target branch of the pull-request. The value of the token can be retrieved using the internal variables ${ github.event.pull_request.head.ref }

PR_HEAD_REPO contains the target repository name of the pull-request. The value of the token can be retrieved using the internal variables ${ github.event.pull_request.head.ref }

PR_BASE_REF contains the source branch of the pull-request. The value of the token can be retrieved using the internal variables ${github.event.pull_request.head.repo.full_name}

PR_USER the GitHub user who created the pull-request. The value of the token can be retrieved using the internal variables ${ github.event.pull_request.user.login }

WTOKEN is the authentication token. This token will be used to authenticate the user sending the request. The server will search it in the .wtoken file that must be present in the artifactsDir. Create and manipulate the file with -htpasswd

The run is basically an invocation of action_pull_request.sh which performs the required operations, see Action pull_request.

Authentication in GitHub

GitHub does not save any cookies that can be used to authenticate the file requests, for that reason, one of the general methods in -auth should be used.

Integrating ECLAIR with GitLab

This section is for anyone who uses GitLab and now needs to know how to integrate ECLAIR with it.

The section assumes that all the platform-independent sections of Integrating ECLAIR with Services for Software Development and CI have been already read, as this section represents an instantiation of them for GitLab.

To avoid confusion in this section we will use the specific GitLab terms.

A demo project showing all the integration possibilities can be found in swquality/eclair_demo.

Installation of the GitLab Runner

For the instruction on how to install a runner in a self-hosted machine see Install GitLab Runner.

Using Docker Containers in GitLab

GitLab provides a very easy and convenient approach to dockerization. It is all handled by the runner. The user only needs to register and set it to use Docker executors through a TOML file, see Run your CI/CD jobs in Docker containers.

Please, pay attention that GitLab allows specifying the dockerization through the .gitlab-ci.yml file: avoid relying only on this option as if a user does specify nothing will have access to the CI/CD server.

ECLAIR, the toolchain and other dependencies should be installed during the pipeline or directly in the Docker image, see Running ECLAIR in Docker Containers.

Impersonation Token

In order to add summary messages with the analysis results in the commit and pull-request threads, the integration requires impersonating a platform user by means of a personal access token.

The impersonated user must be authorized to write comments in all threads related to analyzed commits and pull-requests. We suggest creating an ad-hoc account with enough privileges on the target project and calling it ECLAIR.

Create a personal access token for the user by following the instructions in Create a personal access token.

Create a masked variable (see Mask a CI/CD variable), then use it to set gitlabBotToken in action.settings (see Action Settings).

The default name is ECLAIR_BOT_TOKEN, if you use this name you do not need to amend the file.

Creation of GitLab Pipelines

In GitLab, the actions are defined through special YAML files.

We have prepared three pipelines, respectively for the manual, the push and the merge-request events. You can find the file that defines them in:

PREFIX/eclair-VERSION/share/ci/gitlab/.gitlab-ci.yml

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation).

The above actions create a very deep interaction between GitLab and ECLAIR and do not simply perform an analysis every time they are triggered. The contents of the provided file will be discussed later.

Please remember that it is just an example, or if you prefer, a skeleton for your custom actions, adapt it to perfectly match your needs.

The files should be placed in the repository root directory.

Now, the actions are ready and at every manual, push and pull-request, the respective pipelines will be executed.

See CI/CD pipelines for more details.

Defining the pipeline in a separate repository

It is also possible to define the pipelines in a separate repository. This option is very convenient in case we do want to keep the ECLAIR configuration files and script separated from the project itself.

Let’s assume to have two repositories called MY_PROJECT and MY_PROJECT_ECLAIR that are in the same group my_group. MY_PROJECT contains the project to analyze; MY_PROJECT_ECLAIR contains the required scripts and ECL files for the analysis.

Now, the first step is to connect the two GitLab repositories, to do that we need to create a .gitlab-ci.yml file in MY_PROJECT_ECLAIR with the following content:

analyze:
  trigger: my_group/MY_PROJECT

Instead, the old .gitlab-ci.yml contained the pipelines definition should be renamed in gitlab-ci.yml and placed in the root directory.

See trigger for more details.

Actions ECLAIR_final and ECLAIR_normal in GitLab

This section is an instantiation of Action push to GitLab.

ECLAIR_final and ECLAIR_normal are essentially the same pipelines, they differ only in some settings. For this reason, they will be discussed together.

The pipelines are defined in the following file:

PREFIX/eclair-VERSION/share/ci/gitlab/.gitlab-ci.yml

The YAML file contains all the pipelines, please focus your attention to ECLAIR_final and ECLAIR_normal.

The first lines of both pipelines define an arbitrary name and set interruptible: true to allow GitLab to cancel the job when made redundant by a newer run.

See interruptible for an exhaustive description of the interruptible.

ECLAIR_final sets when: manual and allow_failure: false respectively to allow the start of the pipeline only after a manual trigger and to make fail the pipeline in case of failure of the job.

See Create a job that must be run manually for further details.

ECLAIR_normal sets only: -push to automatically run the pipeline at each push on the branch.

Then, there is the variables section. This section is instead used to define environment variables required by the next steps. In our case, we need three variables:

SCRIPT_DIR contains the path where the analysis scripts are located.

OUTPUT_DIR contains the path where the analysis artifacts are created.

ANALYSIS_KIND contains the kind of analysis. This variable is used to discriminate the operation to perform by analyze.sh for ECLAIR_final and ECLAIR_normal

ENABLE_ECLAIR_BOT enables or disables the ECLAIR messages with summary information on the pipeline page. This feature can be disabled by setting the variable to no, false, n, 0 or f. If the variable is not defined or defined otherwise, the feature is enabled.

See GitLab CI/CD variables for more details.

Now we have reached the most interesting part, where the job script is defined.

The job script performs all the required operations already described in Action push, see that section for an in-depth description.

If you want to separate your project from the analysis scripts as explained in Defining the pipeline in a separate repository, just remember to clone the other repository into the current one, a similar script should look like:

variables:
  ECLAIR_REPO: "my_group/${CI_PROJECT_NAME}_ECLAIR"
  ANALYSIS_BRANCH: "master"
  SCRIPT_DIR: "./.gitlab"
  OUTPUT_DIR: "./ECLAIR_out"
script: |
  set -eu
  git clone -b "${RELEASE_BRANCH}" --depth 1 https://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_HOST}:8444/${PROJECT_PATH}.git "${SCRIPT_DIR}"
  # Prepare for build
  "${SCRIPT_DIR}/prepare.sh"

See script for more details.

The next step is to upload the artifacts the so that they will be available from the job page in GitLab.

We use artifacts to upload them, see Job artifacts for more details.

For our basic usage, we only need:

when: always to keep the artifacts also in case of failure for debugging reasons;

paths: ... that is the list of paths we want to upload;

reports: is a special section that informs GitLab about special report files. In our case ECLAIR is able to produce a report in the GitLab format codeClimate, see Code Quality. We assume the file is generated by eclair_report in analyze.sh using -reports_codeclimate. We provide the file using codequality.

Action ECLAIR_pull_request in GitLab

This section is an instantiation of Action pull_request to GitLab.

The pipeline is defined in the following file:

PREFIX/eclair-VERSION/share/ci/gitlab/.gitlab-ci.yml

The YAML file contains both the merge-request and push actions, please focus your attention to analyze_merge_request.

The first lines of analyze_merge_request define an arbitrary name for the pipeline and a list of events that should trigger it. We used merge_request to trigger the action at every merge request on the repository.

See Merge request pipelines for more details.

Differently from what we said in the general section, this pipeline does not analyze the resulting merged branch, but instead the source one. GitLab offers the so-called merged results pipelines only to premium users. See Merged results pipelines.

The job is defined similarly to the one in the push pipeline, the only difference is in script that is specific for the event. We proceed to describe only this different part, for the remaining see Actions ECLAIR_final and ECLAIR_normal in GitLab.

The job script performs all the required operations already described in Action pull_request, see that section for an in-depth description.

If you want to separate your project from the analysis scripts as explained at the end of Creation of GitLab Pipelines, just remember to clone the other repository into the current one, as already explained in Action ECLAIR_pull_request in GitLab.

Authentication in GitLab

GitLab saves useful cookies that can be exploited to authenticate the file requests, for that reason we suggest using the gitlab method in -auth.

Here is an example:

eclair_report -auth={ARTIFACTS_DIR}/,gitlab,{ECLAIR_REPORT_SERVER}/ \
-server_ext=.. -server_root=/ -server

where ARTIFACTS_DIR is the directory where the analysis artifacts are stored, and ECLAIR_REPORT_SERVER is the URL (including the port) of the machine running the ext server.

Integrating ECLAIR with Jenkins

This section is for anyone who uses Jenkins and now needs to know how to integrate ECLAIR with it without using the plugin.

The section assumes that all the platform-independent sections of Integrating ECLAIR with Services for Software Development and CI have been already read, as this section represents an instantiation of them for Jenkins.

To avoid confusion in this section we will use the specific Jenkins terms.

Installation of the Jenkins Agent

For the instruction on how to install an agent see Using Jenkins agents.

API Token

In order to add summary messages with the analysis results in the pipeline threads, the integration requires impersonating a platform user by means of an API token.

The impersonated user must be authorized to write comments in all threads related to analyzed jobs. We suggest creating an ad-hoc account with enough privileges on the target project and calling it ECLAIR.

Create a API token for the user by following the instructions in Authenticating scripted clients.

Create two credentials of type secret text (see Using credentials), one called ECLAIR_BOT_USERNAME with the username of the user, the other one called ECLAIR_BOT_TOKEN with the API token. Then use these two variables to set jenkinsBotUsername and jenkinsBotToken in action.settings (see Action Settings).

Creation of Jenkins Pipelines

In Jenkins, pipelines can be defined through a step-by-step procedure from its web interface. Depending on the kind of job you want to create the procedure can be slightly different: we assume the reader is familiar with such process.

See Getting Started with Pipelines for further details.

Actions ECLAIR_final and ECLAIR_normal in Jenkins

This section is an instantiation of Action push to Jenkins.

ECLAIR_final and ECLAIR_normal are essentially the same pipelines, they differ only in some settings. For this reason, they will be discussed together.

The procedure depends on the pipeline kind desired, but many steps are the same. This section will go through the common steps related to the integration:

Build Steps

create a build step of kind Execute Shell using the reference script in:

PREFIX/eclair-VERSION/share/ci/jenkins/build_step.sh

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation).

The script defines a series of variables required for the analysis:

SCRIPT_DIR contains the path where the analysis scripts are located.

OUTPUT_DIR contains the path where the analysis artifacts are created.

ANALYSIS_KIND contains the kind of analysis. This variable is used to discriminate the operation to perform by analyze.sh for ECLAIR_final and ECLAIR_normal

ENABLE_ECLAIR_BOT enables or disables the ECLAIR messages with summary information on the pipeline page. This feature can be disabled by setting the variable to no, false, n, 0 or f. If the variable is not defined or defined otherwise, the feature is enabled.

After, the script performs all the required operations already described in Action push, see that section for an in-depth description.

Build Environment

pin the checkbox Use secret text(s) or file(s) and add the secrets required by the integration (WTOKEN, eventually ECLAIR_BOT_USERNAME and ECLAIR_BOT_TOKEN).

Post-build Actions

add an Archive the artifacts action providing the directory where the ECLAIR artifacts are stored.

If you want to separate your project from the analysis scripts as explained in Defining the pipeline in a separate repository, just remember to clone the other repository into the current one, a similar procedure should look like:

export GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no -i '${git_key}'"
[ -d ECLAIR_scripts ] || git clone ssh://git@example.com/repository ECLAIR_scripts
(cd ECLAIR_scripts; git pull --rebase)

We suggest using a secret to store the ssh key to access the repository.

Please remember that it is just an example, or if you prefer, a skeleton for your custom pipelines, adapt it to perfectly match your needs.

Authentication in Jenkins

Jenkins does not save any cookies that can be used to authenticate the file requests; for this reason one of the general methods in -auth should be used.

Warning

Do not use the jenkins authentication method, it is intended to be used with the plugin and not with this kind of integration.

Here is an example:

eclair_report -auth={ARTIFACTS_DIR}/,allow,{ECLAIR_REPORT_SERVER}/ \
-server_ext=.. -server_root=/ -server

where ARTIFACTS_DIR is the directory where the analysis artifacts are stored, and ECLAIR_REPORT_SERVER is the URL (including the port) of the machine running the ext server.

Outputs

The ECLAIR platform can generate outputs for different purposes in many different formats. In this chapter, we introduce the main output formats supported by this version of ECLAIR: Section Report Formats presents them from the end-user point of view, whereas Section Report Tools gives instructions on how to generate them.

If the output formats covered here do not match your needs, please contact BUGSENG to discuss them: due to the unique design of ECLAIR, the results of the analysis can undergo any kind of transformation in order to adapt to any environment and application.

Note

The outputs generated by ECLAIR contain protected intellectual property of BUGSENG srl. Redistribution of any part of such outputs can only happen in accordance with the License Agreement. When some form of redistribution is allowed, the licensed version only supports the generation of textual outputs. The following description of ECLAIR reporting facilities is completely general and does not necessarily reflect the functionality of the ECLAIR instance that was licensed to you.

Report Formats

In this chapter we describe the formats of reports supported by ECLAIR. An ECLAIR report provides information about a circumstance that was detected by some ECLAIR service. Reports can be of different kinds:

All the report kinds provide:

  • the name of the service that generated the report;

  • depending on the report, one or more report areas, which give localized details about the circumstance that is being reported.

A report area (also called main area) provides:

  • the locations of the source code that constitute the area;

  • a message describing the area and its relevance to the overall report;

  • optional report subareas that give additional information about the area itself.

Finally, a report subarea provides:

  • the locations of the source code that constitute the subarea;

  • a message describing the subarea.

Subareas are used to convey information about:

  • the preprocessed version of the code of the main area;

  • the macro expansion chain leading to the main area;

  • the file inclusion chain leading to the main area.

This version of ECLAIR supports two main general formats for the detailed outputs: HTML and pure text. These two formats serve very different purposes and, consequently, they are of a very different nature.

HTML outputs have been designed to be self-contained, complete accounts of all the analyses conducted by means of ECLAIR. So, depending on the analysis and reporting options, these reports may contain, besides the findings of the analysis, full information about the build process together with statistics on the various findings and full project sources both before and after preprocessing. In other words, all the information a developer or quality-assurance person needs for studying and improving the code is available by means of any web browser. HTML outputs are described in Section HTML Outputs.

Textual outputs are ordinary lines of text that can be used for visual inspection, possibly with the help of an editor or an IDE that is able to interpret the location information so as to contextually present the relevant portion(s) of source code. Textual outputs are described in Section Error Reports.

HTML Outputs

The HTML reporting facility provides advanced features for the visualization and navigation of all the information concerning an ECLAIR analysis. By means of any web browser the user has quick access to:

  • information about the build process and the ECLAIR analyses performed;

  • statistics on the various findings;

  • detailed reports about each finding;

  • optionally, full project sources, both before and after preprocessing.

All such information is suitably hyperlinked for easy access and navigation. ECLAIR HTML outputs are compatible with most popular browsers, such as Google Chrome, Mozilla Firefox, Safari, Microsoft Edge and Opera.

The Main Page

The file index.html in the output folder contains the main page of the HTML outputs bundle. At the top is the link

Overall Information

If the service B.EXPLAIN has been enabled, this links to the Configuration page, otherwise the link is void.

The rest of the page consists of three sections.

Project Info:

This section contains a table with information about the project.

Overall Counts:

This section contains four tables, with information on:

  1. the number of enabled services, divided by kind; details about such services (with links to their documentation) can be obtained by clicking on the anchor in the table caption;

  2. the number of analysis frames, divided by kind; details about such frames can be obtained by clicking on the anchor in the table caption;

  3. the number of analysis files, divided by kind; details about such files, divided by directory, can be obtained by clicking on the anchor in the table caption;

  4. the number of reports, divided by report kind; details about reports are available in the next section; clicking on the anchor in the table caption is equivalent to selecting Reports by service and first file in the Detailed Reports section.

Detailed Reports:

This section contains links to more detailed statistical summaries of the reports generated by ECLAIR using the indicated classification:

Reports by service

reports are organized by service;

Reports by first file

reports are organized by first file only;

Reports by service and first file

reports are organized by service and then by first file.

When the user clicks on a link in the left-hand column of a report summary page, the browser enters the selected reports page showing summary information for the selected reports.

Clicking on a link to a service at the left-hand side of the selected reports page, causes the browser to enter a source file page showing the code at the selected location.

We first describe key features common to all the ECLAIR HTML output pages.

Common Features
Color and Column Alignment:

The ECLAIR HTML pages present the report information using color and column alignment to help browsing and selecting the relevant information.

Colored dots, bars and/or rectangles containing the report kind are shown in columns across the relevant vertical region of the page. These columns are ordered and their boxes are colored as follows:

error, violation

red;

caution

orange;

information

yellow;

metric

green.

Navigation Arrows:

In the upper right corner of each page are two navigation arrows < and > for moving back and forward between pages previously displayed in the same browser window.

Home Button:

In the upper right corner of each page, immediately before the navigation arrows, there is a button with a home for moving to the main page in the same browser window.

Scrolling:

On the right of the window is a vertical grey bar showing which section of the whole file is visible. For the report summary pages, the bar can be used to scroll to other parts of the page.

For the selected reports and source file pages, there is a grey circular marker called a scroll handle center-left of this bar; this can be used to move to other parts of the file.

Search:

A search box can be opened using one of ctrl f, ctrl g, or f3.

The search box can be closed using either the esc key or clicking on the X on the extreme right of the search box.

On entering text in the white part of the box, the number of matches found will be displayed in the grey area of the search box and all occurrences visible in the main window will be highlighted (in orange and yellow for the report summary pages and in purple for the selected reports and source file pages).

Also, in a vertical column on the right of the browser window, the distribution of matches in the current file will be shown in the same color (where the vertical size of the browser window represents the entire file).

For the selected reports and source code pages, on the right of the text box are 3 options for improving the search:

Aa:

clicking on this toggles between a case-insensitive or a case-sensitive search;

Ab|:

clicking on this toggles between searching for any matching text or searching only for complete words that match;

.*:

clicking on this toggles between interpreting the entered text as plain text or as a regular expression for the searched character string.

To scroll forward and backward to find other occurrences of the searched text:

scroll to next match:

type f3, ctrl g or enter or click on the > on the right of the search box;

scroll to previous match:

type shift f3 or shift ctrl g or click on the < on the right of the search box;

move the current selection:

to move the current selection to the first visible match or, if not present, to the previous one, click on the circular icon between < and > on the right of the search box.

ECLAIR Button:

In the upper right corner of the pages, between the navigation arrows, there is a box labeled ECLAIR with a set of options. It is displayed on every page, but it can be used only in the Reports Summary, Selected Reports and Source Code pages, in the others the button is inactive. When not all the rules are displayed due to the application of a filter the button will turn red. This box, activated and deactivated by a single click with the mouse left button, is divided into sub-boxes:

Options
Mouse over preview

when set, hovering the mouse over any of the area or subarea boxes will show, either on the preview window or on the preview box, a zoom to the portion of source code in that area.

Preview window

when set, previews will be shown in a new browser window; when unset, previews will be shown in the same browser window.

Current selection

The box allows the creation and storing of named selections. Filter boxes appear once you have selected or created a selection. To create a selection, insert a name for the selection in the text box; then, when a drop down menu appears, click on the Create “{SELECTION_NAME}” entry. The newly created selection will be a copy of the previous one.

Clicking on the link icon next to Current selection, a shareable link, based on the currently shown set of reports, will be automatically created and copied to the clipboard.

By opening the generated link in a browser, it is possible to visualize the same set of reports on a different eclair_report instance. This generated link will depend on the eclair_report server address and port used, and on the location of the database. If the link is used on a different machine, then in order to get the expected behaviour, these should be the same as the machine that generated the link.

It is not required that the target machine contains the same set of selections available in the original one. In fact, all the references to local selections will be expanded and substituted in the link. In this way the link becomes perfectly portable even if the original selection was created using local references.

For these reasons, the link icon feature is particularly useful if used in combination with a remote eclair_report server and a CI/CD system, such as Jenkins (see Integrating ECLAIR with Jenkins).

Area kinds and Subarea kinds

The box allows the selection and deselection of report areas by their area kind or subarea kind. Clicking on an area or subarea kind toggles between selecting and deselecting all areas with that kind. Clicking on the Area kinds or Subarea kinds box name toggles between the simultaneous selection and deselection of all the areas at the same time.

Note that this box is not displayed in the report summary pages.

Hide reports where and Show reports where

The box allows the selection and deselection of reports to be shown. Clicking on the Hide reports where or Show reports where box toggles between the two names. Initially, this box contains Select domain or operator. Clicking here provides a set of selectors:

dir:

allows the selection of reports by the directory containing an area;

file:

allows the selection of reports by the file containing an area;

fingerprint:

allows the selection of reports by their fingerprint;

first_dir:

allows the selection of reports by the directory containing the first main area;

first_file:

allows the selection of reports by the file containing the first main area;

kind:

allows the selection of reports by their report kind;

main_dir:

allows the selection of reports by the directory containing a main area;

main_file:

allows the selection of reports by the file containing a main area;

message:

allows the selection of reports based on the content of the areas;

selection:

allows the selection of reports based on the selections they belong to;

service:

allows the selection of reports by the generating service;

strictness:

allows the selection of reports by the strictness of the generating service;

DOMAIN:

allows the selection of reports by their tags in the specified DOMAIN;

any is true (OR):

opens a list of sub-selectors, any one of which must hold;

any is false (NOT AND):

opens a list of sub-selectors, none of which must hold;

all are true (AND):

opens a list of sub-selectors, everyone of which must hold;

all are false (NOT OR):

opens a list of sub-selectors, not one of which must hold.

If any one of the last 4 options: OR, NOT AND, AND and NOT OR are selected, the expanded text has several framed words or symbols. From left-to-right:

  • clicking on the first toggles between a tick (selector is enabled) and no tick (selector is temporarily disabled);

  • clicking on the second toggles between any and all;

  • clicking on the third toggles between true and false;

  • clicking on the v moves this selector box to be a sub-selector of an OR selector, allowing for alternatives to be added as needed;

  • clicking on the - removes this selector box;

  • clicking on the + adds a new box with Select domain or operator that will provide a new set of selectors.

If any of the other selectors is chosen, a further box appears containing the text Select tags. The expanded text also has a few framed words or symbols. From left-to-right:

  • clicking on the first toggles between a tick (selector is enabled) and no tick (selector is temporarily disabled);

  • clicking on the second toggles between is and is not;

  • clicking on the v makes this selector box to be a sub-selector of an OR selector, allowing for alternatives to be added as needed;

  • clicking on the - removes this selector box.

Clicking on the Select tags box opens a menu with a list of choices relevant to the specified tag domain, any one of which can be selected by clicking on it. Alternatively, by typing directly in the Select tags box:

  • only the matching choices will be shown, or

  • if the typed text begins with ^, the text is interpreted as a regular expression and, in this case, all matching tags will be selected.

To confirm any changes press enter.

If more than one tag is specified, then, next to the tag, there is a checkbox. Clicking on the checkbox, toggles between a tick (tag is enabled) and no tick (tag is temporarily disabled).

Note that by clicking in the white space next to the selected tag or in a different tag box causes the selected tag to be deleted.

Report Summary Pages

These pages show the distribution of the reports utilizing a table and a sunburst chart. The table and the chart show the information according to the selected view and the applied filters. When not all the rules are displayed due to the application of a filter a special hidden column with the counters of the hidden reports appears.

Clicking on row head, counter, or chart sector the browser enters in the selected reports page. Ctrl-clicking on a table entry the selected reports will be opened in a new browser tab, Shift-clicking on a new windows. Shift-clicking on a chart sector the selected reports will be opened in a new browser tab.

Clicking on any column head, it is possible to choose between an ascending or descending sorting.

Ctrl-clicking on a chart sector the entire chart will be recomputed showing only the distribution of the selected sector. The selection only modifies the information visualized by the chart, the view and the table will remain unchanged. To return to the previous configuration click on the button that will appear in the chart center. Hovering with the mouse over a chart sector, a column head or a row head, more information about them will be displayed.

The size of the chart can be increased or decreased by moving the mouse over the chart, pressing Ctrl and using the mouse wheel. The subdivision between the chart and the table areas can be adjusted dragging the gray bar separator. Clicking on the gray bar separator the default subdivision will be restored, if the it is already the default one all page will be completely occupied by the table.

The structure and the information contained in the table and in the chart are completely configurable through the selectors in the top area of the page. User-defined configurations can be saved by giving them a name. A saved configuration is called view.

Namely:

Views

selects the view to display. If the currently displayed view has been modified, it will appear Select.... Now it is possible to save it by clicking on the box, then on Create....

Rows

selects the information to display as row heads. If multiple categories have been selected they will appear hierarchically. This modifies also the configuration of the sunburst chart.

Columns

selects the information to display as column heads. If multiple categories have been selected for each possible combination a column will be created. This modifies also the configuration of the sunburst chart.

Selected Reports Pages

These pages show the list of selected reports using the selected classification.

Each page shows the selected reports with their areas. For each report, the first line shows the report kind and the reported service followed by lines summarising the areas for that report and showing any tags attached to the report.

Each report area line contains its location – the source file name with line and column range – and the message.

On the left of each report kind there is a ☰ button.

Clicking with the right mouse button on a report or clicking with the left mouse button on ☰ causes a a context-specific menu to appear with actions for the selection/deselection and navigation of the reports.

Namely:

Show help for this service

opens a new browser window containing the ECLAIR manual at the page with documentation for the selected service.

Edit this area

positions the already enabled IDE or editor on the report area for editing. This feature works only if a ✎ icon is shown at the beginning of the webpage title. If a ☀ icon is shown, your IDE is not properly configured (see Section All ECLAIR Software Runs on the User’s Desktop). It is also possible to use the feature Ctrl-clicking the location link.

Properties

shows all the properties of the report, the rule and the reported code. For each property it is possible, by clicking on the eye icons, enable or disable a filter for that. You can find all the filters enabled by clicking on the ECLAIR (on the top-right corner) button, inside the sub-box Hide/Show reports where. For the properties added with the Tag in browser button, it is also possible remove them by clicking on the X icon. If some text is selected you will find a message property that contains a regular expression with the selected text: all reports whose message matches the expression have this property. In addition to the general method, the message property can be hidden/shown directly after having selected the text by clicking E to exclude it, or I to include it.

Include in selection

shows all the selections not matching the current report. A new selection can be created using the Current selection group of the ECLAIR button (see Common Features). Click on a selection to include in that selection the reports having the same fingerprint of the current report

Exclude from selection

shows all the selections matching the current report. Click on a selection to exclude from that selection the reports having the same fingerprint of the current report

Tagging comment

adds a tagged comment in the IDE or editors above the report area. It is possible to choose between a series of recent comments or create a new one. To create a new one, click on Add Tagging comment action. The first word will be the tag kind, the rest of the string will be the justification (see Section Mark Locally and Justify). By clicking on the ✎ button next to a comment you can edit it. This feature requires an already enabled IDE or editor. It works only if ✎ icon is shown at the beginning of the webpage title. If a ☀ icon is shown, your IDE is not properly configured (see Section All ECLAIR Software Runs on the User’s Desktop).

Run

shows a list of possible script action that you have set. If you click on the action, ECLAIR will call your custom script passing to it a .eca file containing all the information about the report, the violation, and the rule. The script will be execute inside the eclair_report server and it can communicate with it. The name of the action corresponds to the arguments that your script will receive as input. By clicking on the first button on the right, ECLAIR will call your custom script passing to it a .eca file containing the information about all the reports on the current page. By clicking the ✎ button, you can edit the script action. To create a new one, click on Add Run action. For more information see Section Custom Get and Run actions in ECLAIR.

Get

shows a list of possible script action that you have set. If you click on the action, ECLAIR will download a .eca file containing all the information about the report, the violation, and the rule. If the user configures the browser to do that, a script will be executed. The execution will be independent of eclair_report server and there is no possibility of communication. The name of the action corresponds to the arguments that your script will receive as input. By clicking on the first button on the right, ECLAIR will call your custom script passing to it a .eca file containing the information about all the reports on the current page. By clicking the ✎ button, you can edit the script action. To create a new one, click on Add Get action. For more information see Section Custom Get and Run actions in ECLAIR.

Migrate

allows to import or export JSON files containing the local configuration. Click to Export selections to export a file selections.json containing the selections configured in the browser. Click to Import selections to import selections from a JSON file. Click to Export actions to export a file actions.json containing the selections configured in the browser, the file includes: the tags, the run actions and the get actions added. Click to Import actions to import actions from a JSON file.

On the right of each pair of line and column numbers is a magnifying glass icon. Clicking on this icon a screenshot of the source code area interested by the report will be produced. It is an image that you can save and use as you wish, to copy it right-click on the image and select Copy Image.

Source File Pages

This page shows, for the area selected on the selected reports page, the source file with line numbers as well as additional information about the area(s) located on this page.

The main display has the following features:

  • report boxes showing information about the selected reports and their areas;

  • right marker bars, narrow vertical regions on the right of the browser window which shows, for each report kind, the distribution of reports in the current file where the vertical size of the browser window represents the entire file;

  • left marker bars, narrow vertical regions on the left of the browser window which shows, for each report kind, the location of the reports in the file.

Initially, even if there is more than one area or subarea for the selected report, only the main area is shown: we say that such a report is displayed in condensed form.

Each report area is visualized by two boxes:

  1. a solid-colored box, containing a hamburger icon and the service name;

  2. an outlined box, containing the message.

These boxes which are positioned immediately below the location of the area use coloring depending on the report kind, as described in Common Features).

Hovering the mouse pointer over the service name or area message, highlights the relevant portion of source code using the same coloring as the service name box and adds a pop-up box containing the service’s summary.

How and which reports are shown on this page depends on the current focus:

  • main area focus, a single report is shown in condensed form (this is the initial focus);

  • all areas focus, a single report is shown with all its areas;

  • all reports focus, all reports present in the source file are shown in condensed form;

  • source line focus, all reports are shown for a given report kind and line of code; if there is more than one report for the kind and line, the reports are shown in condensed form.

Clicking the service or message box in the initial state changes the focus from the main area focus to the all areas focus.

Subsequently, clicking the report’s service or message box toggles between all areas focus and all reports focus.

Clicking on a colored dot on the left marker bar or right marker bar switches the display to the source line focus.

Clicking with the mouse button on the ☰ icon causes a context-specific menu to appear with actions for the selection/deselection and navigation of the reports. Namely:

Expand this report

expands the current report (if it is not already expanded), hiding all other reports in the file; same as left-clicking on the colored box of a condensed report.

First report

goes to the first report present in the source file; same as typing f.

Previous report

goes to the previous report present in the source file; same as typing p.

Next report

goes to the following report present in the source file; same as typing n.

Last report

goes to the last report present in the source file; same as typing l (the letter ell).

Show All reports

all the reports present in the source file are shown in condensed form (that is it changes to all reports focus); same as typing a.

Mark this report

sets the current report as marked; same as typing m.

Unmark this report

sets the current report as not marked; same as typing u.

Unmark all reports

sets all the reports as not marked.

Hide other services

sets all the reports generated by services other than the service that produced the current report as hidden.

Hide this service

sets all the reports generated by the same service that produced the current report as hidden.

Hide other report kinds

sets all the reports whose kind is different from the kind of the current report as hidden.

Hide this report kind

sets all the reports whose kind is equal to the kind of the current report as hidden.

Edit this area

connects any enabled IDE or editor to the report area for editing (see Section All ECLAIR Software Runs on the User’s Desktop).

Tag this area

uses any enabled IDE or editor to tag the report area shown (see Mark Locally and Justify).

Show help for this service

service specific help is shown.

Custom Get and Run actions in ECLAIR

The HTML interface of ECLAIR (see Section HTML Outputs) can be configured to perform a wide variety of automated actions. This is possible thanks to the use of the highly informative Get and Run requests. These two methods will allow you to define and run custom-designed actions, thereby boosting your workflow.

How They Work

Both Get and Run requests pass the currently selected reports in the browser to a custom script with a series of arguments that can be customized by the action. The custom script will receive the request and perform the task, exploiting the information. The two methods differ in the way they interact with the interface of ECLAIR. Using the Run method you can respond to the request by sending back information that ECLAIR will display within the interface. This is not possible with the Get action; in this case, the request will be processed externally with no further interaction.

The interactions are made possible by means of well-defined JSON files. The structure of these files is explained in Action Requests and in Action Responses.

Mantis Example

To illustrate the use of a custom script, we provide an example of interaction with Mantis. Mantis is a popular web-based bug tracking system and in the example we will see how to create an issue related to a violation directly from the ECLAIR GUI, without adding a single line to the Mantis interface.

You can find the example in:

PREFIX/eclair-VERSION/share/mantis/actions/mantis.ts

where PREFIX and VERSION are the installation prefix of ECLAIR and its version, respectively (see Chapter Installation). Let SCRIPT_PATH be the directory path of this file.

The example is in TypeScript, but any scripting language can be used. It is enough that the script correctly interprets the JSON request provided via /dev/stdin. The example script file is not ready for use and only intended to show how to create automations; it must be adapted to your Mantis settings.

Note that the TypeScript file cannot be interpreted directly and has to be converted to a JavaScript file. An already converted file can be found in SCRIPT_PATH/mantis.js. Since you will probably need to modify the file, we explain here how the delivered JavaScript file was obtained. To do this, Node, which can be downloaded from the Node website, needs to be installed. The steps for the conversion are the following:

cd SCRIPT_PATH
npm install
npm run compile

Now, run the eclair_report server with the -server_area_run_command set to the script path:

eclair_report  "-server_area_run_command=node,SCRIPT_PATH/mantis.js" -db=ECD_FILE -browser -server

Alternatively, if you are using the eclair_gui, the script location can be provided during the View step: click on the + Add argument button next to ECLAIR report server additional args, and add the string:

-server_area_run_command=node,SCRIPT_PATH/mantis.js

In both cases, when writing SCRIPT_PATH use the full path and avoid using any expansion symbol such as ~. Note that there must be no space between node, and SCRIPT_PATH.

If the eclair_report server connects using an IDE or editor directly, then add:

-server_area_run_command=node,SCRIPT_PATH/mantis.js

to the integration plugin settings. This operation differs for each IDE and for each editor; so check how to configure your IDE in Section Integrating ECLAIR with IDEs, Editors, and CI Tools.

Since our example is in NodeJS we have put node as command of -server_area_run_command, and then the script location as first argument.

If your script can be interpreted directly by the shell and script.sh is your custom script file that accepts two input arguments, then the option should be instantiated as follows:

eclair_report "-server_area_run_command='script.sh,arg1,arg2'" -db=ECD_FILE -browser -server

If your script cannot be interpreted directly by the shell (like mantis.js), you have to provide an interpreter (node in our example) followed by a script location. Letting INTERPRETER be the interpreter and EXT the specific extension of the scripting language, the general pattern is:

eclair_report "-server_area_run_command=INTERPRETER,script.EXT" -db=ECD_FILE -browser -server

Note that only one script should be provided but, if you need more features, the custom script can call other scripts. For example, you could use the string content of the action to distinguish the various features.

The provided Mantis script will split the string content of the action into tagged sub-strings and these will be used to set the Mantis fields for the issue. The following tags are supported by the script:

u:{USER} to assign the issue to the Mantis user USER,

c:{CATEGORY} to set the category of the Mantis issue to CATEGORY,

s:{SEVERITY} to set the severity of the Mantis issue to SEVERITY,

p:{PRIORITY} to set the priority of the Mantis issue to PRIORITY,

t:{TAG} to add the TAG tag to the Mantis issue.

Note that, in general, the string content of an action is the only way to provide action-specific information to a script.

It is now time to prepare the action: right-click on a report (or click on ☰), click on Add Run action then put mantis u:Zoe to assign the issue to the user Zoe. Now, if you click on the action, a request will be sent to the script, which will create an issue on Mantis, assigned to the user Zoe, with the information in the report. It will also attach to the issue a screenshot of the surrounding lines.

An issue page containing all this information will open in your browser; just confirm the submission. Alternatively you can use a Get action in the same way, to download a .eca file and pass it to the mantis script as follows:

node {SCRIPT_PATH}/mantis.js {ECA_PATH}/action-{DOWNLOAD_STAMP}.eca

Action Requests

As explained in selected reports, to create a new action, right-click on a report (or click on ☰), select Run or Get, and click on Add Run action or Add Get action. Now the interface will ask you to insert a string. This string is not just a mnemonic name for the action, but can be used to provide information to the script.

Note that only one script can be used, so if you want to call many scripts you have to create a general one and then using the string content of the action, to call as needed. Also note that the reports’ information is provided to the script via a JSON file with the extension .eca. It contains all the information about the action, the report(s), the violation(s), and the service(s).

ActionData is the main object containing information about the action and the reports contained in the JSON file.

interface ActionData {
   method: string;
   action: string;
   user: string;
   database: string;
   referer: string;
   project_root: string;
   project_name: string;
   reports: ActionReport[];
}
method

is the run or get method in string format;

action

is the action string, providing information for your script;

user

is the name of the user sending the request in string format;

database

is the absolute path of the database in string format;

referer

is the url of the web page the action came from;

project_root

is the path of the project root in string format;

project_name

is the name of the project in string format;

reports is an array of reports information. The reports listed depend on how the request is created. The GUI allows creating the request with just the selected report or, by clicking on Run action on all visible reports, with all the reports visible in the current page of the GUI.

ActionReport is an object containing information about a single report.

interface ActionReport {
   id: number;
   service: ActionReportService;
   kind: string;
   properties: ActionReportProperty[];
   areas: ActionReportArea[];
   selections: string[];
}

id is a number that denotes the specific report within the database;

service is an object containing information about the ECLAIR service that generates the report;

kind is the report kind in string format;

properties is an array containing the report’s properties

areas is the list of report areas;

selections is the list of the selection names to which the report is associated.

ActionReportProperty is an object containing a property of the report.

interface ActionReportProperty {
   domain: string;
   values: ActionReportValue[];
}

domain is the domain of the property

values is an array containing property values

ActionReportValue is an object containing the value of a property of the report.

interface ActionReportValue {
   value: string;
   doc?: string;
}

value is the value of the property

doc is the documentation optionally attached to the value

ActionReportService is an object containing information about the service that generates the report.

interface ActionReportService {
   id: string;
   summary: string;
   kind: string;
   strictness: string;
}

id is the name of the service (as given in this manual) in string format;

summary is a short text describing the service;

kind is the service kind in string format;

strictness is the strictness of the service in string format.

ActionReportArea is an object containing information about a specific area of a report.

interface ActionReportArea {
   idx: number;
   file: string;
   url: string;
   image?: string;
}

idx is a number identifying the area within the report;

file is the name of the file where the area is located;

url is a URL for the report view at this area. Note that this link only works if the GUI’s server is running;

image is an optional image in base64 format showing a screenshot of the surrounding lines of the code where the area is located.

Action Responses

The Run method is used for interacting with the eclair_report server. There are three different types of response that can be sent back from your script; these are:

  • RunMessageAction

  • RunConsoleAction

  • RunOpenAction

  • RunDownloadAction

Each of these asks for a different kind of action by eclair_report and requires different information. The communication is implemented via JSON files and each kind of request has its own pattern.

RunMessageAction will ask eclair_report to show a Toast notification. A Toast is a unobtrusive window element used to display brief, auto-expiring window of information to the user. The Toast will appear at the top-right corner of the GUI.

interface RunMessageAction {
  action: "info" | "warning" | "error" | "success";
  message: string;
}

action is a string denoting the type of Toast and can be info, warning, error or success;

message is the text to be shown inside the Toast notification.

RunConsoleAction will ask eclair_report server to emit a console message. This action can only be used in a browser and will not work in the GUI. The stream used will depend on the method. If the method is run, then the message is sent to the output stream of the browser. If the method is get then the message is sent to the output stream of the terminal where eclair_report is running.

RunConsoleAction {
  action: "consoleLog" | "consoleErr";
  data: unknown;
}

action is the output stream to be used and can be consoleLog or consoleErr;

data is the message content to be sent to the selected stream.

RunOpenAction will ask eclair_report to open a new webpage.

interface RunOpenAction {
  action: "open";
  url: string;
  target?: string;
}

action is the type of the open action and must be open;

url is the URL of the page to be opened;

target is an optional value denoting where to display the linked URL:

_self will use the current browsing context;

_blank will usually use a new tab, but users can configure browsers to open a new window instead,

_parent will use the parent browsing context of the current one but, if there is no parent, it behaves as if it is _self,

_top will use the top most browsing context (the “highest” context that is an ancestor of the current one) but, if there are no ancestors, it behaves as if it is _self.

RunDownloadAction will ask eclair_report to download a file.

interface RunDownloadAction {
  action: "download";
  fileName: string;
  mimeType: string;
  text?: string;
  data?: string; // Base64
}

action is the type of the download action and must be download;

fileName is the name of the file to download;

mimeType is the Multipurpose Internet Mail Extensions or MIME type of the file to download;

text is the content of the file to download in text format; if this field is set, then data should remain unset;

data is the content of the file to download in base64 format; if this field is set, then text should remain unset.

Error Reports

Errors such as parser errors are reported in textual format by the service B.REPORT.ERR which is always enabled. An error report consists of a few lines of ordinary text, one line for each area and subarea with the following default structure:

POS: error for SKIND SERVICE (SUMMARY) Loc #AREA_NO [TAG: MSG]
POS: Loc #AREA_NO [AKIND: MSG]
...

where:

  • POS specifies the position in the code;

  • SKIND is the kind of the service that generated the report;

  • SERVICE is the id of the service that generated the report;

  • SUMMARY is a summary description of the service SERVICE;

  • AREA_NO is a progressive area number within the report;

  • AKIND is the kind of the area;

  • MSG includes additional information about the area.

Such lines are interspersed with lines of code, which, in turn, can optionally be followed by ASCII markers of the form ^, <> and <~~~> that hint at a position in or portion of the preceding line (see option B.REPORT.ERR snippet).

Example:

The program ex1.c consisting of just the single line of code:

unsinged u;

will produce the following error report (where, as usual, a trailing backslash indicates line continuation):

ex1.c:1.1-1.8: error for parser B.PARSER \
  (The code shall be parsable without errors by the ECLAIR parser. \
   If the code is parsed with errors the AST is incomplete and the \
   results of ECLAIR analyses are likely to be incorrect.) \
   Loc #1 [culprit: unknown type name `unsinged']
unsinged u;
<~~~~~~>
ex1.c:1:1: error: unknown type name 'unsinged'; did you mean \
'unsigned'?
unsinged u;
^~~~~~~~

This says that the offending type name can be found in the source area beginning at line 1, column 1 and ending at line 1, column 8 in ex1.c (where both the line and column numbers are counted starting from 1).

Where the non-compliant code has been obtained by macro expansion, the location will refer to the position of the expansion in the source file, but the report item will also include the text (MACRO) to indicate this. It is also possible to show the source code both before and after the preprocessing stage: for this, use the preprocessed option available to all B.REPORT.* services.

Example:

The following example program ex2.c:

#define int32_t unsinged
int32_t u;

if analyzed using an ECLAIR configuration that includes -config=B.REPORT.ERR,preprocessed=show, will output the following error report:

ex2.c:2.1-2.7: (MACRO) error for parser B.PARSER \
  (The code shall be parsable without errors by the ECLAIR parser. \
   If the code is parsed with errors the AST is incomplete and the \
   results of ECLAIR analyses are likely to be incorrect.) \
   Loc #1 [culprit: unknown type name `unsinged']
int32_t u;
<~~~~~>
<preprocessed ex2.c>:1.1-1.8: for #1 [culprit: preprocessed tokens]
unsinged u;
<~~~~~~>
ex2.c:1.17-1.24: for #1 [culprit: expanded from macro `int32_t']
#define int32_t unsinged
                <~~~~~~>
ex2.c:1:17: error: unknown type name 'unsinged'; did you mean 'unsigned'?
#define int32_t unsinged
            ^~~~~~~~
ex2.c:2:1: note: in expansion of macro 'int32_t'
int32_t u;
^~~~~~~
Browsing Textual Reports

Textual reports can be browsed on-screen like any other compiler-generated diagnostics (warning or error messages). As an alternative, all the textual reports can be redirected to a text file using the option B.REPORT.ERR output, to be available to any post-processing phase required by custom browsing and/or reporting tools.

For emacs users, a simple and useful possibility is to use a command such as the following:

eclair_env -eval_file=FILE \
-project_name=NAME -project_root=TOP_SOURCE_DIR \
-config=B.REPORT.ERR,output=LOG.etr -- make

using the ECLAIR options -eval_file, -project_name, -project_root, and service B.REPORT.ERR. When opening the file LOG.etr on completion of these commands, emacs will automatically enter compilation mode, so that the source location information in the reports will link directly to the corresponding project source code.

Report Tools

When an existing project is checked for compliance with respect to a (new) set of services, if the project or a part of it was not originally coded to comply with those services, it is quite likely that you will have many thousands of reports. Obtaining report counts for each service and/or a statistical sampling of the reports themselves is very helpful in understanding which services (configurations) should not be enabled and which parts of the project should be checked. This is one of the many uses of the eclair_report command.

The eclair_report Command

The eclair_report program is a utility implementing several distinct functionalities.

Creating (or Updating) an ECLAIR Database

To create the ECLAIR database, in the sequel simply called the database, the binary output format should be enabled. A binary output is a file denoted by the extension .ecb. The generation of binary output files is described in Section Reporter B.REPORT.ECB, where the service B.REPORT.ECB is discussed. These files are loaded into the database by using command lines such as

eclair_report -create_db=ECD_FILE -load=ECB_FILE,...
eclair_report -create_db=ECD_FILE ECB_FILE ... -load

All the binary output files listed as arguments in command -load and/or previously listed on the command line will be translated and loaded into a newly created database file called ECD_FILE. Note that the optional argument of -load is a comma-separated list of files: all the options of ECLAIR-related commands taking lists do take comma-separated lists. An obvious consequence is that, if the selection of files to be loaded is defined by means of wildcard patterns, only the second form will work. For example:

eclair_report -create_db=PROJECT.ecd q*.ecb r1?.ecb -load

If the database file already exists, then command lines of the form

eclair_report -db=ECD_FILE -load=ECB_FILE,...
eclair_report -db=ECD_FILE ECB_FILE ... -load

can be used to add the analysis results contained in the given binary output files to the existing database. Note however that this incremental addition will only happen if the database and the binary output files contain the very same information for the project name and project top source directory; if any mismatch is detected, an error is produced and analysis results loading will be interrupted.

The -load command also supports reading the binary output data stream from standard input, using the pseudo-file /dev/stdin as follows:

eclair_report -create_db=ECD_FILE /dev/stdin -load

The -load command sets the tags for all the loaded reports for their associated tag domains.

Opening an ECLAIR Database

If the database of analysis results is contained in a file called ECD_FILE, the command to open it on the default browser is:

eclair_report -db=ECD_FILE -browser -server

If the database is located on a remote machine this operation is still possible. In this case, before we need to start the eclair_report server, then we will be able to open the database from a local browser. The operations required depend on the type of license available in the remote machine.

In the case of a site/multisite/enterprise license the remote server can provide the results without any restriction. eclair_report should be installed and started just in the remote machine.

In the case of a partial coverage license, the remote server cannot provide the results to other machines, so a proxy connection that exploits the local license should be used. Both machines should run eclair_report. This option requires all machines from which we want to access the database to have a license.

The command to start the server is:

eclair_report -server

To open the server access from the local browser to one of the following links:

http://REMOTE_MACHINE:3786/fs/PATH_TO_DB;index.html
https://REMOTE_MACHINE:3787/fs/PATH_TO_DB;index.html

if the remote server does have a site/multisite/enterprise license;

http://localhost:3786/host/REMOTE_MACHINE:3786/fs/PATH_TO_DB;index.html
http://localhost:3786/hosts/REMOTE_MACHINE:3787/fs/PATH_TO_DB;index.html

if the remote server does have a partial coverage license.

In both cases, REMOTE_MACHINE is the address or the DNS alias of the remote machine and PATH_TO_DB is the path of the database.

Producing HTML Outputs

If the database of analysis results is contained in a file called ECD_FILE, the command to produce HTML summaries in folder OUTPUT_DIR is

eclair_report -db=ECD_FILE -summary_html=OUTPUT_DIR

If your license allows that, you can also produce full HTML outputs with the command

eclair_report -db=ECD_FILE -full_html=OUTPUT_DIR

It is important to note that full HTML outputs contain also all the sources that are subjects to reports, suitably annotated. If such sources are not wanted in the HTML outputs (e.g., for confidentiality reasons, the command to be used is

eclair_report -db=ECD_FILE -full_html=OUTPUT_DIR,true

Producing Textual Outputs

If the database of analysis results is contained in a file called ECD_FILE, the command to produce plain text summaries in folder OUTPUT_DIR is

eclair_report -db=ECD_FILE -summary_txt=OUTPUT_DIR

If your license allows that, you can also produce full textual outputs with the command

eclair_report -db=ECD_FILE -full_txt=OUTPUT_DIR

Producing ODT Outputs

ECLAIR supports the production of outputs in ODT format (OpenDocument Text Flat XML format). If the database of analysis results is contained in a file called ECD_FILE, the command to produce ODT summaries in folder OUTPUT_DIR,

eclair_report -db=ECD_FILE -summary_odt=OUTPUT_DIR

If your license allows that, you can also produce full ODT outputs with the command

eclair_report -db=ECD_FILE -full_odt=OUTPUT_DIR

There are summaries in some of the files produced. For technical reasons these cannot be pre-generated, so they will appear incomplete. To properly generate a summary, click Tools → Update → Update All. Doing that procedure all summaries in the document will be updated.

Outputs limited to fixable reports

The files book.odt and book.doc, together with the CSV data generated by -reports_csv, only include fixable reports by default. Specifically, the following commands rely on the built-in sel_fixable selection:

As a consequence, informational messages and metrics are not listed in any of these outputs even if they appear in other formats.

Overriding the selection to include metrics

If you wish to include metrics (or other excluded kinds) in the book outputs, you can override sel_fixable. For instance, save the following override into a file (e.g., book_selection.ecl):

# Override the fixable reports definition
defun(sel_fixable(s),
  create_sel(s,
             [["clear_all",s],
              ["add_kind",s,"*"],
              ["del_kind",s,"information"],
              ["select_kind",current_sel(),s]]),
  sel(s))

Run eclair_report specifying this file with -eval_file:

eclair_report -eval_file=book_selection.ecl -db=ECD_FILE -full_odt=OUTPUT_DIR
eclair_report -eval_file=book_selection.ecl -db=ECD_FILE -full_doc=OUTPUT_DIR

Both commands will produce book.odt / book.doc including metrics.

Note that the same override also affects -reports_csv.

Producing DOC Outputs

ECLAIR supports the production of outputs in OOXML format (Office Open XML, also informally known as DOC or DOCX). If the database of analysis results is contained in a file called ECD_FILE, the command to produce DOC summaries in folder OUTPUT_DIR,

eclair_report -db=ECD_FILE -summary_doc=OUTPUT_DIR

If your license allows that, you can also produce full ODT outputs with the command

eclair_report -db=ECD_FILE -full_doc=OUTPUT_DIR

In some of the files produced there are information that, for technical reasons, cannot be pre-generated. Instead of them placeholders with written Click here and press F9 will appear. These are the summary, the project name, and the timestamp. To properly generate them click on placeholders and press F9. The summary can be updated also by clicking Update Index in the Index group on the References tab.

See Outputs limited to fixable reports for details about which reports are included in book.doc (and how to customize that selection).

Additional Ready-Made Output Recipes

The eclair_report output facilities are highly configurable so that any kind of output can be produced. Ready-made recipes are being made available for the most popular output formats: those supported in the version of ECLAIR that was licensed along with this manual are described in this section. Contact BUGSENG to enquire about the availability of more output recipes.

Report Counts According to FCA Norm 7-Z0072

Norm 7-Z0072 of FCA (formerly Fiat Auto) prescribes, among other things, the provision of report counts in a particular Microsoft Excel format. When a database of analysis results has been constructed as previously described, the prescribed file can be automatically generated with a command of the form

eclair_report -db=ECD_FILE -report_counts_7_Z0072=XLS_FILE[,PATTERN]

where ECD_FILE is the database file, PATTERN is a wildcard pattern matching the reported services whose report counts should be included, and XLS_FILE is the name of the desired Excel output file. For example:

eclair_report -db=PROJECT.ecd -report_counts_7_Z0072=file.xls,MC2.*
Metrics Output to Spreadsheet Programs

Program metrics computed by ECLAIR and stored in the database can be exported in a way that makes it easy to post-process them using popular spreadsheet programs. In order to do that, the first step is to produce a particular textual representation of the metrics using a command of the form

eclair_report -db=ECD_FILE -metrics_csv=TXT_FILE

where ECD_FILE is the database file and TXT_FILE is the name of the desired output file, which must have the .txt to make sure it is not misinterpreted by the spreadsheet program. For example:

eclair_report -db=PROJECT.ecd -metrics_csv=metrics.txt

Once that is done, you can work on the metrics data using pivot tables provided with ECLAIR both for Microsoft Excel and for LibreOffice Calc and OpenOffice.org Calc.

With Microsoft Excel open the file

PREFIX\eclair-VERSION\share\metrics\tools\metrics.xlsm

making sure macros are enabled. In certain versions of Windows, enabling macros is not enough, and the file should be unblocked before opening it by clicking on Properties and then select the Unblock checkbox. For more information about this feature, please refer to KB5070960 . The Thresholds sheet will be displayed, which contains example thresholds for some metrics: please make sure you set the thresholds according to your needs and coding standards. Then click on the Pivot sheet tab, click on cell A1, containing File on a blue background, and select your TXT_FILE. Then click on cell B2 and select function, unit or program to see the values for metrics defined at that scope.

For LibreOffice Calc or, equivalently, OpenOffice.org Calc, the procedure is almost identical, the only difference being that the file to be opened is

PREFIX/eclair-VERSION/share/metrics/tools/metrics.ods

If warned about the danger of macros, do enable macros. If asked whether to update the links to other files, do accept. Then proceed as for Microsoft Excel.

Note that the pivot tables provided with ECLAIR are just examples: feel free to adapt them to meet your needs.

Available eclair_report Options

We now present some useful commands that allow the user to specify how the reports should be output. A template for the available commands is provided in

PREFIX/eclair-VERSION/share/config/templates/eclair_report.ecl
Option -actions
-actions
-actions[=STATE]

Set server behavior for commands received by remote clients.

STATE:

whether server accept to be administered by remote clients. Accepted values are:

  • true: eclair_report server can be administered by remote clients;

  • false: eclair_report server refuses to be administered by remote clients;

If omitted it is assumed to be true.

Default:

-actions=false

Option -add_data
-add_data
-add_data=APPENDS,...

Add the provided rows to the database specified on the command line (see the -db option).

Example of usage:

eclair_report -db=PROJECT.ecd '-add_data=:t(x,2,y,3,z,4),:t(x,6,y,7,z,8)'

The above example appends to the table t in PROJECT.ecd the rows (x,2,y,3,z,4) and (x,6,y,7,z,8)

APPEND:

append operation to perform. Accepted forms are:

  • :TABLE(ROW): append to TABLE the row ROW

ROW

accepted forms are:

  • CELL: a pair tag-value

  • CELL,ROW: a list of cells

CELL

accepted forms are:

  • TAG,VALUE: element of the row

Option -area
-area
-area=VARIANT

Set the area variant for the current selection.

VARIANT:

area variant id.

Option -auth
-auth
-auth=PREFIX,KIND[,ARG]

Set the authorization list for requests to eclair_report server. First matching entry decides which authentication mechanism should be used.

Only ECLAIR databases and files that are descendants of directories ending with .ecdf under the server root can be served if authorized. Files starting with . cannot be served for security reasons.

Without using this option all requests (see -server_root) will be granted.

Example of usage:

Let’s suppose to have two ecdf directories one called allow.ecdf, the other deny.ecdf and that we want to provide access only to files in the first one. The following line can be used:

eclair_report -auth=/test/allow.ecdf,allow -server_root=/test -server

Now, asking 127.0.0.1:3786/fs/test/allow.ecdf/example.txt the server will provide the requested file. Instead, it will return a failure asking a file in /deny.ecdf.

Remember that all paths must be absolute

For examples of authentication methods htpasswd and token see -htpasswd

PREFIX:

the absolute path prefix for matching databases and .ecdf directories.

KIND:

authentication mechanism kind. Accepted values are:

  • allow: allow the access;

  • deny: deny the access;

  • jenkins: ask to Jenkins server using URL specified in ARG;

  • htpasswd: use a file .htpasswd file created with -htpasswd in the folder of the ECLAIR database or one of its ancestors. The browser will ask an username and a password to authentication the request;

  • gitlab: ask to GitLab server using URL specified in ARG;

  • token: use a file .rtokens file created with -htpasswd in the folder of the ECLAIR database or one of its ancestors. Provide rtoken=TOKEN as URL parameter to authenticate the request;

ARG:

Jenkins/GitLab server URL for jenkins/gitlab authorization mechanisms.

Option -auto_shutdown
-auto_shutdown
-auto_shutdown=TIME

Set eclair_report to turn off automatically after a set period of time from when all GUI or browser tabs are closed.

TIME:

the period of time in seconds before the automatic shutdown.

Option -browser
-browser
-browser[=STATE]

Set the browser state when the eclair_report server starts.

STATE:

whether the browser is launched when the server starts. Accepted values are:

  • true: launch the browser when server starts;

  • false: do not launch the browser when server starts;

If omitted it is assumed to be true.

Default:

-browser=false

Option -build_compdb
-build_compdb
-build_compdb=OUTPUT

Output a JSON compilation database of the build as intercepted by ECLAIR.

OUTPUT:

the output file.

Option -build_makefile
-build_makefile
-build_makefile=OUTPUT

Output a Makefile that reproduces the build as intercepted by ECLAIR.

OUTPUT:

the output file.

Option -build_ninja
-build_ninja
-build_ninja=OUTPUT

Output a ninja build file that reproduces the build as intercepted by ECLAIR.

OUTPUT:

the output file.

Option -clear_data
-clear_data
-clear_data=TABLE_GLOB

Remove the table with the TABLE_GLOB tag in the database specified on the command line (see the -db option).

TABLE_GLOB:

tag of the table to remove.

Option -create_db
-create_db
-create_db=ECD_FILE

Create a database file to be used for loading the results.

ECD_FILE:

the database file to be created.

Option -db
-db
-db=ECD_FILE

Specify the database file to be used by following commands.

ECD_FILE:

the database file to be used.

Option -detailed_trial
-detailed_trial
-detailed_trial

Full report details are only exported to files with site/multisite/enterprise license coverage. For trial licenses, it is possible to use this command to consume one of the available tokens to showcase the detailed reports functionality.

Default:

-detailed_trial=false

Option -diff_criteria
-diff_criteria
-diff_criteria=CRITERIA

Specify the criteria to use for detecting common reports between databases.

CRITERIA:

criteria for common reports detection. Accepted values are:

  • fingerprint: consider the service id, the report kind, the report category, the areas kinds, the areas canonical filenames, the areas messages and the tokens in the ranges shown by the areas. This is the default;

  • hash: consider all the information contained in a report. This criteria is not stable since such generated hashes change very easily at any editing of the source file;

Option -diff_full_txt
-diff_full_txt
-diff_full_txt=OLD_DB,NEW_DB

Create for each enabled service two files diff_add.txt and diff_del.txt containing a list of the services respectively with removed and added reports in the provided databases.

Removed reports are the ones that are only in the first database provided.

Added reports are the ones that are only in the second database provided.

The option creates also a directory named diff_output containing, for each enabled service two files SERVICE.del.etr and SERVICE.add.etr containing respectively the removed and added reports in the provided databases.

If you are not interested in these detailed per-service outputs see -diff_summary_txt.

The configuration requires to specify a criteria that will be used to compute the differences using -diff_criteria.

The common reports to both provided databases will be tagged with common in the diff domain.

This information can be easily exploited creating filters in the interactive reports view or when creating any type of artifacts starting from one of the tagged databases.

Example of usage:

eclair_report -diff_full_txt=PROJECT.old.ecd,PROJECT.new.ecd
OLD_DB:

the old database to compare.

NEW_DB:

the new database to compare.

Option -diff_summary_txt
-diff_summary_txt
-diff_summary_txt=OLD_DB,NEW_DB

Create for each enabled service two files diff_add.txt and diff_del.txt containing a list of the services respectively with removed and added reports in the provided databases.

Removed reports are the ones that are only in the first database provided.

Added reports are the ones that are only in the second database provided.

If you are interested in a more detailed output with per-service differences see -diff_full_txt.

The configuration requires to specify a criteria that will be used to compute the differences using -diff_criteria.

The common reports to both provided databases will be tagged with common in the diff domain.

This information can be easily exploited creating filters in the interactive reports view or when creating any type of artifacts starting from one of the tagged databases.

Example of usage:

eclair_report -diff_summary_txt=PROJECT.old.ecd,PROJECT.new.ecd
OLD_DB:

the old database to compare.

NEW_DB:

the new database to compare.

Option -explain_doc
-explain_doc
-explain_doc=OUTPUT

Output the explained ECLAIR configuration in Microsoft Word Flat OPC XML format.

OUTPUT:

the output file.

Option -explain_html
-explain_html
-explain_html=OUTPUT

Output the explained ECLAIR configuration in HTML format.

OUTPUT:

the output file.

Option -explain_json
-explain_json
-explain_json=OUTPUT

Output the explained ECLAIR configuration in JSON format.

OUTPUT:

the output file.

Option -explain_odt
-explain_odt
-explain_odt=OUTPUT

Output the explained ECLAIR configuration in OpenDocument Text Flat XML format.

OUTPUT:

the output file.

Option -explain_xml
-explain_xml
-explain_xml=OUTPUT

Output the explained ECLAIR configuration in XML format.

OUTPUT:

the output file.

Option -explain_xslt
-explain_xslt
-explain_xslt=XSLT,OUTPUT

Output the explained ECLAIR configuration as filtered by the specified XSLT file.

XSLT:

the XSLT file used to process XML data.

OUTPUT:

the output file.

Option -files
-files
-files=ECB_FILE,...

Specify .ecb file(s) to be loaded or saved. Files added with this option are queued and are actually loaded when the -load option is used or saved when the -save option is used.

ECB_FILE:

the ECB file (or the list of ECB files) to add to the list of files to load or to save. Use /dev/stdin to specify the standard input. Note that all files in the command line are also added.

Option -files_doc
-files_doc
-files_doc=OUTPUT

Output info about the analyzed files in Microsoft Word Flat OPC XML format.

OUTPUT:

the output file.

Option -files_html
-files_html
-files_html=OUTPUT

Output info about the analyzed files in HTML format.

OUTPUT:

the output file.

Option -files_json
-files_json
-files_json=OUTPUT

Output info about the analyzed files in JSON format.

OUTPUT:

the output file.

Option -files_odt
-files_odt
-files_odt=OUTPUT

Output info about the analyzed files in OpenDocument Text Flat XML format.

OUTPUT:

the output file.

Option -files_txt
-files_txt
-files_txt=OUTPUT

Output info about the analyzed files in pure text format.

OUTPUT:

the output file.

Option -files_xml
-files_xml
-files_xml=OUTPUT

Output info about the analyzed files in XML format.

OUTPUT:

the output file.

Option -files_xslt
-files_xslt
-files_xslt=XSLT,OUTPUT

Output info about the analyzed files as filtered by the specified XSLT file.

XSLT:

the XSLT file used to process XML data.

OUTPUT:

the output file.

Option -first_area
-first_area
-first_area

Show only the first report area, thus omitting all the others, when full reports details are requested using a site/multisite/enterprise license.

Default:

-first_area=false

Option -frames_doc
-frames_doc
-frames_doc=OUTPUT

Output info about the analyzed frames in Microsoft Word Flat OPC XML format.

OUTPUT:

the output file.

Option -frames_html
-frames_html
-frames_html=OUTPUT

Output info about the analyzed frames in HTML format.

OUTPUT:

the output file.

Option -frames_json
-frames_json
-frames_json=OUTPUT

Output info about the analyzed frames in JSON format.

OUTPUT:

the output file.

Option -frames_odt
-frames_odt
-frames_odt=OUTPUT

Output info about the analyzed frames in OpenDocument Text Flat XML format.

OUTPUT:

the output file.

Option -frames_txt
-frames_txt
-frames_txt=OUTPUT

Output info about the analyzed frames in pure text format.

OUTPUT:

the output file.

Option -frames_xml
-frames_xml
-frames_xml=OUTPUT

Output info about the analyzed frames in XML format.

OUTPUT:

the output file.

Option -frames_xslt
-frames_xslt
-frames_xslt=XSLT,OUTPUT

Output info about the analyzed frames as filtered by the specified XSLT file.

XSLT:

the XSLT file used to process the XML data.

OUTPUT:

the output file.

Option -full_doc
-full_doc
-full_doc=OUTPUT_DIR

Output the complete project project report in Microsoft Word Flat OPC XML format. The report with front and back covers is written to book.doc, whereas the version without covers is written to index.doc. See -detailed_trial for license-specific information.

OUTPUT_DIR:

the top output directory.

Option -full_html
-full_html
-full_html=OUTPUT_DIR[,NO_SOURCES]

Output the complete project report in HTML format. Main file is index.html. See -detailed_trial for license-specific information.

OUTPUT_DIR:

the top output directory.

NO_SOURCES:

whether to omit sources from project report. Accepted values are:

  • true: omit sources;

  • false: include sources referenced by reports;

If omitted it is assumed to be false.

Option -full_json
-full_json
-full_json=OUTPUT_DIR[,NO_SOURCES]

Output the complete project report in JSON format. See -detailed_trial for license-specific information.

OUTPUT_DIR:

the top output directory.

NO_SOURCES:

whether to omit sources from project report. Accepted values are:

  • true: omit sources;

  • false: include sources referenced by reports;

If omitted it is assumed to be false.

Option -full_odt
-full_odt
-full_odt=OUTPUT_DIR

Output the complete project report in OpenDocument Text Flat XML format. The report with front and back covers is written to book.odt, whereas the version without covers is written to index.odt. See -detailed_trial for license-specific information.

OUTPUT_DIR:

the top output directory.

Option -full_txt
-full_txt
-full_txt=OUTPUT_DIR

Output the complete project report in pure text format. See -detailed_trial for license-specific information.

OUTPUT_DIR:

the top output directory.

Option -full_xml
-full_xml
-full_xml=OUTPUT_DIR[,NO_SOURCES]

Output the complete project report in XML format. See -detailed_trial for license-specific information.

OUTPUT_DIR:

the top output directory.

NO_SOURCES:

whether to omit sources from project report. Accepted values are:

  • true: omit sources;

  • false: include sources referenced by reports;

If omitted it is assumed to be false.

Option -htpasswd
-htpasswd
-htpasswd=FILE,USER[,PASSWORD]

Add/change entry in .htpasswd like files.

These files can be used with the authentication method htpasswd and token of -auth.

Example of usage with method htpasswd:

Let’s suppose we want to create a .htpasswd file to grant permissions on the directory test/allow.ecdf and its descendants, but not to test/deny.ecdf. The following line can be used:

eclair_report -htpasswd=/test/allow.ecdf/.htpasswd,user,TOKEN
eclair_report -auth=/test/allow.ecdf,htpasswd -server_root=/test -server

Now, asking 127.0.0.1:3786/fs/allow.ecdf/example.txt the browser will ask username and password. Instead, it will return a failure asking a file in /deny.ecdf.

Example of usage with method token:

Let’s suppose we want to create a .rtokens file to grant the same permissions. The following line can be used:

eclair_report -htpasswd=/test/allow.ecdf/.rtokens,user,TOKEN
eclair_report -auth=/test/allow.ecdf,token -server_root=/test -server

Now, asking 127.0.0.1:3786/fs/allow.ecdf/example.txt?rtoken=TOKEN the server will provide the requested file. Instead, it will return a failure asking a file in /deny.ecdf.

Remember that all paths must be absolute

FILE:

password file.

USER:

user name.

PASSWORD:

password (if empty the entry for the user is removed).

Option -json_data
-json_data
-json_data=WHAT,OUTPUT[,OPTS][,FIELDS]

Output the tables provided in WHAT on the specified JSON output file OUTPUT_FILE using the options provided in OPTS and adding the field values FIELDS.

WHAT:

comma-separated list of tables to export.

OUTPUT:

the output file where the selected tables will be exported in JSON format.

OPTS:

comma-separated list of options to use to generate the output file.

FIELDS:

comma-separated list of field values to add to the output file.

Option -load
-load
-load=ECB_FILE,...

Load the .ecb result file(s) in the database.

ECB_FILE:

the ECB file (or the list of ECB files) to be loaded or /dev/stdin for the standard input.

Option -load_xml
-load_xml
-load_xml=XML_FILE,...

Load analysis results in XML format in the database.

XML_FILE:

the XML file to be loaded or /dev/stdin for the standard input.

Option -lock_timeout
-lock_timeout
-lock_timeout=TIME

Set eclair_report timeout for access to a locked database.

TIME:

the period of time in millseconds before to give up.

Option -metrics_csv
-metrics_csv
-metrics_csv=OUTPUT

Output metrics’ values in textual, TAB-separated form that is suitable for further elaboration with spreadsheet software. The information is extracted from the database specified on the command line (see the -db option). Suitable pivot tables are supplied with ECLAIR for Microsoft Excel, LibreOffice Calc, and OpenOffice.org Calc.

With Microsoft Excel, open the file PREFIX/eclair-VERSION/share/reports/tools/metrics.xlsm making sure macros are enabled.

The Threshold sheet contains example thresholds for the metrics: please make sure to set them according to your requirements. Then open the Pivot sheet tab, click on cell A1, containing File on a blue background, and select the generated OUTPUT file. Then click on cell B2 and select function, unit or program to show the values of the metrics. The metrics, in the Pivot sheet tab, that exceed the thresholds will be shown with a red background.

For LibreOffice Calc or, equivalently, OpenOffice.org Calc, the procedure is almost identical, the only difference is that the file to be open is PREFIX/eclair-VERSION/share/metrics/tools/metrics.ods

Even if warned about the danger of macros, you must still enable macros. If asked whether to update the links to other files, accept. Then proceed as for Microsoft Excel.

Note that the pivot tables provided with ECLAIR are just examples: feel free to adapt them to meet your requirements.

OUTPUT:

the output file.

Option -metrics_tab
-metrics_tab
-metrics_tab=OUTPUT_DIR

Create in the specified OUTPUT_DIR directory a textual, TAB-separated metrics.txt file containing the metrics computed during the analysis. The information is extracted from the database specified on the command line (see the -db option). In the specified OUTPUT_DIR directory two further files are created: metrics.ods and metrics.xlsm, they contain pivot tables that can be used for further elaboration. Finally, a README.txt file is created in the same directory, which contains instructions on the use of the other files.

At least one metrics service (e.g., MET.HIS.GOTO) should be enabled for the analysis used to generate the database, otherwise no directory will be created.

With Microsoft Excel open the file OUTPUT_DIR/metrics.xlsm making sure macros are enabled.

The Threshold sheet contains example thresholds for the metrics: make sure you set them according to your requirements. Then open the Pivot sheet tab, click on cell A1, containing File on a blue background, and select the generated OUTPUT file. Then click on cell B2 and select function, unit or program to show the values of the metrics. The metrics, in the Pivot sheet tab, that exceed the thresholds will be shown with a red background.

For LibreOffice Calc or, equivalently, OpenOffice.org Calc, the procedure is almost identical, the only difference is that the file to be open is OUTPUT_DIR/metrics.ods

Even if warned about the danger of macros, you must still enable macros. If asked whether to update the links to other files, accept. Then proceed as for Microsoft Excel.

Note that the pivot tables provided with ECLAIR are just examples: feel free to adapt them to match your requirements.

OUTPUT_DIR:

the top output directory.

Option -metrics_xslt
-metrics_xslt
-metrics_xslt=XSLT,OUTPUT

Output metrics info as filtered by the specified XSLT file.

XSLT:

the XSLT file used to process XML data.

OUTPUT:

the output file.

Option -overall_doc
-overall_doc
-overall_doc=OUTPUT

Output overall project summary in Microsoft Word Flat OPC XML format.

OUTPUT:

the output file.

Option -overall_html
-overall_html
-overall_html=OUTPUT

Output overall project summary in HTML format.

OUTPUT:

the output file.

Option -overall_json
-overall_json
-overall_json=OUTPUT

Output overall project summary in JSON format.

OUTPUT:

the output file.

Option -overall_odt
-overall_odt
-overall_odt=OUTPUT

Output overall project summary in OpenDocument Text Flat XML format.

OUTPUT:

the output file.

Option -overall_txt
-overall_txt
-overall_txt=OUTPUT

Output overall project summary in pure text format.

OUTPUT:

the output file.

Option -overall_xml
-overall_xml
-overall_xml=OUTPUT

Output overall project summary in XML format.

OUTPUT:

the output file.

Option -overall_xslt
-overall_xslt
-overall_xslt=XSLT,OUTPUT

Output overall project summary as filtered by the specified XSLT file.

XSLT:

the XSLT file used to process XML data.

OUTPUT:

the output file.

Option -primary_domain
-primary_domain
-primary_domain=DOMAIN

Specify the primary tag domain to be used to generate output.

DOMAIN:

the primary tag domain to be used.

Default:

-primary_domain=service

Option -protobuf_data
-protobuf_data
-protobuf_data=WHAT,OUTPUT[,OPTS][,FIELDS]

Output the tables provided in WHAT on the specified PROTOBUF output file OUTPUT_FILE using the options provided in OPTS and adding the field values FIELDS.

WHAT:

comma-separated list of tables to export.

OUTPUT:

the output file where the selected tables will be exported in Protocol Buffers (PROTOBUF) format.

OPTS:

comma-separated list of options to use to generate the output file.

FIELDS:

comma-separated list of field values to add to the output file.

Option -quiet
-quiet
-quiet[=STATE]

Set informative messages suppression state.

STATE:

whether the application is quiet. Accepted values are:

  • true: the application does not show informative messages;

  • false: the application show informative messages;

If omitted it is assumed to be true.

Default:

-quiet=false

Option -report_counts_7_Z0072
-report_counts_7_Z0072
-report_counts_7_Z0072=OUTPUT,SERVICES

Output the report counts in XLS format conforming to norm 7-Z0072 of FCA (formerly Fiat Auto).

OUTPUT:

the output file.

SERVICES:

a wildcard pattern matching the services whose report counts should be included.

If omitted it is assumed to be *.

Option -report_counts_doc
-report_counts_doc
-report_counts_doc=DOMAINS,OUTPUT

Output the report counts grouped by tag values for the specified domains in Microsoft Word Flat OPC XML format.

DOMAINS:

the tag domains used to group reports separated by +.

OUTPUT:

the output file.

Option -report_counts_html
-report_counts_html
-report_counts_html=DOMAINS,OUTPUT

Output the report counts grouped by tag values for the specified domains in HTML format.

DOMAINS:

the tag domains used to group reports separated by +.

OUTPUT:

the output file.

Option -report_counts_json
-report_counts_json
-report_counts_json=DOMAINS,OUTPUT

Output the report counts grouped by tag values for the specified domains in JSON format.

DOMAINS:

the tag domains used to group reports separated by +.

OUTPUT:

the output file.

Option -report_counts_odt
-report_counts_odt
-report_counts_odt=DOMAINS,OUTPUT

Output the report counts grouped by tag values for the specified domains in OpenDocument Text Flat XML format.

DOMAINS:

the tag domains used to group reports separated by +.

OUTPUT:

the output file.

Option -report_counts_txt
-report_counts_txt
-report_counts_txt=DOMAINS,OUTPUT

Output the report counts grouped by tag values for the specified domains in pure text format.

DOMAINS:

the tag domains used to group reports separated by +.

OUTPUT:

the output file.

Option -report_counts_xml
-report_counts_xml
-report_counts_xml=DOMAINS,OUTPUT

Output the report counts grouped by tag values for the specified domains in XML format.

DOMAINS:

the tag domains used to group reports separated by +.

OUTPUT:

the output file.

Option -report_counts_xslt
-report_counts_xslt
-report_counts_xslt=DOMAINS,XSLT,OUTPUT

Output the report counts grouped by tag values for the specified domains as filtered by the specified XSLT file.

DOMAINS:

the tag domains used to group reports separated by +.

XSLT:

the XSLT file used to process XML data.

OUTPUT:

the output file.

Option -reports_codeclimate
-reports_codeclimate
-reports_codeclimate=OUTPUT

Output untagged cautions and violations in Code Climate JSON format.

OUTPUT:

the output file.

Option -reports_csv
-reports_csv
-reports_csv=OUTPUT

Output report summary data in textual, TAB-separated form that is suitable for further elaboration with spreadsheet software.

The information is extracted from the database specified on the command line (see the -db option).

Suitable pivot tables are supplied with ECLAIR for Microsoft Excel, LibreOffice Calc, and OpenOffice.org Calc.

With Microsoft Excel, open the file PREFIX/eclair-VERSION/share/reports/tools/reports.xlsm making sure macros are enabled. If asked whether to update the links to other files, accept.

In the Pivot sheet tab, you can click on cell A1, containing File on a blue background, and select the generated OUTPUT file. In the same sheet tab you can click on Less detail or More detail to change detail level. The available details are:

  • the reports’ kind;

  • the service name and description;

  • eventual documentation provided to the reports;

  • the directory path of the file containing the reports;

  • the file that contains the reports;

  • the line of the report.

The last fixed column reports provides the the number of reports for the detailed constraints defined by the row.

Row 4 contains the details’ names; by clicking on any of names except the first, it is possible to swap the name with the previous one. Also, swapping columns will reorder the reports.

For LibreOffice Calc or, equivalently, OpenOffice.org Calc, the procedure is almost identical, the only difference being that the file to be opened is PREFIX/eclair-VERSION/share/reports/tools/reports.ods.

Versions of LibreOffice Calc prior to 7.2 are affected by bugs that are triggered by such reports.

Even if warned about the danger of macros, you must still enable macros. If asked whether to update the links to other files, accept. Then proceed as for Microsoft Excel.

Note that the pivot tables provided with ECLAIR are just examples: feel free to adapt them to match your requirements.

OUTPUT:

the output file.

Option -reports_jenkins
-reports_jenkins
-reports_jenkins=OUTPUT

Output untagged cautions and violations in Jenkins XML format.

OUTPUT:

the output file.

Option -reports_sarif
-reports_sarif
-reports_sarif=OUTPUT

Output untagged cautions and violations in SARIF JSON format.

OUTPUT:

the output file.

Option -reports_tab
-reports_tab
-reports_tab=OUTPUT_DIR

Create in the specified OUTPUT_DIR directory a textual, TAB-separated reports.txt file containing report summary data.

The information is extracted from the database specified on the command line (see the -db option).

In the specified OUTPUT_DIR directory two further files are created: these are reports.ods and reports.xlsm, they contain pivot tables that can be used for further elaboration.

Finally, README.txt file is created in the same directory, which contains instructions on the use of the other files.

With Microsoft Excel open the file OUTPUT_DIR/reports.xlsm making sure macros are enabled. If asked whether to update the links to other files, accept.

In the Pivot sheet tab, click on cell A1, containing File on a blue background, and select OUTPUT_DIR/reports.txt. Click on cell B1 to wrap the services descriptions. In the same sheet tab you can click on Less detail or More detail to change the detail level. The available details are:

  • the reports kind;

  • the service name and description;

  • eventual documentation provided to the reports;

  • the directory path of the file containing the reports;

  • the file that contains the reports;

  • the line of the report.

The last fixed column reports provides the the number of reports that have the details specified by the row.

Row 4 contains the details’ names; by clicking on any of names except the first, it is possible to swap the name with the previous one. Also, swapping columns will reorder the reports.

Clicking on the arrow, it is possible to choose between an ascending or descending sorting and create filters on it. E.g., clicking on the arrow in the tag cell is possible to show only the reports related to violations simply by unchecking caution and clicking OK.

For LibreOffice Calc or, equivalently, OpenOffice.org Calc, the procedure is almost identical, the only difference being that the file to be opened is OUTPUT_DIR/reports.ods.

Versions of LibreOffice Calc prior to 7.2 are affected by bugs that are triggered by such reports.

Note that the pivot tables provided with ECLAIR are just examples: feel free to adapt them to match your requirements.

OUTPUT_DIR:

the top output directory.

Option -reports1_doc
-reports1_doc
-reports1_doc=TAG,OUTPUT

Output the reports grouped by tag domains in Microsoft Word Flat OPC XML format. See -detailed_trial for license-specific information.

TAG:

the tag domain used to group reports.

OUTPUT:

the output file where @TAG@ is replaced by tag value.

Option -reports1_html
-reports1_html
-reports1_html=TAG,OUTPUT

Output the reports grouped by tag domains in HTML format. See -detailed_trial for license-specific information.

TAG:

the tag domain used to group reports.

OUTPUT:

the output file where @TAG@ is replaced by tag value.

Option -reports1_json
-reports1_json
-reports1_json=TAG,OUTPUT

Output the reports grouped by tag domains in JSON format. See -detailed_trial for license-specific information.

TAG:

the tag domain used to group reports.

OUTPUT:

the output file where @TAG@ is replaced by tag value.

Option -reports1_odt
-reports1_odt
-reports1_odt=TAG,OUTPUT

Output the reports grouped by tag domains in OpenDocument Text Flat XML format. See -detailed_trial for license-specific information.

TAG:

the tag domain used to group reports.

OUTPUT:

the output file where @TAG@ is replaced by tag value.

Option -reports1_txt
-reports1_txt
-reports1_txt=TAG,OUTPUT

Output the reports grouped by tag domains in pure text format. See -detailed_trial for license-specific information.

TAG:

the tag domain used to group reports.

OUTPUT:

the output file where @TAG@ is replaced by tag value.

Option -reports1_xml
-reports1_xml
-reports1_xml=TAG,OUTPUT

Output the reports grouped by tag domains in XML format. See -detailed_trial for license-specific information.

TAG:

the tag domain used to group reports.

OUTPUT:

the output file where @TAG@ is replaced by tag value.

Option -reports1_xslt
-reports1_xslt
-reports1_xslt=TAG,XSLT,OUTPUT

Output the reports grouped by tag domains as filtered by the specified XSLT file. See -detailed_trial for license-specific information.

TAG:

the tag domain used to group reports.

XSLT:

the XSLT file used to process XML data.

OUTPUT:

the output file where @TAG@ is replaced by tag value.

Option -reports2_doc
-reports2_doc
-reports2_doc=TAG1,TAG2,OUTPUT

Output the reports grouped by primary and secondary tag domains in Microsoft Word Flat OPC XML format. See -detailed_trial for license-specific information.

TAG1:

the primary tag domain to group reports.

TAG2:

the secondary tag domain to group reports.

OUTPUT:

the output file where @TAG@ is replaced by primary tag value.

Option -reports2_html
-reports2_html
-reports2_html=TAG1,TAG2,OUTPUT

Output the reports grouped by primary and secondary tag domains in HTML format. See -detailed_trial for license-specific information.

TAG1:

the primary tag domain to group reports.

TAG2:

the secondary tag domain to group reports.

OUTPUT:

the output file where @TAG@ is replaced by primary tag value.

Option -reports2_json
-reports2_json
-reports2_json=TAG1,TAG2,OUTPUT

Output the reports grouped by primary and secondary tag domains in JSON format. See -detailed_trial for license-specific information.

TAG1:

the primary tag domain to group reports.

TAG2:

the secondary tag domain to group reports.

OUTPUT:

the output file where @TAG@ is replaced by primary tag value.

Option -reports2_odt
-reports2_odt
-reports2_odt=TAG1,TAG2,OUTPUT

Output the reports grouped by primary and secondary tag domains in OpenDocument Text Flat XML format. See -detailed_trial for license-specific information.

TAG1:

the primary tag domain to group reports.

TAG2:

the secondary tag domain to group reports.

OUTPUT:

the output file where @TAG@ is replaced by primary tag value.

Option -reports2_txt
-reports2_txt
-reports2_txt=TAG1,TAG2,OUTPUT

Output the reports grouped by primary and secondary tag domains in pure text format. See -detailed_trial for license-specific information.

TAG1:

the primary tag domain to group reports.

TAG2:

the secondary tag domain to group reports.

OUTPUT:

the output file where @TAG@ is replaced by primary tag value.

Option -reports2_xml
-reports2_xml
-reports2_xml=TAG1,TAG2,OUTPUT

Output the reports grouped by primary and secondary tag domains in XML format. See -detailed_trial for license-specific information.

TAG1:

the primary tag domain to group reports.

TAG2:

the secondary tag domain to group reports.

OUTPUT:

the output file where @TAG@ is replaced by primary tag value.

Option -reports2_xslt
-reports2_xslt
-reports2_xslt=TAG1,TAG2,XSLT,OUTPUT

Output the reports grouped by primary and secondary tag domains as filtered by the specified XSLT file. See -detailed_trial for license-specific information.

TAG1:

the primary tag domain to group reports.

TAG2:

the secondary tag domain to group reports.

XSLT:

the XSLT file used to process XML data.

OUTPUT:

the output file where @TAG@ is replaced by primary tag value.

Option -save
-save
-save=FILE_ECB_XZ

Saves binary output frames as a xz-compressed file

Example of usage:

eclair_report ECB_OUTPUT_DIR/FRAME.*.ecb -save=OUTPUT_PATH/FRAMES.ecb.xz
FILE_ECB_XZ:

the output file or /dev/stdout for the standard output.

Option -save_sel
-save_sel
-save_sel

Make current selection persistent saving it in the database.

Option -secondary_domain
-secondary_domain
-secondary_domain=DOMAIN

Specify the secondary tag domain to be used to generate output.

DOMAIN:

the secondary tag domain to be used.

Default:

-secondary_domain=first_file

Option -sel
-sel
-sel=NAME

Set the report filter for the current selection.

NAME:

report filter name.

Option -sel_tag_glob
-sel_tag_glob
-sel_tag_glob=SEL_NAME,DOM,TAGS

Only the reports tagged with one of the provided reports tags will be included in the produced artifacts.

Example of usage:

# Create the diff files and tag the databases:
eclair_report -diff_full_txt=PROJECT.old.ecd,PROJECT.new.ecd

# create an artifact containing only the new violations:
eclair_report -db=PROJECT.new.ecd -sel_tag_glob=new,diff,missing <REPORT_GEN_CMD>

# create an artifact containing only the fixed violations:
eclair_report -db=PROJECT.old.ecd -sel_tag_glob=new,diff,missing <REPORT_GEN_CMD>

Where <REPORT_GEN_CMD> are the options to generate the desired artifact.

If you do not want to create any artifact, but simply navigate the resulting selection use:

eclair_report -db=PROJECT.old.ecd -sel_tag_glob=new,diff,missing -browser -server
SEL_NAME:

the name of the selection. This information will be reported in the produced outputs.

DOM:

the domain of the selection.

TAGS:

a wildcard pattern matching the tags to select. The Unix file globbing syntax can be used.

Option -server
-server
-server[=ACTION]

Perform action ACTION on the server.

ACTION

Accepted values are:

  • start: start the server;

  • stop: stop the server;

  • restart: stop and restart the server;

  • changing: lock the server as database is changing;

  • changed: unlock the server as changes are complete;

If omitted it is assumed to be start.

Option -server_area_run_command
-server_area_run_command
-server_area_run_command=COMMAND,ARG,...

Set the program handling user Run actions.

COMMAND:

the executable called to handle the Run action.

ARG:

argument for the command.

Option -server_ext
-server_ext
-server_ext=PATHNAME[,PROGRAM],ARGS,...

Set the socket (named pipe under Windows) file to be used to forward URIs that begins with /ext/ and optionally the server to launch.

PATHNAME:

the pathname of socket/named pipe file.

PROGRAM:

the server program name.

ARG:

the arguments to be passed to server program.

Option -server_root
-server_root
-server_root=ROOT

Specify the directory to be used as server root for accessing database files.

ROOT:

the root directory to be used.

Default:

-server_root=.

Option -services_doc
-services_doc
-services_doc=OUTPUT

Output info about enabled services in Microsoft Word Flat OPC XML format.

OUTPUT:

the output file.

Option -services_html
-services_html
-services_html=OUTPUT

Output info about enabled services in HTML format.

OUTPUT:

the output file.

Option -services_json
-services_json
-services_json=OUTPUT

Output info about enabled services in JSON format.

OUTPUT:

the output file.

Option -services_odt
-services_odt
-services_odt=OUTPUT

Output info about enabled services in OpenDocument Text Flat XML format.

OUTPUT:

the output file.

Option -services_txt
-services_txt
-services_txt=OUTPUT

Output info about enabled services in pure text format.

OUTPUT:

the output file.

Option -services_xml
-services_xml
-services_xml=OUTPUT

Output info about enabled services in XML format.

OUTPUT:

the output file.

Option -services_xslt
-services_xslt
-services_xslt=XSLT,OUTPUT

Output info about enabled services as filtered by the specified XSLT file.

XSLT:

the XSLT file used to process XML data.

OUTPUT:

the output file.

Option -sources_html
-sources_html
-sources_html=OUTPUT

Output sources with related reports in HTML format. See -detailed_trial for license-specific information.

OUTPUT:

the output file where @TAG@ is replaced by tag associated to file name.

Option -sources_xml
-sources_xml
-sources_xml=OUTPUT

Output sources with related reports in XML format. See -detailed_trial for license-specific information.

OUTPUT:

the output file where @TAG@ is replaced by tag associated to file name.

Option -sources_xslt
-sources_xslt
-sources_xslt=XSLT,OUTPUT

Output sources with related reports as filtered by the specified XSLT file. See -detailed_trial for license-specific information.

XSLT:

the XSLT file used to process XML data.

OUTPUT:

the output file where @TAG@ is replaced by tag associated to file name.

Option -ssl
-ssl
-ssl[=STATE]

Set SSL mode.

STATE:

whether eclair_report should use only HTTPS protocol. Accepted values are:

  • true: eclair_report use only HTTPS protocol;

  • false: eclair_report use HTTP protocol if available, otherwise HTTPS;

If omitted it is assumed to be true.

Default:

-ssl=false

Option -ssl_certificate
-ssl_certificate
-ssl_certificate=FILE

Set SSL certificate to be used for HTTPS.

FILE:

certificate file path.

Option -stripped_doc
-stripped_doc
-stripped_doc=OUTPUT_DIR

Output a shorter version of the project report in Microsoft Word Flat OPC XML format. The report with front and back covers is written to book.doc, whereas the version without covers is written to index.doc. See -detailed_trial for license-specific information.

OUTPUT_DIR:

the top output directory.

Option -stripped_odt
-stripped_odt
-stripped_odt=OUTPUT_DIR

Output a shorter version of the project report in OpenDocument Text Flat XML format. The report with front and back covers is written to book.odt, whereas the version without covers is written to index.odt. See -detailed_trial for license-specific information.

OUTPUT_DIR:

the top output directory.

Option -summary_doc
-summary_doc
-summary_doc=OUTPUT_DIR

Output the summarized project report in Microsoft Word Flat OPC XML format. The report with front and back covers is written in book.doc, whereas the version without covers is written in index.doc.

OUTPUT_DIR:

the top output directory.

Option -summary_html
-summary_html
-summary_html=OUTPUT_DIR

Output the summarized project report in HTML format. Main file is index.html.

OUTPUT_DIR:

the top output directory.

Option -summary_json
-summary_json
-summary_json=OUTPUT_DIR

Output the summarized project report in JSON format.

OUTPUT_DIR:

the top output directory.

Option -summary_odt
-summary_odt
-summary_odt=OUTPUT_DIR

Output the summarized project report in OpenDocument Text Flat XML format. The report with front and back covers is written to book.odt, while the version without covers is written to index.odt.

OUTPUT_DIR:

the top output directory.

Option -summary_txt
-summary_txt
-summary_txt=OUTPUT_DIR

Output the summarized project report in pure text format.

OUTPUT_DIR:

the top output directory.

Option -summary_xml
-summary_xml
-summary_xml=OUTPUT_DIR

Output the summarized project report in XML format.

OUTPUT_DIR:

the top output directory.

Option -verbose
-verbose
-verbose[=STATE]

Set verbosity state.

STATE:

whether the application messages are verbose. Accepted values are:

  • true: messages are verbose;

  • false: messages are not verbose;

If omitted it is assumed to be true.

Default:

-verbose=false

Option -version
-version
-version

Print version number.

Option -xml_data
-xml_data
-xml_data=WHAT,OUTPUT[,OPTS][,FIELDS]

Output the tables provided in WHAT on the specified XML output file OUTPUT_FILE using the options provided in OPTS and adding the field values FIELDS.

WHAT:

comma-separated list of tables to export.

OUTPUT:

the output file where the selected tables will be exported in XML format.

OPTS:

comma-separated list of options to use to generate the output file.

FIELDS:

comma-separated list of field values to add to the output file.

Option -xslt_data
-xslt_data
-xslt_data=WHAT,OUTPUT[,OPTS][,FIELDS]

Output the tables provided in WHAT on the specified XSLT output file OUTPUT_FILE using the options provided in OPTS and adding the field values FIELDS.

WHAT:

comma-separated list of tables to export.

OUTPUT:

the output file where the selected tables will be exported in XSLT format.

OPTS:

comma-separated list of options to use to generate the output file.

FIELDS:

comma-separated list of field values to add to the output file.

Option -yaml_data
-yaml_data
-yaml_data=WHAT,OUTPUT[,OPTS][,FIELDS]

Output the tables provided in WHAT on the specified YAML output file OUTPUT_FILE using the options provided in OPTS and adding the field values FIELDS.

WHAT:

comma-separated list of tables to export.

OUTPUT:

the output file where the selected tables will be exported in YAML format.

OPTS:

comma-separated list of options to use to generate the output file.

FIELDS:

comma-separated list of field values to add to the output file.

Incorporating Third-party Reports into an ECLAIR Database

A project using ECLAIR as a static analyzer may want to incorporate, as part of its quality metrics, the findings of other tools (e.g., compiler diagnostics or test coverage information). To give users a uniform report browsing experience, the B.DIAGNOSTICS, B.GCOV and B.LLVM_COV services provide a way to convert and import textual reports from toolchain components or external tools directly into an ECLAIR database.

Parsing Diagnostic Messages with B.DIAGNOSTICS

The B.DIAGNOSTICS service parses textual output from a supported third-party tool such as make, gcc or clang. The textual output can be supplied via one or more files, or by intercepting the tool’s standard output (and standard error, if desired).

Intercepting a Toolchain Component’s Standard Output

Consider the following example file diag.c:

int main(int argc, char **argv) {
  enum e { A, B = -1, C};
  enum e e1 = 0x10000;
  e1 + argv[1][0];
  return 0;
}

Compiling this program with the following command line produces several diagnostics:

clang-18 -Weverything diag.c
diag.c:2:12: warning: element 'A' has been implicitly assigned 0 which another element has been assigned [-Wduplicate-enum]
    2 |   enum e { A, B = -1, C};
      |            ^
diag.c:2:23: note: element 'C' also has value 0
    2 |   enum e { A, B = -1, C};
      |                       ^
diag.c:3:15: warning: integer constant not in range of enumerated type 'enum e' [-Wassign-enum]
    3 |   enum e e1 = 0x10000;
      |               ^
diag.c:1:14: warning: unused parameter 'argc' [-Wunused-parameter]
    1 | int main(int argc, char **argv) {
      |              ^
diag.c:4:6: warning: expression result unused [-Wunused-value]
    4 |   e1 + argv[1][0];
      |   ~~ ^ ~~~~~~~~~~
diag.c:4:8: warning: unsafe buffer access [-Wunsafe-buffer-usage]
    4 |   e1 + argv[1][0];
      |        ^~~~
5 warnings generated.

This output can be intercepted and parsed by ECLAIR with the configuration:

-enable=B.DIAGNOSTICS
-config=B.DIAGNOSTICS,sel_frames='kind(command)&&tool(command(^clang-18.*$))'

The sel_frames configuration above restricts parsing to command frames whose tool invocation matches the regular expression ^clang-18.*$. This avoids attempting to parse unrelated output produced by other tools executed during the build.

Note that ECLAIR intercept the tools standard output only when they are matched by the EXTRA_ALIASES environment variable, for example:

export EXTRA_ALIASES="^.*llvm(-\d+)?$|^.*clang(-\d+)?$"
set EXTRA_ALIASES=clang-18

For more information on the EXTRA_ALIASES environment variable, refer to the Tool Specification Variables section.

Using Textual Output from a File

Assume that the file diag.log is generated by the build procedure that is being analyzed with ECLAIR. It can be loaded and parsed by ECLAIR with the configuration:

-enable=B.DIAGNOSTICS
-config=B.DIAGNOSTICS,input_files="diag.log"

Parsing Coverage Output with B.LLVM_COV or B.GCOV

The B.LLVM_COV and B.GCOV services process the output produced by the llvm-cov and gcov tools, respectively. Like B.DIAGNOSTICS, they accept input either from files or by intercepting the tools’ standard output (and standard error, if desired).

Parsing llvm-cov Output

Suppose you have a build script that you are collecting MC/DC coverage information produced by llvm-cov on a file main.c in an output file mcdc.txt:

 clang-20 \
   -fprofile-instr-generate \
   -fcoverage-mapping \
   -fcoverage-mcdc \
   "-fcoverage-compilation-dir=$(pwd)" \
   -O0 \
   main.c \
   -o abs.out

 LLVM_PROFILE_FILE=default.profraw ./abs.out

 llvm-profdata-20 merge -sparse default.profraw -o a.profdata

 # generate report summary
 llvm-cov-20 report \
   abs.out \
   -instr-profile=a.profdata \
   -compilation-dir=. \
   --show-mcdc-summary \
   > mcdc.txt

 # add source file path
echo "$(realpath main.c):" >> mcdc.txt

 # generate detailed report
 llvm-cov-20 show \
   abs.out \
   -instr-profile=a.profdata \
   --show-branches=count \
   --show-expansions \
   --show-mcdc-summary \
   --show-mcdc \
   --sources main.c \
   >> mcdc.txt

Here main.c is the source file to be analyzed:

int f(int x, int y) {
  if (x < 0 && y > 0) {
   return -x + y;
 } else {
   return x + y;
 }
}

int main(int argc, char **argv) {
  (void)f(-1, 2);
  return 0;
}

The llvm-cov-20 report command is optional. However, realpath main.c >> mcdc.txt is necessary if the llvm-cov show output would otherwise contain only one file (in which case the file path is not printed). For more information, refer to the B.LLVM_COV service documentation.

The output file mcdc.txt can be parsed by ECLAIR with the following

-enable=B.LLVM_COV
-config=B.LLVM_COV,input_files="mcdc.txt"

Similarly, llvm-cov standard output can be captured and parsed by ECLAIR using a suitable sel_frames. For example:

-enable=B.LLVM_COV
-config=B.LLVM_COV,sel_frames='kind(command)&&tool(command(^llvm-cov(-\\d+)? report.*$))'

This restricts parsing to frames produced by an llvm-cov report command.

Parsing gcov Output

The B.GCOV service works similarly to service B.LLVM_COV, but parses textual output from the gcov tool. For example, assuming that main.c is the same as above, the following commands generate a gcov.txt file:

OPTS=(
  -g
  -fprofile-arcs
  -ftest-coverage
  -fcondition-coverage
  -O0
)

gcc-14 -g "${OPTS[@]}" -c main.c -o main.o
gcc-14 -g "${OPTS[@]}" main.o -o abs.out

./abs.out

# Generate coverage report
gcov-14 -b -t main.c > gcov.txt

Like B.LLVM_COV, the output file gcov.txt can be parsed by ECLAIR with:

-enable=B.GCOV
-config=B.GCOV,input_files="gcov.txt"
Configurable Thresholds

Both B.LLVM_COV and B.GCOV support configurable thresholds that control the severity of some reports based on coverage percentages.

The predefined thresholds are documented in the grammar_globals option configuration for services B.LLVM_COV and B.GCOV. These settings can be changed individually to

-config=B.GCOV,grammar_globals+={executed_blocks_threshold,90}

This sets the threshold for the executed_blocks metric to 90%; functions with less than 90% executed blocks will then be reported as violations.

Tagging Imported Reports

The B.DIAGNOSTICS, B.LLVM_COV and B.GCOV services support report tagging as described in Tagging/Hiding Reports. This might be required, for example, to classify and justify code coverage gaps.

One way to tag reports is to use the -reports global option, for example:

-doc="Thread functions are designed to run indefinitely and never return"
-config=B.GCOV,reports+={deliberate,"any_area(all_loc(^(.*/)?main\\.c)&&^.*?function .*?_thread_fn called \\d+ returned 0.*$)"}

Which will tag as “deliberate” all reports from the file main.c which mention a function whose name ends with _thread_fn and never returns.

Another possibility is to mark and justify deviations locally, which is covered in Mark Locally and Justify. For example, in the main.c file above, you could add a comment based tagging like the following:

int f(int x, int y) {
  // -E> deliberate B.LLVM_COV 1 `y' is always > 0 during testing
  if (x < 0 && y > 0) {
   return -x + y;
 } else {
   return x + y;
 }
}

int main(int argc, char **argv) {
  (void)f(-1, 2);
  return 0;
}

Migrating from eclair_import

If you previously used eclair_import, use the services as follows:

  • Diagnostics import: enable service B.DIAGNOSTICS instead of invoking eclair_import --parser=GCC.

  • llvm-cov coverage: enable service B.LLVM_COV (was --parser=LLVM_COV).

  • gcov coverage: enable service B.GCOV.

Configuration

The obvious counterpart to the extreme configurability of ECLAIR is that its configuration might be quite complex. However, many users are simply given an ECLAIR configuration file in ECL format and they only need to know how to give it to ECLAIR: such users can skip this chapter altogether. Only a minority of users will need to know more about ECLAIR options and how to express them in ECL. These are the users who are involved in the writing or modification of scripts and advanced configurations: they will find all they need in this chapter and in Sections Global Options and Generic Service Options.

Common Configuration Concepts

This section describes some common concepts used when setting the ECLAIR configuration options for analyzing a project.

String Interpolation

String interpolation allows the composition of strings from string literals and ECL expressions. The juxtaposition of a string literal (that is, a possibly empty sequence of characters enclosed in double quotes) followed by a sequence of expressions and string literals denotes string interpolation. Note that every string interpolation must be introduced by a string literal, possibly the empty string "". Note also that the sequence cannot contain two adjacent expressions: for example, two adjacent variable names would be interpreted as the name of a single variable; again, the empty string can be used to separate expressions in the sequence.

An expression can be any ECL expression: this allows for full generality. However, for most users it is sufficient to know that expressions include the following predefined variables:

An example of string interpolation is

""install_dir"/share/dict/en_US"

which is expanded to

PREFIX/eclair-VERSION/share/dict/en_US

Note the empty string occurring as the first element of the juxtaposition in order to introduce string interpolation.

An expression can also be a function invocation, such as:

  • join_paths(PATH,...) takes one or more path components (i.e., file or directory names) and joins them by interposing a system-dependent delimiting character (the slash / or the backslash \);

  • getenv(NAME) gives the value of environment variable named NAME;

  • windows_wildcard_regex(WINDOWS_PATH) takes a Windows path, possibly with wildcards, and turns it into a corresponding regular expression performing all the necessary quoting.

For instance, the example above can be rewritten in a more portable way as follows:

""join_paths(install_dir,"share","dict","en_US")

or, assuming a suitable definition for the DICTIONARY environment variable,

""join_paths(install_dir,"share","dict",getenv("DICTIONARY"))

Raw String Literals

A raw string literal is a string whose content is taken verbatim, with no escape processing. This is particularly convenient when the string contains backslashes or other characters that would otherwise need to be escaped, for example Windows paths or regular expressions.

A raw string literal is delimited by one or more backtick characters. The opening delimiter is one or more consecutive backticks; the literal ends at the first occurrence of exactly the same number of consecutive backticks. This means that a raw string containing backticks can always be written by choosing a longer delimiter.

Examples:

-eval_file=`C:\Users\user\config.ecl`
-enable=`^MC3\.D.*$`
print(```contains ` one and `` two backticks```)

```
this is a raw string literal used as comment block
```

The first example produces the string C:\Users\user\config.ecl. The second produces ^MC3\.D.*$. The third produces the string:

contains ` one and `` two backticks

Because no escape processing takes place inside a raw string literal, the sequences \\, \n, \t, etc. are all passed through unchanged. When escape sequences are needed, use a regular double-quoted or single-quoted string literal instead (see String Interpolation).

A raw string literal can span multiple lines; all characters between the opening and closing delimiters, including newlines, are included in the resulting string verbatim.

Note

In ECL, a string literal is a valid expression almost everywhere an expression is allowed. This rule is why literal fragments (like the example above) are accepted and can be used as comment-like blocks.

Booleans

Whenever eclair_env requires a Boolean parameter, the following can be specified:

  • false

  • true

Matchers

Several commonly-used (often global) configuration options use matchers. A matcher defines a constraint on the elements specified by the configuration option; if the constraint on the element holds, the matcher is said to match the element.

A matcher is an expression formed from atomic selectors with the usual Boolean operators !, ||, && together with the addition operators + and -. The atomic selectors include

  • parenthesized expressions,

  • named matchers: an element matches the identifier if it matches the associated matcher expression;

  • any(): any element matches,

  • none(): no element matches

  • built-in selectors that depend on the specific matcher; the syntax and constraints checked by such a selector is defined by the configuration option for the matcher.

An example of a matcher is the global configure option entity_selector defined in Global Options.

Short Circuit Taggers

Several commonly-used configuration options are short circuit taggers with values in the form of an ordered sequence of short-circuit clauses.

In its simplest form, each short-circuit clause is a pair consisting of a tag and some conditions; the tag takes one of a set of values defined by the configure option and the conditions takes a value or values that define a condition COND on the data being examined. Note that a set or sequence of conditions is interpreted as a conjunction of the conditions they specify. If the data being examined by ECLAIR satisfies COND, then we say that the short-circuit clause matches the data.

The relevant data being examined by ECLAIR is checked against the conditions of each short-circuit clause in the tagger (in the sequential order of the clauses) until a match is found. The tag in the first short-circuit clause that matches the data is then assigned to the data. When there is no matching short-circuit condition, then, the data is given a default tag (defined by the configure option).

More generally, a short circuit clause may include additional arguments that are not part of the conditions but may affect the report output. A common use for such an argument is for the user to specify a message to be included in the report or a justification for hiding a report.

An example of a short circuit tagger is the global configure option source_files defined in Global Options. The values for tag are hide and show, with the default tag being show.

Output Sinks

Whenever eclair_env requires the specification of an output sink, the specification can be prefixed by:

  • >>, in which case the rest of the atom is interpreted as a filename to be opened in append mode;

  • >, in which case the rest of the atom is interpreted as a filename to be opened in truncate mode (that is, if the file already exists, its contents is overwritten);

  • |, in which case the rest of the atom is interpreted as a command to which the output should be piped.

If such a prefix is not present, then the entire atom is interpreted as a filename to be opened in a use-dependent mode. The mode is append (i.e., the file is created if it does not exists and writing takes place at the end of the file) for the output of diagnostics and of report data files that are meant to be constructed incrementally. The mode is truncate (i.e., the file is created if it does not exists, it is truncated to zero length if it does exist, and writing takes place at the beginning of the file) in all other cases. The defaults have been chosen so that the vast majority of users will never need to use the >> and > specifiers.

Regular Expressions

A regular expression (shortened as regex or regexp) is a sequence of characters that specifies a search pattern in text.

See Syntax quick-reference summary for the precise syntax details.

Note that when a regular expression is written inside a string literal there are two levels of quoting: one introduced by the string literal and the other one by the regular expression.

For example, consider the configuration:

-call_properties+={"^foo\\(.*$",{noreturn}}

The string literal ^foo\\(.*$ is expanded first, replacing the \\ by \, so that the expansion of the regular expression will interpret the \( as a verbatim ( and not as a group begin.

To avoid this double-escaping, a raw string literal can be used instead, since its content is never processed for escape sequences:

-call_properties+={`^foo\(.*$`,{noreturn}}

Documenting Configurations

We first describe some special options for documenting the configuration itself.

Option -doc

-doc

-doc=DOC...

where DOC is a comment that explains the next line of the configuration.

Option -doc_begin

-doc_begin

-doc_begin=DOC...

where DOC is a comment that explains the block of configuration lines that follows.

Option -doc_end

-doc_end

terminates a documented block of configuration lines.

Global Options

We present some useful global configuration options that are service-independent but project specific. For service-dependent options that can be used with any service see Generic Service Options.

A template for the configuration of global options is provided in

PREFIX/eclair-VERSION/share/config/templates/globals.ecl

Configuration

Option -load_config
-load_config
-load_config=INPUT

Load the specified compiled configuration file.

The input file must be obtained using the -save_config global option.

The option loads all the configurations contained in the input file similarly to what -eval_file does for an ECL file.

The only difference is that the latter needs to recompile the ECL file at each COMMAND frame causing a significant overhead. It is suggested to use this option in projects with many COMMAND frames, and/or that use large ECL files.

Example of usage:

eclair -record_config -eval_file=configuration.ecl -save_config=configuration.cecl
eclair_env -load_config=configuration.cecl -- ...
INPUT:

a compiled configuration file.

Option -record_config
-record_config
-record_config

Mark the beginning of configuration commands that should be saved by -save_config.

Only the configuration commands will be placed in the output file, other commands will be ignored.

Example of usage:

eclair -record_config -eval_file=configuration.ecl -save_config=configuration.cecl
eclair_env -load_config=configuration.cecl -- ...
Option -save_config
-save_config
-save_config=OUTPUT

Save the compiled output of configuration commands received since the last -record_configin the specified file.

The obtained output file can be used later with the -load_config global option.

Only the configuration commands will be placed in the output file, other commands will be ignored.

Example of usage:

eclair -record_config -eval_file=configuration.ecl -save_config=configuration.cecl
eclair_env -load_config=configuration.cecl -- ...
OUTPUT:

the output file.

Option -variant
-variant
-variant=FRAME_MATCHER

Configuration variants introducer.

FRAME_MATCHER:

a -frame_selector identifier or a matcher expression used to select the frames where to use following configurations.

Default:

-variant=""

Actions

Option -config_file
-config_file
-config_file=FILE_NAME

Loads the given configuration file.

Unlike -eval_file, -config_file compiles the configuration files only once during the CLEAN frame and then the compiled version is reused in the remaining frames.

-eval_file re-compiles the configuration files at each frame.

This command can be used only once, hence the specified file should use -eval_file to include all the needed configuration files.

FILE_NAME:

configuration file to be loaded, usually including the full absolute path (omitting the path or providing a relative path is not recommended, as the file will then be looked for in a directory relative to the current directory of the build process).

Option -eval_file
-eval_file
-eval_file=FILE_NAME,...

Loads the given configuration files in left-to-right order.

The configuration’s content is an ordered list of configurations files to be loaded.

FILE_NAME:

configuration file to be loaded, usually including the full absolute path (omitting the path or providing a relative path is not recommended, as the file will then be looked for in a directory relative to the current directory of the build process).

Option -eval_string
-eval_string
-eval_string=ACTION,...

Commands to be executed.

The configuration’s content is an ordered list of commands to be executed.

ACTION:

the command to be executed.

Option -post
-post
-post=ACTION,...

Commands to be executed after toolchain detection.

The configuration’s content is an ordered list of commands to be executed after toolchain detection.

ACTION:

the command to be executed.

Project information

Option -project_name
-project_name
-project_name=NAME

Project name.

NAME:

the name of the project.

Default:

-project_name=unnamed
Option -project_root
-project_root
-project_root=DIRECTORY

Project root directory.

DIRECTORY:

the top source directory of the project.

Default:

-project_root=/dev/null
Option -source_files
-source_files
-source_files={TAG, FILE_MATCHER},...

Specifies the source files to be excluded from the analysis.

The configuration’s content is a short-circuit sequence specifying the sources files for which the top level declarations and tokens should not be analyzed.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

FILE_MATCHER:

a -file_tag identifier or a matcher expression used to select the files.

Analysis

Option -frame_override
-frame_override
-frame_override=OVERRIDE

If enabled, data collected from analysis for the same target, the same command line and the same current working directory will replace previous data.

OVERRIDE:

specify if new analysis frame should override previous similar analysis frame. Accepted values are:

  • false: old analysis data is not overridden;

  • true: old analysis data is discarded;

Default:

-frame_override=false
Option -frames
-frames
-frames={TAG, FRAME_MATCHER},...

Specifies the analysis frames to be excluded from the analysis.

The configuration’s content is a short-circuit sequence specifying the frames that should not be analyzed.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

FRAME_MATCHER:

a -frame_selector identifier or a matcher expression used to select the frames.

Launching the compiler

Option -compile
-compile
-compile=WHAT

Specify which source should be compiled.

WHAT:

the source format. Accepted values are:

  • original: compile the original source;

  • nothing: don’t call the target compiler;

Default:

-compile=original

Remapping

Option -remap_file
-remap_file
-remap_file={FROM, TO},...

This will map a file name into another file name in the ECLAIR parser.

The configuration’s content is a set of file redirections.

FROM:

the file name to be remapped.

TO:

the target file name.

Option -remap_include
-remap_include
-remap_include={FROM, TO},...

This will map an include name into another include name in the ECLAIR parser.

The configuration’s content is a set of include redirections.

FROM:

the include name to be remapped.

TO:

the target include name.

Option -remap_rtag
-remap_rtag
-remap_rtag={FROM, TO},...

This will map a report tag into other report tags. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden.

The configuration’s content is a set of rtag mappings.

FROM:

the rtag to be remapped.

TO:

a possibly empty sequence of rtags separated by +.

Default:

-remap_rtag={}

Idioms

Option -loop_idioms
-loop_idioms
-loop_idioms={STMT, LOOP_MATCHER},...

Specify the loop idioms.

The configuration’s content is a set of loop kinds with condition matcher.

STMT:

for, do or while statement. Accepted values are:

  • for_stmt: for statement;

  • do_stmt: do statement;

  • while_stmt: while statement;

LOOP_MATCHER:

a matcher expression for the loop conditions. Accepted forms are:

  • [+]AND_MATCHER: the loop matches AND_MATCHER

  • -AND_MATCHER: the loop does not match AND_MATCHER

  • [+]AND_MATCHER||LOOP_MATCHER: either the loop matches AND_MATCHER or it matches LOOP_MATCHER

  • -AND_MATCHER||LOOP_MATCHER: the loop does not match AND_MATCHER but does match LOOP_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the loop matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the loop matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (LOOP_MATCHER): the loop matches LOOP_MATCHER

  • !BASIC_MATCHER: the loop does not match BASIC_MATCHER

  • any(): any loop matches

  • none(): no loop matches

  • macro(): the loop is an expanded macro

  • empty_head(): the loop is a for statement with an empty head

  • literal(NUM): the loop condition must be the integer NUM, which is 0 or 1

  • constant(BOOL): the loop condition must be the Boolean BOOL, which is true or false

  • eval(NUM): the loop condition expression must evaluate to NUM, which is 0 or 1

  • type(boolean): the loop condition expression must have a Boolean type not considering implicit conversions

Default:

-loop_idioms={do_stmt, "macro()&&constant(false)"}

Diagnostics output

ECLAIR diagnostics output can be set in two different ways: the preferred one is via the ECLAIR_DIAGNOSTICS_OUTPUT environment variable; this has the advantage that the setting is active even before the command line is parsed and before any ECL file has been read. The following global setting provides an alternative that can be used when, at some stage, the diagnostics output is to be diverted to a different output sink.

Option -diagnostics_output
-diagnostics_output
-diagnostics_output=DIAG_OUTPUT

Specify the output file for the diagnostics.

DIAG_OUTPUT:

the file name for the diagnostics output.

Default:

-diagnostics_output=/dev/stderr

Extra output

Option -print
-print
-print=PRINT

Specify extra text to be printed.

PRINT:

text to be printed.

Option -verbose
-verbose
-verbose=LEVEL

Verbosity level.

LEVEL:

the level of verbosity. Accepted values are:

  • false: less verbose;

  • true: more verbose;

Default:

-verbose=false
Option -version
-version
-version

Print version number.

Report control

Option -entity_declarations
-entity_declarations
-entity_declarations={TAG, DECL_MATCHER},...

Select declarations to be used for entity presentation.

The configuration’s content is a short-circuit sequence specifying which declaration to choose when presenting an entity.

TAG:

a tag with values hate and show. Accepted values are:

  • hate: avoid when possible if it matches the associated conditions;

  • show: show if it matches the associated conditions;

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option -fmt
-fmt
-fmt={FMT, TPL_FMT, CONTENT},...

Specify the formats for the messages.

The configuration’s content is a collection of named message formats.

FMT:

format identifier.

TPL_FMT:

template identifier.

CONTENT:

format content string. Accepted forms are:

  • PARTPARTS: non empty parts

  • : empty parts

PART

accepted forms are:

  • %{EXPR}: result of EXPR

  • TEXT: text TEXT

EXPR

accepted forms are:

  • 'TEXT': text TEXT

  • n(PARAM): value of parameter PARAM

  • q(PARAM): quoted value of parameter PARAM

  • seq(EXPR,SEP): value of items in list EXPR separated by SEP

  • cond(EXPR_COND,EXPR_DEFAULT,CASES): value of EXPR_COND is tested against CASES, if nothing matches EXPR_DEFAULT is used

  • FMT(OPT_ARGS): fmt FMT is called

  • FMT(EXPROPT_COMMA_SEPOPT_COMMA_ARGS): fmt FMT is called on EXPR

  • ifmt(EXPR_FMT,IDOPT_COMMA_ARGS): fmt specified by EXPR_FMT (whose template is ID) is called

  • ifmte(EXPR_FMT,EXPR_VALUEOPT_COMMA_ARGS): fmt specified by EXPR_FMT is called on EXPR_VALUE

  • ifmts(EXPR_FMT,EXPR_SEQ,EXPR_SEPOPT_COMMA_ARGS): fmt specified by EXPR_FMT is called on sequence EXPR_SEQ using separator EXPR_SEP

OPT_ARGS

accepted forms are:

  • ID:EXPROPT_COMMA_ARGS: optional comma separated EXPR sequence

  • : no more expressions

OPT_COMMA_ARGS

accepted forms are:

  • ,OPT_ARGS: optional comma separated OPT_ARGS sequence

  • : no more args

OPT_COMMA_SEP

accepted forms are:

  • ,EXPR: comma followed by EXPR

  • : no more expressions

Option -ignored_comments
-ignored_comments
-ignored_comments=COMMENT_MATCHER,...

Specify the comments that should be ignored.

The configuration’s content is a list of comment matchers.

COMMENT_MATCHER:

a -comment_selector identifier or a matcher expression used to select the comments.

Default:

-ignored_comments=__eclair_rtag_comments
Option -program_presentation_style
-program_presentation_style
-program_presentation_style=STYLE

Specify the output style for report program reference.

STYLE:

sets the output style; the default is to include the full linker command. Accepted values are:

  • include_full_command: file name with full linker command;

  • file_name_only: main file name without the full linker command;

Default:

-program_presentation_style=file_name_only
Option -reports
-reports
-reports={TAGS, REPORT_MATCHER},...

Specifies the report tags for reports.

The configuration’s content is a list of clauses specifying the reports and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

REPORT_MATCHER:

a -report_selector identifier or a matcher expression used to select the reports.

Option -rtag
-rtag
-rtag={NAME, TITLE, SORT_KEY},...

Provide additional information for a report tag.

The configuration’s content is list or report tag information.

NAME:

the domain and name of the tag, separated by a colon.

TITLE:

a title associated to this tag; it is presented to the user when this tag is selected.

SORT_KEY:

sort key for the tag.

Default:

-rtag={}
Option -tool_name_style
-tool_name_style
-tool_name_style=STYLE

Specify the output style for the tool used.

STYLE:

sets the tool name style; the default is the full name. Accepted values are:

  • full_name: full name of tool including the path;

  • base_name: name of tool excluding the path;

Default:

-tool_name_style=full_name
Option -unit_presentation_style
-unit_presentation_style
-unit_presentation_style=STYLE

Specify the output style for report unit reference.

STYLE:

sets the output style; the default is to include the full compilation command. Accepted values are:

  • include_full_command: file name with full compilation command;

  • file_name_only: main file name without the full compilation command;

Default:

-unit_presentation_style=file_name_only

Services

Option -disable
-disable
-disable=SERVICE,...

Services to disable.

The configuration’s content is a set of services to disable.

SERVICE:

a -service_selector identifier or a matcher expression used to select services.

Default:

-disable={}
Option -enable
-enable
-enable=SERVICE,...

Services to enable.

The configuration’s content is a set of services to enable.

SERVICE:

a -service_selector identifier or a matcher expression used to select services.

Default:

-enable={}

Metrics

Option -metrics
-metrics
-metrics={METRIC, SPECIFIER, SUMMARY},...

Specify custom metrics based on those already present.

The configuration’s content is a collection of named metric definitions.

METRIC:

the identifier for the custom metric.

SPECIFIER:

an expression that specifies the custom metric. Accepted forms are:

  • AGGR_ID(ID_BASE,AGGR_CTX): aggregated metric using ID_BASE as the basis

  • EXPR: expression of other metrics

AGGR_ID

accepted forms are:

  • max: the maximum of all base metric values for the specified context

  • min: the minimum of all base metric values for the specified context

  • sum: a sum of all base metric values for the specified context

  • count: a count of the number of base metric values for the specified context

AGGR_CTX

accepted forms are:

  • same: use the same context for both the aggregate metric and the base metric

  • function: use the function context for the aggregation

  • unit: use the translation unit context for the aggregation

  • program: use the whole program context for the aggregation

  • project: use the whole project context for the aggregation

EXPR

accepted forms are:

  • NUMBER: a number

  • list(EXPRS): a list of expressions

  • -EXPR: unary minus

  • ceil(EXPR): ceil

  • floor(EXPR): floor

  • max(EXPR,EXPR): max

  • min(EXPR,EXPR): min

  • round(EXPR): round

  • sign(EXPR): sign

  • sqr(EXPR): square

  • sqrt(EXPR): square root

  • EXPR_LHSBINOPEXPR_RHS: binary operator

  • EXPR_COND?:EXPR_ELSE: binary conditional operator

  • EXPR_COND?EXPR_THEN:EXPR_ELSE: conditional operator

  • ID_NAME:ID_SUBJECT: the metric expression has the metric name ID_NAME and subject ID_SUBJECT

  • ID: the metric expression is the metric name ID

BINOP

accepted forms are:

  • +: add

  • -: subtract

  • *: times

  • /: divide

  • %: remainder

  • &: bitwise and

  • |: bitwise or

  • ^: bitwise xor

  • ==: equal

  • !=: not equal

  • <: less than

  • >: greater than

  • <=: less than or equal to

  • >=: greater than or equal to

  • <<: bitwise left shift

  • >>: bitwise right shift

  • >=: greater than or equal to

  • &&: logical and

  • ||: logical or

  • ??: coalescing operator

EXPRS

accepted forms are:

  • EXPR,EXPRS: expressions

  • EXPR: expression

SUMMARY:

summery describing the metric.

Default:

-metrics={}

Types and constant names

Option -boolean_constants
-boolean_constants
-boolean_constants=NAME,...

Specify any defined Boolean constant.

NAME,…:

a set of Boolean constant names. Accepted members are:

  • NAME: a name for a Boolean constant.

Default:

-boolean_constants=true, false
Option -boolean_typenames
-boolean_typenames
-boolean_typenames=NAME,...

Specify type names used for Boolean values.

NAME,…:

a set of Boolean type names. Accepted members are:

  • NAME: a name for a Boolean type.

Default:

-boolean_typenames=bool
Option -typedef_naming
-typedef_naming
-typedef_naming={SCHEME, {{{BUILT_IN,...}, FMT},...}},...

Specify the builtin types that should always be used via a matching typedef.

The configuration’s content is a collection of named typedef naming schemes for builtin types.

SCHEME:

scheme identifier.

BUILT_IN,…:

built-in types. Accepted members are:

  • _Bool: _Bool;

  • __int128_t: __int128_t;

  • __uint128_t: __uint128_t;

  • bool: bool;

  • char: char;

  • char8_t: char8_t;

  • char16_t: char16_t;

  • char32_t: char32_t;

  • int: int;

  • long long: long long;

  • long: long;

  • short: short;

  • signed char: signed char;

  • unsigned char: unsigned char;

  • unsigned long long: unsigned long long;

  • unsigned long: unsigned long;

  • unsigned short: unsigned short;

  • unsigned: unsigned;

  • wchar_t: wchar_t;

  • double: double;

  • long double: long double;

  • float: float;

  • half: half;

  • __bf16: __bf16;

  • _Float16: _Float16;

  • void: void;

  • unsized_unsigned_integral: the following: unsigned, unsigned char, unsigned long, unsigned long long, unsigned short are the built-in unsized unsigned integral types;

  • unsized_signed_integral: the following: int, signed char, signed long, signed long long, signed short are the built-in unsized signed integral types;

  • unsized_floating: the following: double, float, half, long double are the built-in unsized floating point types;

  • unsized_complex_floating: the following: _Complex double, _Complex float, _Complex half, _Complex long double are the unsized complex floating point types;

FMT:

format (see the -fmt template typedef_naming_default_fmt) to specify the regular expression for matching the typedef name with fields:

bits

bit size of the built-in type;

bits0

two-digits bit size of the built-in.

Default:

-typedef_naming={misra,
    {{{unsized_unsigned_integral},
        "%{__misra_uint_fmt()}"},
      {{unsized_signed_integral},
        "%{__misra_sint_fmt()}"},
      {{unsized_floating},
        "%{__misra_float_fmt()}"},
      {{unsized_complex_floating},
        "%{__misra_complex_fmt()}"}}}

-typedef_naming+={misra_1,
    {{{"signed char"},
        "%{__misra_1_scint_fmt()}"},
      {{"unsigned char"},
        "%{__misra_1_ucint_fmt()}"},
      {{unsized_signed_integral},
        "%{__misra_1_siint_fmt()}"},
      {{unsized_unsigned_integral},
        "%{__misra_1_uiint_fmt()}"},
      {{unsized_floating},
        "%{__misra_1_float_fmt()}"},
      {{unsized_complex_floating},
        "%{__misra_1_complex_fmt()}"}}}

-typedef_naming+={lp1,
    {{{unsized_signed_integral},
        "%{__lp1_sint_fmt()}"},
      {{unsized_unsigned_integral},
        "%{__lp1_uint_fmt()}"},
      {{unsized_floating},
        "%{__lp1_float_fmt()}"},
      {{unsized_complex_floating},
        "%{__lp1_complex_fmt()}"}}}

-typedef_naming+={mp1,
    {{{char},
        "%{__mp1_char_fmt()}"},
      {{unsized_signed_integral},
        "%{__mp1_sint_fmt()}"},
      {{unsized_unsigned_integral},
        "%{__mp1_uint_fmt()}"},
      {{unsized_floating},
        "%{__mp1_float_fmt()}"},
      {{unsized_complex_floating},
        "%{__mp1_complex_fmt()}"}}}

-typedef_naming+={jpl,
    {{{unsized_signed_integral},
        "%{__jp1_sint_fmt()}"}, {{unsized_unsigned_integral},
        "%{__jp1_uint_fmt()}"},
      {{unsized_floating},
        "%{__jp1_float_fmt()}"},
      {{unsized_complex_floating},
        "%{__jp1_complex_fmt()}"}}}

Selectors

Option -area_selector
-area_selector
-area_selector={ID, AREA_MATCHER},...

Associates a selection identifier to an expression defining the matching report areas.

The configuration’s content is a collection of named selectors for report areas.

ID:

an area selection identifier.

AREA_MATCHER:

an expression defining the matching areas. Accepted forms are:

  • [+]AND_MATCHER: the area matches AND_MATCHER

  • -AND_MATCHER: the area does not match AND_MATCHER

  • [+]AND_MATCHER||AREA_MATCHER: either the area matches AND_MATCHER or it matches AREA_MATCHER

  • -AND_MATCHER||AREA_MATCHER: the area does not match AND_MATCHER but does match AREA_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the area matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the area matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (AREA_MATCHER): the area matches AREA_MATCHER

  • !BASIC_MATCHER: the area does not match BASIC_MATCHER

  • any(): any area matches

  • none(): no area matches

  • ^REGEX$: the message matches ^REGEX$

  • all_loc(LOC_MATCHER): all area’s locations matches LOC_MATCHER (see the -loc_selector global configuration)

  • any_loc(LOC_MATCHER): any area’s locations matches LOC_MATCHER (see the -loc_selector global configuration)

  • begin_loc(LOC_MATCHER): the area begin location matches LOC_MATCHER (see the -loc_selector global configuration)

  • end_loc(LOC_MATCHER): the area end location matches LOC_MATCHER (see the -loc_selector global configuration)

  • text(^REGEX$[,LINES_RANGE]): the text in top expansion location lines range relative to area defined by LINES_RANGE matches ^REGEX$. The default is begin+0..end+0

  • context(DECL_MATCHER): the context declaration matches DECL_MATCHER (see the -decl_selector global configuration)

  • decl(DECL_MATCHER): the declaration referred to in the area matches DECL_MATCHER (see the -decl_selector global configuration)

  • entity(ENTITY_MATCHER): the entity referred to in the area matches ENTITY_MATCHER (see the -entity_selector global configuration)

  • stmt(STMT_MATCHER): the statement or expression referred to in the area matches STMT_MATCHER (see the -stmt_selector global configuration)

  • kind(AREA_KIND[||AREA_KIND]*): the area kind one of the AREA_KIND

  • macro(MACRO_MATCHER): the macro referred to in the area matches MACRO_MATCHER (see the -macro_selector global configuration)

  • value(VALUE_MATCHER): the value for the area matches VALUE_MATCHER (see the -value_selector global configuration)

  • frame(FRAME_MATCHER): the frame generating the area matches FRAME_MATCHER (see the -frame_selector global configuration)

  • ID: the area matches the matcher associated to ID in the -area_selector global configuration

AREA_KIND

accepted forms are:

  • culprit: culprit

  • evidence: evidence

  • context: context

  • instantiation: instantiation

REGEX

accepted forms are:

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

LINES_RANGE

accepted forms are:

  • [begin±]NUMRANGE_SEP[end±]NUM: the range in the area location where the text matched by REGEX should be searched. begin is the first line of the area, and end is the last

Option -call_selector
-call_selector
-call_selector={ID, CALL_MATCHER},...

Associates a selection identifier to an expression defining the matching calls.

The configuration’s content is a collection of named selectors for macro and function calls.

ID:

a call selection identifier.

CALL_MATCHER:

an expression defining the matching calls. Accepted forms are:

  • [+]AND_MATCHER: the call matches AND_MATCHER

  • -AND_MATCHER: the call does not match AND_MATCHER

  • [+]AND_MATCHER||CALL_MATCHER: either the call matches AND_MATCHER or it matches CALL_MATCHER

  • -AND_MATCHER||CALL_MATCHER: the call does not match AND_MATCHER but does match CALL_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the call matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the call matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CALL_MATCHER): the call matches CALL_MATCHER

  • !BASIC_MATCHER: the call does not match BASIC_MATCHER

  • any(): any call matches

  • none(): no call matches

  • ^REGEX$: the fully qualified name of the callee matches ^REGEX$

  • all_arg(ARG_RANGE,STMT_MATCHER): for a call having all arguments with indices in the range ARG_RANGE that match STMT_MATCHER (note that the argument indices start at index 1 so that there is no element with index 0 and that negative range values are counted in reverse from the last argument down)

  • any_arg(ARG_RANGE,STMT_MATCHER): for a call having at least one argument with index in the range ARG_RANGE that matches STMT_MATCHER (note that the argument indices start at index 1 so that there is no element with index 0 and that negative range values are counted in reverse from the last argument down)

  • decl(DECL_MATCHER): the callee declaration matches DECL_MATCHER (see the -decl_selector global configuration)

  • entity(ENTITY_MATCHER): the callee declaration matches ENTITY_MATCHER (see the -entity_selector global configuration)

  • error_where(ERROR_WHERE): the call with error value in ERROR_WHERE)

  • impact(IMPACT): the call’s impact property is IMPACT

  • macro(MACRO_MATCHER): the call is expanded from a macro that matches MACRO_MATCHER (see the -macro_selector global configuration)

  • name(ID[||ID]*): the callee’s unqualified name is an identifier that matches one of the ID

  • node(ASTF[||ASTF]*): the call matches one of the AST functors

  • property(PROPERTY[||PROPERTY]*): the call property’s identifier is one of the PROPERTY

  • resource(RESOURCE_MATCHER): the call is referring to a resource that matches RESOURCE_MATCHER

  • return_type(TYPE_MATCHER): the call whose callee return type matches TYPE_MATCHER (see the -type_selector global configuration)

  • std(STDS_MATCHER): the standard used is STDS_MATCHER (see the -stds global configuration)

  • std_fname(ID[||ID]*): the callee’s unqualified name or called macro name matches one of the ID and is declared or defined in the standard library

  • stdlib(STDLIB[||STDLIB]*): select this call if the project standard library set contains one of the STDLIB (see the -stdlib global configuration)

  • stmt(STMT_MATCHER): the call expression is a statement matching STMT_MATCHER (see the -stmt_selector global configuration)

  • tag(TAG[||TAG]*): the call property’s tags matches one of the TAGs

  • type(TYPE_MATCHER): the call is a type that matches TYPE_MATCHER (see the -type_selector global configuration)

  • ID: the call matches the matcher associated to ID in -call_selector global configuration

STDLIB

accepted forms are:

  • posix: the project standard library posix

PROPERTY

accepted forms are:

  • const_pointee_read(POINTEE_RW[&&POINTEE_RW]*): indicate the read use for call arguments that correspond to parameters whose pointee types are const

  • const_pointee_write(POINTEE_RW[&&POINTEE_RW]*): indicate the write use for call arguments that correspond to parameters whose pointee types are const

  • data_kind(POS_MIN_MAX,TKIND): the call arguments or return in the specified index range POS_MIN_MAX have the specified data kind. Index 0 refers the return value, the indices of the arguments start from 1

  • errno[(MODE)]: if the argument is omitted or MODE is true, then, when an error occurs, the errno indicator will be set. If MODE is false, then the errno indicator is not set

  • error(ID[&&ID]*): function error is specified by ID

  • heap[(MODE)]: if the argument is omitted or MODE is true, then the call is considered as having the heap property. If MODE is false, then the call is considered as not having the heap property

  • ignorable_result[(MODE)]: if the argument is omitted or MODE is true, then the call is considered as having an ignorable result. If MODE is false, then the call is considered as having a non-ignorable result

  • IMPACT: the call has impact IMPACT

  • impact(IMPACT): the call has impact IMPACT

  • malloc[(MODE)]: if the argument is omitted or MODE is true, then the call is considered as having the malloc property. If MODE is false, then the call is considered as not having the malloc property

  • math_err[(MODE)]: if the argument is omitted or MODE is true, then the call is considered as possibly setting the errno indicator and/or raising a floating-point exception if an error occurs according to the value of math_errhandling. If MODE is false, then the call is considered as not setting the errno indicator and/or raising a floating-point exception. non-const

  • noeffect: like pure but can also read volatile variable not triggering side effects. This is equivalent to impact(noeffect)

  • noreturn[(MODE)]: if the argument is omitted or MODE is true, then the call is considered to be non-returning. If MODE is false, then the call is considered to be returning

  • pointee_read(POINTEE_RW[&&POINTEE_RW]*): indicate the read use for call arguments that correspond to parameters whose pointee types are non-const

  • pointee_write(POINTEE_RW[&&POINTEE_RW]*): indicate the write use for call arguments that correspond to parameters whose pointee types are non-const

  • points_to(POINTS_TO_ITEM[&&POINTS_TO_ITEM]*): all the points_to properties must hold

  • resource(RESOURCE_ITEM[,RESOURCE_ITEM]*): indicates a set of property resources that must hold

  • returned([RETURNED[&&RETURNED]*]): indicates that the specified address arguments may be returned; address arguments not listed are never returned

  • tag(Id[&&Id]*): user-defined property tags

  • taken([TAKEN[&&TAKEN]*]): indicates that the specified address arguments may be stored in objects that persist after the function has ceased to exist (excluding the returned value); address arguments not listed are never taken

IMPACT

accepted forms are:

  • const: call is const. That is, it is assumed that the called function is const

  • fp_const: the floating-point environment is unchanged and the call is const

  • pure: call is pure. That is, it is assumed that the called function is pure

  • noeffect: a call to a function with no external side effect. That is, it is assumed that: there are no indirect calls; any throw is caught within the function; there are no calls to new, delete, a non-trivial constructor or a destructor; it does not write to a variable that is volatile or has static storage; and it does not read from a volatile variable that triggers a side effects

  • nothrow: a call to a function for which it is assumed that any thrown exceptions are caught within the function

  • any: the call can have any impact

REGEX

accepted forms are:

ARG_RANGE

accepted forms are:

  • MINRANGE_SEPMAX: range is from MIN to MAX or, if MIN and MAX are negative and the length is L, the range is from L + MIN + 1 to L + MAX + 1

  • RANGE_SEPNUM: range is all values equal or less than NUM or, if NUM is negative and the length is L, the range is all values equal or less than L + NUM + 1

  • NUMRANGE_SEP: range is all values equal or greater than NUM or, if NUM is negative and the length is L, the range is all values equal or greater than L + NUM + 1

  • NUM: range is the single value NUM or, if NUM is negative and the length is L, the value is L + NUM + 1

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

Option -asm_properties
-asm_properties
-asm_properties={STMT_MATCHER, {PROPERTY,...}},...

Specify properties of a gcc asm statement.

The configuration’s content is a list of asm specifications with properties.

STMT_MATCHER:

the node is an asm statement that matches STMT_MATCHER (see -stmt_selector).

PROPERTY:

asm property. Accepted forms are:

  • no_side_effect: asm has no side effects

  • read_memory(BOOL3): indicate if reachable memory is read

  • write(BOOL3): indicate if asm output arguments are written

  • write_memory(BOOL3): indicate if reachable memory is written

BOOL3

accepted forms are:

  • always: always happens

  • maybe: might or might not happen

  • never: never happens

Option -default_asm_properties
-default_asm_properties
-default_asm_properties=PROP,...

Specify the default properties for gcc asm statements.

The configuration’s content is a set of properties.

PROP:

asm property.

Default:

-default_asm_properties="read_memory(maybe)",
  "write(always)",
  "write_memory(maybe)"
Option -comment_selector
-comment_selector
-comment_selector={ID, COMMENT_MATCHER},...

Associates a selection identifier to an expression defining the matching comments.

The configuration’s content is a collection of named selectors for comments.

ID:

a comment selection identifer.

COMMENT_MATCHER:

an expression defining the matching comments. Accepted forms are:

  • [+]AND_MATCHER: the comment matches AND_MATCHER

  • -AND_MATCHER: the comment does not match AND_MATCHER

  • [+]AND_MATCHER||COMMENT_MATCHER: either the comment matches AND_MATCHER or it matches COMMENT_MATCHER

  • -AND_MATCHER||COMMENT_MATCHER: the comment does not match AND_MATCHER but does match COMMENT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the comment matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the comment matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (COMMENT_MATCHER): the comment matches COMMENT_MATCHER

  • !BASIC_MATCHER: the comment does not match BASIC_MATCHER

  • any(): any comment matches

  • none(): no comment matches

  • ^REGEX$: the comment text matches ^REGEX$

REGEX

accepted forms are:

Default:

-comment_selector={__document_any_comments,
    "^(?:\\n|.)+$"},
  {__eclair_rtag_comments,
    "^/[/\\*]\\s*-+E>\\s.*$"},
  {__doxygen_comments,
    "^(?ms)/(\\*(\\*|!)|/(/|!)).*$"},
  {__fall_through_empty_case_comments,
    "^(.*[fF]all[- ]?[tT]hr(ough|u)|.*FALL[- ]?THR(OUGH|U))(?s).*$"},
  {__empty_missing_else_comments,
    "^.*(empty[- ]else|EMPTY[- ]ELSE)(?s).*$"},
  {__empty_compound_else_comments,
    "^.*(empty[- ]else|EMPTY[- ]ELSE)(?s).*$"},
  {__document_cast_comments,
    "^(?:\\n|.)*\\b([Cc]ast|[Cc]onversion|[Cc]onvert|[Oo]verflow|[Ww]rap[p]?)(s|ed|ing)?\\b(?:\\n|.)*$"}
Option -replacer
-replacer
-replacer={ID, REGEX, REPLACER},...

Associates a replacer identifier to an expression defining the replacements. The replacement expression associated to first regular expression that matches the input (if any) is evaluated and returned. If no regular expression matches, the input is returned unmodified. Some identifiers have special uses:

canonical_path

is used to influence file canonical pathname generation.

The configuration’s content is a collection of named replacer definitions.

ID:

a replacer identifier.

REGEX:

a regular expression.

REPLACER:

an expression defining the action. Accepted forms are:

  • 'STRING': the replacement is STRING

  • STRINGREPLACER_NAMED_PARTS: the output is the concatenation of STRING (maximal prefix not including the %) character followed by the replacement specified by REPLACER_NAMED_PARTS

REPLACER_NAMED_PARTS

accepted forms are:

  • %{REPLACER_EXPR{}}REPLACER_PARTS: the output is the concatenation of the replacements specified by REPLACER_EXPR and REPLACER_PARTS

REPLACER_PIPE_EXPR

accepted forms are:

  • REPLACER_CAT_EXPR: the output is the replacement specified by REPLACER_CAT_EXPR

  • REPLACER_CAT_EXPR|REPLACER_PIPE_EXPR: the output is the replacement specified by REPLACER_PIPE_EXPR with input expression specified by REPLACER_CAT_EXPR

REPLACER_CAT_EXPR

accepted forms are:

  • REPLACER_EXPR: the output is the replacement specified by REPLACER_EXPR

  • REPLACER_EXPR|REPLACER_CAT_EXPR: the output is the replacement specified by REPLACER_EXPR concatenated with the replacement specified by REPLACER_CAT_EXPR

REPLACER_EXPR

accepted forms are:

  • $POS_NUMBER: the regular expression group POS_NUMBER

  • @POS_NUMBER: the expression argument POS_NUMBER

  • regquote(REPLACER_EXPR): quote all special regular expression characters in REPLACER_EXPR, so that the output text can be used as part of a regular expression

  • upcase(REPLACER_EXPR): replace all lowercase by uppercase in REPLACER_EXPR

  • downcase(REPLACER_EXPR): replace all uppercase by lowercase in REPLACER_EXPR

  • save(REPLACER_EXPR0,REPLACER_EXPR1): add REPLACER_EXPR1 to saved assoc list values for key REPLACER_EXPR0

  • tr(REPLACER_EXPR0,REPLACER_EXPR1,REPLACER_EXPR2): in REPLACER_EXPR0, replace each character in REPLACER_EXPR1by the corresponding character in REPLACER_EXPR2

  • replace(REPLACER_EXPR0,REPLACER_EXPR1,REPLACER_EXPR2): in REPLACER_EXPR0, replace every string REPLACER_EXPR1 by the string REPLACER_EXPR2

  • substr(REPLACER_EXPR0,REPLACER_EXPR1,REPLACER_EXPR2): the expression arguments REPLACER_EXPR1 and REPLACER_EXPR2 must evaluate to non-negative integers; then REPLACER_EXPR0 is replaced by the substring beginning at REPLACER_EXPR1 with length REPLACER_EXPR2

  • REPLACER_ID(REPLACER_EXPR0,REPLACER_EXPR1): replace text using replacer REPLACER_ID with arguments replacer expressions REPLACER_EXPR0 and REPLACER_EXPR1

  • 'STRING': the quoted string STRING

  • NUMBER: the number NUMBER

Default:

-replacer={__anydecl_document_repl, "^(?:\\n|.)+$", "%{$0}"}

-replacer+={__anydecl_comment_repl, "^//(.*)$", "%{$1} "},
  {__anydecl_comment_repl, "^/[*]((?:\\n|.)*)([*]/)$", "%{$1} "}

-replacer+={__function_document_repl, "^(?:\\n|.)+$", "%{$0}"}

-replacer+={__parameter_document_repl, "^(?:\\n|.)*$", "%{$0}"}

-replacer+={__function_comment_repl, "^//(.*)$", "%{$1} "},
  {__function_comment_repl, "^/[*]((?:\\n|.)*)([*]/)$", "%{$1} "}

-replacer+={__memory_reuse_comment_repl, "^//(.*)$", "%{$1} "},
  {__memory_reuse_comment_repl, "^/[*]((?:\\n|.)*)([*]/)$", "%{$1} "}

-replacer+={__asm_comment_repl, "^//(.*)$", "%{$1} "},
  {__asm_comment_repl, "^/[*]((?:\\n|.)*)([*]/)$", "%{$1} "}

-replacer+={__expr_comment_repl, "^//(.*)$", "%{$1} "},
  {__expr_comment_repl, "^/[*]((?:\\n|.)*)([*]/)$", "%{$1} "}

-replacer+={__fundefn_comment_repl, "^//(.+)$", "%{$1}"},
  {__fundefn_comment_repl, "^/[*]((?:\\n|.)+)([*]/)$", "%{$1}"}
Option -context_selector
-context_selector
-context_selector={ID, CONTEXT_MATCHER},...

Associates a selection identifier to an expression defining the matching contexts.

The configuration’s content is a collection of named selectors for contexts.

ID:

a context selection identifier.

CONTEXT_MATCHER:

an expression defining the matching context, where context refers to a node with its chain of ancestors in the AST; the immediate ancestor of a node is called the parent. Accepted forms are:

  • OR_MATCHER: the context matches OR_MATCHER

OR_MATCHER

accepted forms are:

  • [+]AND_MATCHER: context matches AND_MATCHER

  • -AND_MATCHER: context does not match AND_MATCHER

  • [+]AND_MATCHER||CTXT_MATCHER: either context matches AND_MATCHER or it matches CTXT_MATCHER

  • -AND_MATCHER||CTXT_MATCHER: context does not match AND_MATCHER but does match CTXT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the context matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: context matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CTXT_MATCHER): context matches CTXT_MATCHER

  • !BASIC_MATCHER: context does not match BASIC_MATCHER

  • any(): matches any context

  • none(): matches no context

  • call(CALL_MATCHER): the node is a function call that matches CALL_MATCHER (see the -call_selector global configuration)

  • class(CLASS[||CLASS]*): the node‘s class matches a CLASS

  • constexpr(): context requires a constant expression node

  • decl(DECL_MATCHER): node is a declaration that matches DECL_MATCHER (see the -decl_selector global configuration)

  • entity(ENTITY_MATCHER): node is an entity that matches ENTITY_MATCHER (see the -entity_selector global configuration)

  • is(CHILD[||CHILD]*): the child kind of node with respect to its parent matches a CHILD

  • node(ASTF[||ASTF]*): the node‘s AST functor matches an ASTF

  • parent(CTXT_MATCHER): the node parent matches CTXT_MATCHER

  • role(CTXT_ROLE[||CTXT_ROLE]*): node has a role with respect to its context matching a CTXT_ROLE

  • save(ID,CTXT_MATCHER): if context matches CTXT_MATCHER, it is saved with identifier ID

  • skip(CTXT_MATCHER_0,CTXT_MATCHER_1): node is wrapped greedily (0 or more times) by ancestors matching CTXT_MATCHER_0 up to a node matching CTXT_MATCHER_1

  • std(STDS_MATCHER): the standard used matches STDS_MATCHER (see the -stds global configuration)

  • stmt(STMT_MATCHER): node is a statement that matches STMT_MATCHER (see the -stmt_selector global configuration)

  • type(TYPE_MATCHER): node is a type that matches TYPE_MATCHER (see the -type_selector global configuration)

  • unevaluated(): an unevaluated context

  • wrapped(CTXT_MATCHER_0,CTXT_MATCHER_1): node is wrapped lazily (0 or more times) by ancestors matching CTXT_MATCHER_0 up to a node matching CTXT_MATCHER_1

  • ID: context matches the matcher associated to ID in -context_selector global configuration

CHILD

accepted forms are:

  • any: any child

  • CHILD: CHILD is a nonterminal child kind of an AST node

  • CHILD-POS_MIN_MAX: CHILD is a nonterminal child kind of an AST node and the child index is in the range indicated by POS_MIN_MAX

POS_MIN_MAX

accepted forms are:

  • POS_NUM_MINRANGE_SEPPOS_NUM_MAX: range is from (non-negative) POS_NUM_MIN to POS_NUM_MAX

  • POS_NUMRANGE_SEP: range is all values equal or more than (non-negative) POS_NUM

  • POS_NUM: range is the single non-negative value POS_NUM

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

CLASS

accepted forms are:

  • decl: decl class

  • stmt: stmt class

  • expr: expr class

  • type: type class

Option -decl_selector
-decl_selector
-decl_selector={ID, DECL_MATCHER},...

Associates a selection identifier to an expression defining the matching declarations.

The configuration’s content is a collection of named selectors for declarations.

ID:

a declaration selection identifier.

DECL_MATCHER:

an expression defining the matching declaration. Accepted forms are:

  • [+]AND_MATCHER: the declaration matches AND_MATCHER

  • -AND_MATCHER: the declaration does not match AND_MATCHER

  • [+]AND_MATCHER||DECL_MATCHER: either the declaration matches AND_MATCHER or it matches DECL_MATCHER

  • -AND_MATCHER||DECL_MATCHER: the declaration does not match AND_MATCHER but does match DECL_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the declaration matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the declaration matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (DECL_MATCHER): the declaration matches DECL_MATCHER

  • !BASIC_MATCHER: the declaration does not match BASIC_MATCHER

  • any(): any declaration matches

  • none(): no declaration matches

  • ^REGEX$: the declaration is named and its fully qualified name matches ^REGEX$

  • abstract(): the declaration is a class that is abstract

  • access(ACCESS_SPEC[||ACCESS_SPEC]*): the declaration has one of the access specifiers ACCESS_SPECIFIER

  • all_child(DECL_MATCHER): for any declaration with inner declarations, all of these match DECL_MATCHER

  • all_param(MIN_MAX,DECL_MATCHER): for a function, all parameters with indices in the range MIN_MAX match DECL_MATCHER

  • ancestor(DECL_MATCHER): an ancestor declaration context matches DECL_MATCHER

  • ancestor_or_self(DECL_MATCHER): the declaration or an ancestor declaration context matches DECL_MATCHER

  • anonymous(): the declaration is anonymous

  • any_child(DECL_MATCHER): for any declaration with inner declarations, one of these match DECL_MATCHER

  • any_inheritance(TYPE_MATCHER): the declaration is a class that inherits from a type that matches TYPE_MATCHER

  • any_param(MIN_MAX,DECL_MATCHER): for a function, one of the parameters with indices in the range MIN_MAX match DECL_MATCHER

  • any_type_targ(MIN_MAX,TYPE_MATCHER): for a specialization, one of the template parameters with indices in the range MIN_MAX match TYPE_MATCHER

  • ast_field(NAME_ID,NAME_MATCHER): an ast field NAME_ID whose value matches NAME_MATCHER

  • bitfield_width(POS_MIN_MAX): the declaration is for a bit-field with length in the range POS_MIN_MAX

  • body_kind(FUNCTION_BODY_KIND[||FUNCTION_BODY_KIND]*): the declaration is a function definition whose body has one of the kinds FUNCTION_BODY_KIND

  • constexpr(): the declaration has the constexpr specifier

  • child_pair(DECL_MATCHER1,DECL_MATCHER2): the declaration has multiple inner declarations; one matches DECL_MATCHER1 and another matches DECL_MATCHER2

  • context(DECL_MATCHER): the declaration’s context matches DECL_MATCHER

  • copy_assignment(): the declaration is a method with the copy assignment operator

  • constructor([CONSTRUCTOR_TAG[||CONSTRUCTOR_TAG]*]): the declaration is a constructor matching at least one of the tags CONSTRUCTOR_TAG, or any constructor if no tags are specified

  • entity(ENTITY_MATCHER): the entity matches ENTITY_MATCHER (see the -entity_selector global configuration)

  • enum_implicit_type(): an enum whose underlying type is implicit

  • enum_scope(SCOPE_KIND[||SCOPE_KIND]*): a scoped enum declaration where the scope is one of SCOPE_KIND

  • enum_underlying_type(TYPE_MATCHER): an enum whose underlying type matches TYPE_MATCHER

  • explicit(): the declaration is a constructor/conversion and is explicit

  • extern_c: the function or variable declaration is wrapped by an extern “C” declaration

  • external_repeatable_defn(): the declaration is a repeatable function definition

  • forward_decl(): the declaration is a forward declaration

  • fqname('ID'[||'ID']*): the declaration’s fully qualified name matches one of the ID

  • implicit_access(): the declaration has implicit access

  • inherit(DECL_MATCHER,POS_MIN_MAX): the declaration inherits within level range POS_MIN_MAX matching DECL_MATCHER

  • initialized(): the declaration has an initialization

  • initializer(STMT_MATCHER): the declaration has an initializer expression that matches STMT_MATCHER

  • inline(): the declaration is inline

  • instance(INSTANCE_KIND): the declaration must have the instance kind INSTANCE_KIND

  • intrinsic(): a compiler intrinsic declaration

  • kind(ENTITY_KIND[||ENTITY_KIND]*): the entity has one of the entity ENTITY_KINDs

  • lexical_context(DECL_MATCHER): the declaration’s lexical context matches DECL_MATCHER

  • linkage(LINKAGE): the declaration has linkage LINKAGE

  • loc(LOC_MATCHER): the location of the declaration name matches LOC_MATCHER (see the -loc_selector global configuration)

  • move_assignment(): the declaration is a method with the move assignment operator

  • name(ID[||ID]*): the declaration’s name matches one of the ID

  • namespace(DECL_MATCHER): the declaration’s namespace matches DECL_MATCHER

  • node(ASTF[||ASTF]*): the declaration’s AST functor matches one of the ASTF

  • origin(ORIGIN): the declaration must have the named origin ORIGIN

  • outofline(): the declaration is out-of-line

  • override(DECL_MATCHER): the declaration is a method that overrides DECL_MATCHER

  • parameter_count(POS_MIN_MAX_L,POS_MIN_MAX_U): the declaration has parameters; the minimum number of parameters is in range POS_MIN_MAX_L and the maximum is in range POS_MIN_MAX_U

  • pattern(): the declaration must be a pattern

  • pod(): the declaration is a pod class

  • polymorphic_class(): the class is polymorphic

  • property(ID[||ID]*): the declaration has property ID. The property can be either a call property (see the -call_properties global configuration) or a declaration property (see the -decl_properties global configuration)

  • proto(PROTO_KIND): the declaration has a PRTO_KIND

  • record_kind(RECORD_KIND[||RECORD_KIND]*): the declaration is a record with one of the kinds RECORD_KIND

  • redeclared(): the declaration is a redeclaration

  • same_id_type(): the declaration and its type have the same unqualified names

  • save(ID,DECL_MATCHER): the declaration that matches DECL_MATCHER is saved with identifier ID

  • single_inheritance_hierarchy(): the declaration is a class with a single inheritance hierarchy

  • std(STDS_MATCHER): the standard used is STDS_MATCHER (see the -stds global configuration)

  • storage_duration(STORAGE_DURATION): the declaration has storage duration STORAGE_DURATION

  • tentative_defn(): the declaration is a tentative definition

  • targ_count(MIN_MAX): the declaration has POS_MIN_MAX template arguments

  • type(TYPE_MATCHER): the declaration has a type that matches TYPE_MATCHER (see the -type_selector global configuration)

  • underlying_type(TYPE_MATCHER): the underlying type matches TYPE_MATCHER

  • variadic(): the declaration is variadic function

  • virtual_method(): the declaration is a virtual method (note that this matches also virtual destructors)

  • visibility(VISIBILITY): the declaration has visibility VISIBILITY

  • written_inline(): the declaration has inline specifier

  • written_storage(STORAGE_CLASS): the declaration has storage STORAGE_CLASS

  • ID: the declaration matches the matcher associated to ID in the -decl_selector global configuration

POS_MIN_MAX

accepted forms are:

  • POS_NUM_MINRANGE_SEPPOS_NUM_MAX: range is from (non-negative) POS_NUM_MIN to POS_NUM_MAX

  • POS_NUMRANGE_SEP: range is all values equal or more than (non-negative) POS_NUM

  • POS_NUM: range is the single non-negative value POS_NUM

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

REGEX

accepted forms are:

ENTITY_KIND

accepted forms are:

  • class_template: a class template

  • constructor: a constructor

  • constructor_using_shadow: a constructor using shadow

  • conversion: a conversion

  • destructor: a destructor

  • enum: an enum

  • enum_constant: an enum constant

  • function: a function

  • function_template: a function template

  • label: a label

  • field: a field

  • method: a method

  • namespace: a namespace

  • namespace_alias: a namespace alias

  • param: a parameter

  • static_field: a static field

  • template_non_type_param: a template non type parameter

  • template_template_param: a template template parameter

  • template_type_param: a template type parameter

  • type_alias: a type alias

  • type_alias_template: a type alias template

  • typedef: a typedef

  • unresolved_using_typedef: an unresolved using typedef

  • unresolved_using_value: an unresolved using value

  • using: a using decl

  • using_directive: a using directive decl

  • using_shadow: a using shadow decl

  • var: a variable

LINKAGE

accepted forms are:

  • external: linkage is external

  • internal: linkage is internal

  • no_linkage: there is no linkage

  • has_linkage: linkage is internal or external

CONSTRUCTOR_TAG

accepted forms are:

  • copy: copy constructor

  • default: default constructor

  • delegating: delegating constructor

  • inheriting: inheriting constructor

  • move: move constructor

  • trivial: trivial constructor

RECORD_KIND

accepted forms are:

  • class: class

  • struct: structure

  • union: union

ACCESS_SPEC

accepted forms are:

  • empty: access is empty or unspecified

  • public: access is declared public

  • protected: access is declared protected

  • private: access is private

STORAGE_CLASS

accepted forms are:

  • static: storage is static

  • auto: storage is auto

  • extern: storage is extern

  • register: storage is register

  • none: no storage

STORAGE_DURATION

accepted forms are:

  • static: storage duration is static

  • auto: storage duration is automatic

  • thread_local: storage is thread

INSTANCE_KIND

accepted forms are:

  • none: the declaration must not be a instance

  • partial_specialization: the declaration must be a partial specialization

  • specialization: the declaration must be a full specialization

  • instantiation: the declaration must be an instantiation

FUNCTION_BODY_KIND

accepted forms are:

  • default: default kind

  • delete: delete kind

  • implicit: implicit kind

  • unparsed: unparsed kind

  • written: written kind

ORIGIN

accepted forms are:

  • embedded: embedded declaration

  • standalone: standalone declaration

  • synthetic: synthetic declaration

VISIBILITY

accepted forms are:

  • program: program visibility

  • unit: unit visibility

  • local: block local visibility

PROTO_KIND

accepted forms are:

  • written: a written prototype

  • no_written: no written prototype

  • k_and_r: k-and-r definition

DIRECTIVE

accepted forms are:

  • include: #include directive

  • define: #define directive

  • undef: #undef directive

RECORD_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the record matches AND_MATCHER

  • -AND_MATCHER: the record does not match AND_MATCHER

  • [+]AND_MATCHER||RECORD_MATCHER: either the record matches AND_MATCHER or it matches RECORD_MATCHER

  • -AND_MATCHER||RECORD_MATCHER: the record does not match AND_MATCHER but does match RECORD_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the record matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the record matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • kind(RECORD_KIND[||RECORD_KIND]*): the record kind is one of RECORD_KIND

  • polymorphic(): the record is polymorphic

  • defn(DECL_MATCHER): one of members in the definition matches DECL_MATCHER

  • record_defn_has_no_named_member(): declaration is a struct or union definition with no named member

Option -entity_selector
-entity_selector
-entity_selector={ID, ENTITY_MATCHER},...

Associates a selection identifier to an expression defining the matching entities.

The configuration’s content is a collection of named selectors for entities.

ID:

an entity selection identifier.

ENTITY_MATCHER:

an expression defining the matching entities. Accepted forms are:

  • [+]AND_MATCHER: the entity matches AND_MATCHER

  • -AND_MATCHER: the entity does not match AND_MATCHER

  • [+]AND_MATCHER||ENTITY_MATCHER: either the entity matches AND_MATCHER or it matches ENTITY_MATCHER

  • -AND_MATCHER||ENTITY_MATCHER: the entity does not match AND_MATCHER but does match ENTITY_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER[&&AND_MATCHER]*: the entity matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (ENTITY_MATCHER): the entity matches ENTITY_MATCHER

  • !BASIC_MATCHER: the entity does not match BASIC_MATCHER

  • any(): any entity matches

  • none(): no entity matches

  • ^REGEX$: the fully qualified names of a declaration of the entity matches ^REGEX$

  • abstract(): the entity is a class that is abstract

  • access(ACCESS_SPEC[||ACCESS_SPEC]*): the entity has one of the access specifiers ACCESS_SPECIFIER

  • all_decl(DECL_MATCHER): all the entity declarations match DECL_MATCHER (see the -decl_selector global configuration)

  • ancestor(ENTITY_MATCHER): an ancestor declaration context for the entity matches ENTITY_MATCHER

  • ancestor_or_self(ENTITY_MATCHER): the entity itself or an ancestor declaration context for the entity matches ENTITY_MATCHER

  • anonymous(): the entity is anonymous

  • any_decl(DECL_MATCHER): at least one entity declaration matches DECL_MATCHER (see the -decl_selector global configuration)

  • any_type_targ(MIN_MAX,TYPE_MATCHER): for a specialization, one of the template parameters with indices in the range MIN_MAX match TYPE_MATCHER

  • bitfield_width(POS_MIN_MAX): the entity is a bit-field with length in the range POS_MIN_MAX

  • context(ENTITY_MATCHER): the entity’s context matches ENTITY_MATCHER

  • constructor([CONSTRUCTOR_TAG[||CONSTRUCTOR_TAG]*]): the entity is a constructor matching at least one of the tags CONSTRUCTOR_TAG, or any constructor if no tags are specified

  • copy_assignment(): the entity is a method with the copy assignment operator

  • extra_referenced(): the entity is referenced in a non-visible ways

  • fqname('ID'[||'ID']*): at least one entity declaration has a fully qualified name that matches one of the fully qualified names ID

  • inline(): the entity is inline

  • instance(INSTANCE_KIND): the declaration must have the instance kind INSTANCE_KIND

  • kind(ENTITY_KIND[||ENTITY_KIND]*): the entity has one of the entity ENTITY_KINDs

  • linkage(LINKAGE): entity has linkage LINKAGEs

  • move_assignment(): the entity is a move assignment operatort

  • name(NAME[||NAME]*): at least one entity declaration has an unqualified name that matches one of the names NAME

  • namespace(ENTITY_MATCHER): the entity namespace matches ENTITY_MATCHER

  • override(DECL_MATCHER): the entity is a method that overrides DECL_MATCHER

  • pattern(): the entity must be a pattern

  • parameter_count(POS_MIN_MAX_L,POS_MIN_MAX_U): the entity has parameters; the minimum number of parameters is in range POS_MIN_MAX_L and the maximum is in range POS_MIN_MAX_U

  • record_kind(KIND[||RECORD_KIND]*): the entity is a record whose kind is one of the record kinds RECORD_KIND

  • save(ID,ENTITY_MATCHER): the entity that matches ENTITY_MATCHER is saved with identifier ID

  • storage_duration(STORAGE_DURATION): the entity has storage duration STORAGE_DURATION

  • targ_count(MIN_MAX): the entity has POS_MIN_MAX template arguments

  • visibility(VISIBILITY): the entity has visibility VISIBILITY

  • ID: the entity matches the matcher associated to ID in -entity_selector global configuration

REGEX

accepted forms are:

ACCESS_SPEC

accepted forms are:

  • empty: access is empty or unspecified

  • public: access is declared public

  • protected: access is declared protected

  • private: access is private

INSTANCE_KIND

accepted forms are:

  • none: the declaration must not be a instance

  • partial_specialization: the declaration must be a partial specialization

  • specialization: the declaration must be a full specialization

  • instantiation: the declaration must be an instantiation

STORAGE_CLASS

accepted forms are:

  • static: storage is static

  • auto: storage is auto

  • extern: storage is extern

  • register: storage is register

  • none: no storage

STORAGE_DURATION

accepted forms are:

  • static: storage duration is static

  • auto: storage duration is automatic

  • thread_local: storage is thread

VISIBILITY

accepted forms are:

  • program: program visibility

  • unit: unit visibility

  • local: block local visibility

RECORD_KIND

accepted forms are:

  • class: class

  • struct: structure

  • union: union

ENTITY_KIND

accepted forms are:

  • class_template: a class template

  • constructor: a constructor

  • constructor_using_shadow: a constructor using shadow

  • conversion: a conversion

  • destructor: a destructor

  • enum: an enum

  • enum_constant: an enum constant

  • function: a function

  • function_template: a function template

  • label: a label

  • field: a field

  • method: a method

  • namespace: a namespace

  • namespace_alias: a namespace alias

  • param: a parameter

  • static_field: a static field

  • template_non_type_param: a template non type parameter

  • template_template_param: a template template parameter

  • template_type_param: a template type parameter

  • type_alias: a type alias

  • type_alias_template: a type alias template

  • typedef: a typedef

  • unresolved_using_typedef: an unresolved using typedef

  • unresolved_using_value: an unresolved using value

  • using: a using decl

  • using_directive: a using directive decl

  • using_shadow: a using shadow decl

  • var: a variable

LINKAGE

accepted forms are:

  • external: linkage is external

  • internal: linkage is internal

  • no_linkage: there is no linkage

  • has_linkage: linkage is internal or external

CONSTRUCTOR_TAG

accepted forms are:

  • copy: copy constructor

  • default: default constructor

  • delegating: delegating constructor

  • inheriting: inheriting constructor

  • move: move constructor

  • trivial: trivial constructor

Option -file_tag
-file_tag
-file_tag={FILE_TAG, FILE_MATCHER},...

Assign tags to the files.

The configuration’s content is an ordered list of pairs ([DOMAIN:]FILE_TAG, FILE_MATCHER) combining a file tag with a file matcher. The tag paired with the first file matcher that matches the file name is assigned to that file for the specified domain (or the empty domain if it is not specified); no tag is assigned if there are no matching file matchers.

FILE_TAG:

the file’s tag.

FILE_MATCHER:

for matching the file. Accepted forms are:

  • [+]AND_MATCHER: the file matches AND_MATCHER

  • -AND_MATCHER: the file does not match AND_MATCHER

  • [+]AND_MATCHER||FILE_MATCHER: either the file matches AND_MATCHER or it matches FILE_MATCHER

  • -AND_MATCHER||FILE_MATCHER: the file does not match AND_MATCHER but does match FILE_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the file matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the file matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (FILE_MATCHER): the file matches FILE_MATCHER

  • !BASIC_MATCHER: the file does not match BASIC_MATCHER

  • any(): any file matches

  • none(): no files matches

  • ^REGEX$: the file name matches ^REGEX$

  • kind(FILE_KIND[||FILE_KIND]*): the file has one of the kind FILE_KINDs

  • public(): the file is a public API file; by default the set of public API files includes all system headers; the set may be modified using the -public_files global configuration

  • std(): the file is part of the standard library

  • ID: the file has tag ID

REGEX

accepted forms are:

FILE_KIND

accepted forms are:

  • internal: an ECLAIR internal file

  • main_file: the main source file for the unit

  • object: an object file

  • project: the project as a whole

  • pseudo: a non file source (e.g. generated from compiler command line or from token pasting)

  • system: a system header file

  • user: a user header file

Default:

-file_tag={external, "kind(system||extern_c_system)||^([A-Z]:)?/.*$"},
  {project_files, "kind(main_file||user||object||project)&&!^([A-Z]:)?/.*$"},
  {pseudo, "kind(pseudo)"},
  {main, "kind(main_file)"},
  {header, "kind(user||system||extern_c_system)"}
Option -frame_selector
-frame_selector
-frame_selector={ID, FRAME_MATCHER},...

Associates a selection identifier to an expression defining the matching frames.

The configuration’s content is a collection of named selectors for frames.

ID:

a frame selection identifier.

FRAME_MATCHER:

an expression defining the matching frames. Accepted forms are:

  • [+]AND_MATCHER: the frame matches AND_MATCHER

  • -AND_MATCHER: the frame does not match AND_MATCHER

  • [+]AND_MATCHER||FRAME_MATCHER: either the frame matches AND_MATCHER or it matches FRAME_MATCHER

  • -AND_MATCHER||FRAME_MATCHER: the frame does not match AND_MATCHER but does match FRAME_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the frame matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the frame matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (FRAME_MATCHER): the frame matches FRAME_MATCHER

  • !BASIC_MATCHER: the frame does not match BASIC_MATCHER

  • any(): any frame matches

  • none(): no frame matches

  • main(FILE_MATCHER): the main file matches FILE_MATCHER (see the -file_tag global configuration)

  • target(FILE_MATCHER): the target file matches FILE_MATCHER (see the -file_tag global configuration)

  • kind(FRAME_KIND[||FRAME_KIND]*): the frame has one of the kind FRAME_KINDs

  • std(STD_MATCHER): the unit frame has a standard that matches STD_MATCHER (see the -stds global configuration)

  • option(OPTION_MATCHER): the frame has a tagged option that matches OPTION_MATCHER (see the -option_selector global configuration)

  • tool(TOOL_TAG): the tool is named and its name matches TOOL_TAG (see the -tool_tag global configuration)

FRAME_KIND

accepted forms are:

  • unit: unit analysis frame

  • program: program analysis frame

  • project: project analysis frame

  • object: object analysis frame

  • command: command frame

REGEX

accepted forms are:

Option -loc_selector
-loc_selector
-loc_selector={ID, LOC_MATCHER},...

Associates a selection identifier to an expression defining the matching location.

The configuration’s content is a collection of named selectors for locations.

ID:

a location selection identifier.

LOC_MATCHER:

an expression defining the matching locations. Accepted forms are:

  • [+]AND_MATCHER: the location matches AND_MATCHER

  • -AND_MATCHER: the location does not match AND_MATCHER

  • [+]AND_MATCHER||LOC_MATCHER: either the location matches AND_MATCHER or it matches LOC_MATCHER

  • -AND_MATCHER||LOC_MATCHER: the location does not match AND_MATCHER but does match LOC_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the location matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the location matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (LOC_MATCHER): the location matches LOC_MATCHER

  • !BASIC_MATCHER: the location does not match BASIC_MATCHER

  • any(): any location matches

  • none(): no location matches

  • file(FILE_TAG): the location’s file matches FILE_TAG (see the -file_tag global configuration)

  • line(POS_MIN_MAX): the location line number is within range POS_MIN_MAX

  • top(LOC_MATCHER): the top expansion location matches LOC_MATCHER

  • begin_exp(LOC_MATCHER): direct expansion begin location matches LOC_MATCHER

  • end_exp(LOC_MATCHER): direct expansion end location matches LOC_MATCHER

  • any_exp(LOC_MATCHER): some expansion location matches LOC_MATCHER

  • all_exp(LOC_MATCHER): all expansion locations match LOC_MATCHER

  • any_begin_exp(LOC_MATCHER): some expansion begin location matches LOC_MATCHER

  • all_begin_exp(LOC_MATCHER): all expansion begin locations match LOC_MATCHER

  • any_end_exp(LOC_MATCHER): some expansion end location matches LOC_MATCHER

  • all_end_exp(LOC_MATCHER): all expansion end locations match LOC_MATCHER

  • text(^REGEX$[,LINES_RANGE]): the text in lines range relative to location defined by LINES_RANGE matches ^REGEX$. The default is0..0

  • macro(MACRO_MATCHER): the location is at an expansion of a macro that matches MACRO_MATCHER (see the -macro_selector global configuration)

  • ID: the location matches the matcher associated to ID in the -loc_selector global configuration

POS_MIN_MAX

accepted forms are:

  • POS_NUM_MINRANGE_SEPPOS_NUM_MAX: range is from (non-negative) POS_NUM_MIN to POS_NUM_MAX

  • POS_NUMRANGE_SEP: range is all values equal or more than (non-negative) POS_NUM

  • POS_NUM: range is the single non-negative value POS_NUM

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

LINES_RANGE

accepted forms are:

  • [begin±]NUMRANGE_SEP[end±]NUM: the range in the area location where the text matched by REGEX should be searched. begin is the first line of the area, and end is the last

Option -macro_selector
-macro_selector
-macro_selector={ID, MACRO_MATCHER},...

Associates a selection identifier to an expression defining the matching macros.

The configuration’s content is a collection of named selectors for macros.

ID:

a macro selection identifier.

MACRO_MATCHER:

an expression defining the matching macros. Accepted forms are:

  • [+]AND_MATCHER: the macro matches AND_MATCHER

  • -AND_MATCHER: the macro does not match AND_MATCHER

  • [+]AND_MATCHER||MACRO_MATCHER: either the macro matches AND_MATCHER or it matches MACRO_MATCHER

  • -AND_MATCHER||MACRO_MATCHER: the macro does not match AND_MATCHER but does match MACRO_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the macro matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the macro matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (MACRO_MATCHER): the macro matches MACRO_MATCHER

  • !BASIC_MATCHER: the macro does not match BASIC_MATCHER

  • any(): any macro matches

  • none(): no macro matches

  • ^REGEX$: the macro name matches ^REGEX$

  • body(^REGEX$): the body’s normalized text (that is, a string where the parsed tokens are separated by a single space character) matches ^REGEX$

  • function_like(): the macro kind is function-like

  • guard(): the macro is used as a guard

  • loc(LOC_MATCHER): the macro definition location matches LOC_MATCHER (see the -loc_selector global configuyration)

  • name(ID[||ID]*): the macro’s name matches one of the ID

  • parameters(POS_MIN_MAX): the macro is function-like and the number of its parameters is in the range POS_MIN_MAX

  • previous(MACRO_MATCHER): the macro is a redefinition of a macro that matches MACRO_MATCHER (see the -macro_selector global configuration)

  • same_id_body(): the macro body is the macro name; for example: #define x x or #define x() x

  • used(): the macro is used

  • variadic(): the macro is variadic

  • ID: the macro matches the matcher associated to ID in -macro_selector global configuration

REGEX

accepted forms are:

Option -name_selector
-name_selector
-name_selector={ID, NAME_MATCHER},...

Associates a selection identifier to an expression defining the matching names.

The configuration’s content is a collection of named selectors for names.

ID:

a name selection identifier.

NAME_MATCHER:

an expression defining the matching names. Accepted forms are:

  • [+]AND_MATCHER: the name matches AND_MATCHER

  • -AND_MATCHER: the name does not match AND_MATCHER

  • [+]AND_MATCHER||NAME_MATCHER: either the name matches AND_MATCHER or it matches NAME_MATCHER

  • -AND_MATCHER||NAME_MATCHER: the name does not match AND_MATCHER but does match NAME_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the name matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the name matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (NAME_MATCHER): the name matches NAME_MATCHER

  • !BASIC_MATCHER: the name does not match BASIC_MATCHER

  • any(): any name matches

  • none(): no name matches

  • ^REGEX$: the name matches ^REGEX$

  • name(ID): the name matches ID

  • replace_vocabulary(REPL): if vocabulary options are supported, then, after transforming the name using REPL, the transformed name satisfies criteria defined using the supplied dictionaries, word files and associated configuration options

  • vocabulary(): if vocabulary options are supported, the name satisfies criteria defined using the supplied dictionaries, word files and associated configuration options

  • ID: the name matches the matcher associated to ID in the -name_selector global configuration

REGEX

accepted forms are:

Option -option_selector
-option_selector
-option_selector={ID, OPTION_MATCHER},...

Associates a selection identifier to an expression defining the matching options.

The configuration’s content is a collection of named selectors for options.

ID:

a option selection identifier.

OPTION_MATCHER:

an expression defining the matching options. Accepted forms are:

  • [+]AND_MATCHER: the option matches AND_MATCHER

  • -AND_MATCHER: the option does not match AND_MATCHER

  • [+]AND_MATCHER||OPTION_MATCHER: either the option matches AND_MATCHER or it matches OPTION_MATCHER

  • -AND_MATCHER||OPTION_MATCHER: the option does not match AND_MATCHER but does match OPTION_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the option matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the option matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (OPTION_MATCHER): the option matches OPTION_MATCHER

  • !BASIC_MATCHER: the option does not match BASIC_MATCHER

  • any(): any option matches

  • none(): no option matches

  • tag(NAME_MATCHER): the tag is named and its name matches NAME_MATCHER (see the -name_selector global configuration)

  • arg(POS_NUM,^REGEX$): the argument at position POS_NUM matches ^REGEX$

  • tool(TOOL_TAG): the tool is named and its name matches TOOL_TAG (see the -tool_tag global configuration)

REGEX

accepted forms are:

Option -service_selector
-service_selector
-service_selector={ID, SERVICE_MATCHER},...

Associates a selection identifier to an expression defining the matching services.

The configuration’s content is a collection of named selectors for services.

ID:

a service selection identifier.

SERVICE_MATCHER:

an expression defining the matching services. Accepted forms are:

  • [+]AND_MATCHER: the service matches AND_MATCHER

  • -AND_MATCHER: the service does not match AND_MATCHER

  • [+]AND_MATCHER||SERVICE_MATCHER: either the service matches AND_MATCHER or it matches SERVICE_MATCHER

  • -AND_MATCHER||SERVICE_MATCHER: the service does not match AND_MATCHER but does match SERVICE_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the service matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the service matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (SERVICE_MATCHER): the service matches SERVICE_MATCHER

  • !BASIC_MATCHER: the service does not match BASIC_MATCHER

  • any(): any service matches

  • none(): no service matches

  • ^REGEX$: the service id matches ^REGEX$

  • ID: the service identifier

  • tag(ID): the service tag

  • ID: the service matches the matcher associated to ID in -service_selector global configuration

REGEX

accepted forms are:

Option -stds
-stds
-stds={ID, STD_MATCHER},...

Specify the standard.

The configuration’s content is a collection of named selectors for standards.

ID:

a standard selection identifier.

STD_MATCHER:

an expression defining the matching standards. Accepted forms are:

  • [+]AND_MATCHER: the standard matches AND_MATCHER

  • -AND_MATCHER: the standard does not match AND_MATCHER

  • [+]AND_MATCHER||STD_MATCHER: either the standard matches AND_MATCHER or it matches STD_MATCHER

  • -AND_MATCHER||STD_MATCHER: the standard does not match AND_MATCHER but does match STD_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the standard matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the standard matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (STD_MATCHER): the standard matches STD_MATCHER

  • !BASIC_MATCHER: the standard does not match BASIC_MATCHER

  • any(): any standard matches

  • none(): no standard matches

  • STD: the standard is STD

  • ID: the node matches the matcher associated to ID in -stds global configuration

STD

accepted forms are:

  • c90: the C90 standard [28]

  • c95: the C95 standard [29]

  • c99: the C99 standard [31]

  • c11: the C11 standard [35]

  • c18: the C18 standard [39]

  • c++98: the C++98 standard [30]

  • c++03: the C++03 standard [32]

  • c++11: the C++11 standard [34]

  • c++14: the C++14 standard [36]

  • c++17: the C++17 standard [38]

  • c++20: the C++20 standard [40]

Default:

-stds={c, c90||c95||c99||c11||c18}, {c++, c++98||c++03||c++11||c++14||c++17||c++20||c++23}, {c90_, c90||c95||c99||c11||c18}, {c95_, c95||c99||c11||c18}, {c99_, c99||c11||c18}, {c11_, c11||c18}, {c18_, c18}, {cxx98_, c++98||c++03||c++11||c++14||c++17||c++20||c++23}, {cxx03_, c++03||c++11||c++14||c++17||c++20||c++23}, {cxx11_, c++11||c++14||c++17||c++20||c++23}, {cxx14_, c++14||c++17||c++20||c++23}, {cxx17_, c++17||c++20||c++23}, {cxx20_, c++20||c++23}, {cxx23_, c++23}
Option -stmt_selector
-stmt_selector
-stmt_selector={ID, STMT_MATCHER},...

Associates a selection identifier to an expression defining the matching expression and statement nodes.

The configuration’s content is a collection of named selectors for expression and statements.

ID:

a statement and expression selection identifier.

STMT_MATCHER:

an expression defining the matching statement and expression nodes. Accepted forms are:

  • [+]AND_MATCHER: the node matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||STMT_MATCHER: either the node matches AND_MATCHER or it matches STMT_MATCHER

  • -AND_MATCHER||STMT_MATCHER: the node does not match AND_MATCHER but does match STMT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the node matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the node matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (STMT_MATCHER): the node matches STMT_MATCHER

  • !BASIC_MATCHER: the node does not match BASIC_MATCHER

  • any(): any node matches

  • none(): no node matches

  • ^REGEX$: the node is a constant literal or references a named object whose text or name matches REGEX$

  • all_stmt(ID,ARG_RANGE,STMT_MATCHER): for a statement child ID (which should have a list of statements or expressions), all elements with indices in the range ARG_RANGE match STMT_MATCHER (note that the argument indices start at index 1 so that there is no element with index 0 and that negative range values are counted in reverse from the last argument down, e.g., -1 identifies the last argument)

  • any_stmt(ID,ARG_RANGE,STMT_MATCHER): for a statement child ID (which should have a list of statements or expressions), an element with index in the range ARG_RANGE matches STMT_MATCHER (note that the argument indices start at index 1 so that there is no element with index 0 and that negative range values are counted in reverse from the last argument down, e.g., -1 identifies the last argument)

  • asm(ASM_MATCHER): the node is a gcc asm statement matching ASM_MATCHER

  • ast_field(NAME_ID,NAME_MATCHER): an ast field NAME_ID whose value matches NAME_MATCHER

  • attribute(ATTRIBUTE[||ATTRIBUTE]*): the node a statement or expression has an attribute that is one of the ATTRIBUTE values

  • any_base(STMT_MATCHER): the expression must have at least one address base that matches STMT_MATCHER

  • begin(LOC_MATCHER): the initial location matches LOC_SELECTOR

  • call(CALL_MATCHER): the node must be a call expression matching CALL_MATCHER

  • callee(CALL_MATCHER): the node must evaluate to a function declaration matching CALL_MATCHER

  • cast(CAST_MATCHER): the node is a cast matching CAST_MATCHER

  • child(ID[||ID]*,STMT_MATCHER): there is a child matching STMT_MATCHER for a statement child that matches one of the ID

  • constant_initializer(): the node is a constant initializer

  • definitely_in(RANGE): the node has a value definitely in range RANGE

  • empty_child(ID): the node has child ID that is empty

  • end(LOC_MATCHER): the initial location matches LOC_SELECTOR

  • evaluatable(): the node is a constant expression

  • expr(): the node is an expression

  • f151_assign(): the node is an f151_assign expression

  • ice(): the node is an integer constant expression

  • inexact_literal(): the node is an inexact floating-point literal

  • kind(ID[||ID]*): the node is an expression whose ast node has a kind that is one of the ID values

  • lvalue(): the node is an lvalue expression

  • macro(MACRO_MATCHER): the node is the full expansion of a macro and matches MACRO_MATCHER (see the -macro_selector global configuration)

  • misra_boolean(): the node is a MISRA Boolean typed expression. See page 118 of MISRA-C:2004 [62] ☞ for a definition of effectively Boolean

  • misra_character(): the node is a MISRA character typed expression

  • misra_enum(): the node is a MISRA enum typed expression

  • misra_integer(): the node is a MISRA integer typed expression

  • misra_kind(MKIND): the node is MKIND

  • name(ID[||ID]*): the statement’s name matches one of the ID

  • node(ASTF[||ASTF]*): the node matches one of the AST functors

  • nullptr(): an expression with a nullptr builtin type or a null_to_pointer explicit cast expression

  • operator(ID[||ID]*): the node is an expression whose main operator matches one of the ID operators or operator categories

  • possibly_in(RANGE): the node has a value possibly in range RANGE

  • pure_decl(): the statement is a declaration that does not have any initialization

  • ref(DECL_MATCHER): the node is an expression referring to a declaration matching DECL_MATCHER (see the -decl_selector global configuration)

  • rvalue(): the node is an rvalue expression

  • save(ID,STMT_MATCHER): the statement or expression that matches STMT_MATCHER is saved with identifier ID

  • skip(STMT_MATCHER0,STMT_MATCHER1): the node, possibly wrapped with expressions matching STMT_MATCHER0, matches STMT_MATCHER1 (note that the unwrapping is greedy so that STMT_MATCHER0 is always checked before STMT_MATCHER1)

  • std(STDS_MATCHER): the standard used is STDS_MATCHER (see the -stds global configuration)

  • syntactic(): the node is syntactic

  • type(TYPE_MATCHER): the node is an expression with type matching TYPE_MATCHER (see the -type_selector global configuration)

  • wrapped(STMT_MATCHER0,STMT_MATCHER1): the node, possibly wrapped with expressions matching STMT_MATCHER0, matches STMT_MATCHER1 (note that the unwrapping is lazy so that STMT_MATCHER1 is always checked before STMT_MATCHER0)

  • ID: the node matches the matcher associated to ID in -stmt_selector global configuration

MKIND

accepted forms are:

  • mc2_complex: a MISRA-C:2004 complex expression (see page 49 MISRA-C:2004 [62] ☞, Section 6.10.5)

  • mc3_composite: a MISRA C:2012 composite expression (see page 98 of MISRA C:2012 [43] ☞, Section 8.10.3)

  • mp1_cvalue: a MISRA C++:2008 cvalue expression (see page 66 of MISRA C++:2008 [64] ☞, Section 6.5.0)

MIN_MAX

accepted forms are:

  • NUM_MINRANGE_SEPNUM_MAX: range is from NUM_MIN to NUM_MAX

  • RANGE_SEPNUM: range is all values equal or less than NUM

  • NUMRANGE_SEP: range is all values equal or more than NUM

  • NUM: range is the single value NUM

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

ASM_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the asm matches AND_MATCHER

  • -AND_MATCHER: the asm does not match AND_MATCHER

  • [+]AND_MATCHER||ASM_MATCHER: either the asm matches AND_MATCHER or it matches ASM_MATCHER

  • -AND_MATCHER||ASM_MATCHER: the asm does not match AND_MATCHER but does match ASM_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the asm matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the asm matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • volatile(): the asm is volatile

  • memory(): the asm accesses the reachable memory

CAST_MATCHER

accepted forms are:

  • [+]AND_CAST_MATCHER: the cast matches AND_CAST_MATCHER

  • -AND_CAST_MATCHER: the cast does not match AND_CAST_MATCHER

  • [+]AND_CAST_MATCHER||CAST_MATCHER: either the cast matches AND_CAST_MATCHER or it matches CAST_MATCHER

  • -AND_CAST_MATCHER||CAST_MATCHER: the cast does not match AND_CAST_MATCHER but does match CAST_MATCHER

AND_CAST_MATCHER

accepted forms are:

  • BASIC_CAST_MATCHER: the cast matches BASIC_CAST_MATCHER

  • BASIC_CAST_MATCHER&&AND_CAST_MATCHER: the cast matches BASIC_CAST_MATCHER and AND_CAST_MATCHER

BASIC_CAST_MATCHER

accepted forms are:

  • class(CAST_CLASS[||CAST_CLASS]*): the cast matches one of the cast class CAST_CLASS

  • from(type(TYPE_MATCHER)): the cast must be from an expression with type matching TYPE_MATCHER (see the -type_selector global configuration)

  • from(expr(STMT_MATCHER)): the cast must be from an expression matching STMT_MATCHER

  • to(type(TYPE_MATCHER)): the cast must be to a type matching TYPE_MATCHER (see the -type_selector global configuration)

  • kind(KIND[||KIND]*): the cast kind is one of ID

  • relation(RELATION[||RELATION]*): the cast satisfies one of RELATION

ATTRIBUTE

accepted forms are:

  • fallthrough: fallthrough

REGEX

accepted forms are:

MIN_MAX

accepted forms are:

  • NUM_MINRANGE_SEPNUM_MAX: range is from NUM_MIN to NUM_MAX

  • RANGE_SEPNUM: range is all values equal or less than NUM

  • NUMRANGE_SEP: range is all values equal or more than NUM

  • NUM: range is the single value NUM

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

ARG_RANGE

accepted forms are:

  • MINRANGE_SEPMAX: range is from MIN to MAX or, if MIN and MAX are negative and the length is L, the range is from L + MIN + 1 to L + MAX + 1

  • RANGE_SEPNUM: range is all values equal or less than NUM or, if NUM is negative and the length is L, the range is all values equal or less than L + NUM + 1

  • NUMRANGE_SEP: range is all values equal or greater than NUM or, if NUM is negative and the length is L, the range is all values equal or greater than L + NUM + 1

  • NUM: range is the single value NUM or, if NUM is negative and the length is L, the value is L + NUM + 1

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

CAST_KIND

accepted forms are:

  • no_op: no_op

  • address_space_conversion: address_space_conversion

  • array_to_pointer_decay: array_to_pointer_decay

  • atomic_to_non_atomic: atomic_to_non_atomic

  • base_to_derived: base_to_derived

  • base_to_derived_member_pointer: base_to_derived_member_pointer

  • bitcast: bitcast

  • boolean_to_signed_integral: boolean_to_signed_integral

  • builtin_function_to_pointer_decay: builtin_function_to_pointer_decay

  • constructor_conversion: constructor_conversion

  • dependent: dependent

  • derived_to_base: derived_to_base

  • derived_to_base_member_pointer: derived_to_base_member_pointer

  • dynamic: dynamic

  • floating_cast: floating_cast

  • floating_complex_cast: floating_complex_cast

  • floating_complex_to_boolean: floating_complex_to_boolean

  • floating_complex_to_integral_complex: floating_complex_to_integral_complex

  • floating_complex_to_real: floating_complex_to_real

  • floating_real_to_complex: floating_real_to_complex

  • floating_to_boolean: floating_to_boolean

  • floating_to_integral: floating_to_integral

  • function_to_pointer_decay: function_to_pointer_decay

  • integral_cast: integral_cast

  • integral_complex_cast: integral_complex_cast

  • integral_complex_to_boolean: integral_complex_to_boolean

  • integral_complex_to_floating_complex: integral_complex_to_floating_complex

  • integral_complex_to_real: integral_complex_to_real

  • integral_real_to_complex: integral_real_to_complex

  • integral_to_boolean: integral_to_boolean

  • integral_to_floating: integral_to_floating

  • integral_to_pointer: integral_to_pointer

  • lvalue_bitcast: lvalue_bitcast

  • lvalue_to_rvalue: lvalue_to_rvalue

  • member_pointer_to_boolean: member_pointer_to_boolean

  • non_atomic_to_atomic: non_atomic_to_atomic

  • null_to_member_pointer: null_to_member_pointer

  • null_to_pointer: null_to_pointer

  • pointer_to_boolean: pointer_to_boolean

  • pointer_to_integral: pointer_to_integral

  • reinterpret_member_pointer: reinterpret_member_pointer

  • to_union: to_union

  • to_void: to_void

  • unchecked_derived_to_base: unchecked_derived_to_base

  • user_defined_conversion: user_defined_conversion

  • vector_splat: vector_splat

CAST_CLASS

accepted forms are:

  • implicit: the cast is implicit

  • explicit: the cast is explicit

  • c_style: the cast is c_style

  • functional: the cast is functional

  • const: the cast is a const named cast

  • dynamic: the cast is a dynamic named cast

  • reinterpret: the cast is a reinterpret named cast

  • static: the cast is a static named cast

RELATION

accepted forms are:

  • : bigger_sizea cast to a bigger type

  • : bigger_size_pointeea cast from a pointer to another pointer with a bigger pointee

  • cast_away_const: a cast from a pointer to a const type to a pointer without the qualifier

  • cast_away_volatile: a cast from a pointer to a volatile type to a pointer without the qualifier

  • compatible_deep_unqualified: a cast from a type to a type that has the same pointee depth and where the innermost types without qualifiers are compatible

  • definitely_changes_value: a cast that definitely does change the source expression’s value

  • definitely_in_range: a cast whose cast value is definitely in the range of its type

  • definitely_out_range: a cast whose cast value is definitely out of range of its type

  • definitely_preserves_value: a cast that definitely does not change the source expression’s value

  • derived_to_virtual_base: a cast from a pointer to a class to a pointer to a virtual base class

  • enum_constant: a cast whose source expression is an enumeration constant and whose destination type is the same as the enumerator type

  • forget_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const or is void or Boolean

  • forget_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile or is void or Boolean

  • incompatible_unqualified_pointee: a cast from a pointer to a pointer with an incompatible unqualified pointee type

  • more_aligned_pointee: a cast from a pointer to a pointer with a more aligned pointee type

  • polymorphic_base_to_derived: a cast from a pointer to a base class with polymorphic type to a pointer to a derived class

  • qualification: a cast from a pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_from_void_pointee: a cast from a void pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_to_void_pointee: a cast from a pointer to void pointer where the destination pointee has all the qualifiers in the source pointee

  • same_type: a cast that does not change the type

  • same_unqualified_pointee: a cast from a pointer to a pointer with the same pointee type, ignoring any qualifications

  • signed_to_unsigned: a cast from a signed integral type to an unsigned integral type

  • unqualify_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const

  • unqualify_pointee: a cast from a pointer with a pointee type qualifier to another pointer whose pointee type does not have that qualifier

  • unqualify_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile

  • unqualify_atomic_pointee: a cast from a pointer with an _Atomic pointee type to another pointer whose pointee is not _Atomic

  • unsigned_to_signed: a cast from an unsigned integral type to a signed integral type

  • virtual_base_to_derived: a cast from a pointer to a virtual base class to a pointer to a derived class

Option -report_selector
-report_selector
-report_selector={ID, REPORT_MATCHER},...

Associates a selection identifier to an expression defining the matching reports.

The configuration’s content is a collection of named selectors for reports.

ID:

a report selection identifier.

REPORT_MATCHER:

an expression defining the matching reports. Accepted forms are:

  • [+]AND_MATCHER: the report matches AND_MATCHER

  • -AND_MATCHER: the report does not match AND_MATCHER

  • [+]AND_MATCHER||REPORT_MATCHER: either the report matches AND_MATCHER or it matches REPORT_MATCHER

  • -AND_MATCHER||REPORT_MATCHER: the report does not match AND_MATCHER but does match REPORT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the report matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the report matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (REPORT_MATCHER): the report matches REPORT_MATCHER

  • !BASIC_MATCHER: the report does not match BASIC_MATCHER

  • any(): any report matches

  • none(): no report matches

  • category(REGEX): the report category matches REGEX; note that the category depends on the service and it is reported between square brackets only if its value is non-empty; see the service descriptions for more information about this field

  • tag(ID): at least one report tag is ID

  • kind(REPORT_KIND): the report kind

  • service(SERVICE_MATCHER): the reporting service matches the SERVICE_MATCHER (see the -service_selector global configuration)

  • first_area(AREA_MATCHER): the first area matches the AREA_MATCHER (see the -area_selector global configuration)

  • all_area(AREA_MATCHER): all the areas match AREA_MATCHER (see -area_selector global configuration)

  • any_area(AREA_MATCHER): at least one of the areas matches AREA_MATCHER (see the -area_selector global configuration)

  • ID: the report matches the matcher associated to ID in -report_selector global configuration

REPORT_KIND

accepted forms are:

  • error: error report

  • violation: violation report

  • caution: caution report

  • information: information report

  • metric: metric report

REGEX

accepted forms are:

Option -tool_tag
-tool_tag
-tool_tag={TOOL_TAG, TOOL_MATCHER},...

Assign tags to the project tools.

The configuration’s content is an ordered list of pairs ([DOMAIN:]TOOL_TAG, TOOL_MATCHER) combining a tool tag with a tool matcher. The tag paired with the first tool matcher that matches the tool specification is assigned to that tool; no tag is assigned if there are no matching tool matchers.

TOOL_TAG:

the tool’s tag.

TOOL_MATCHER:

tool matcher. Accepted forms are:

  • [+]AND_MATCHER: the tool matches AND_MATCHER

  • -AND_MATCHER: the tool does not match AND_MATCHER

  • [+]AND_MATCHER||TOOL_MATCHER: either the tool matches AND_MATCHER or it matches TOOL_MATCHER

  • -AND_MATCHER||TOOL_MATCHER: the tool does not match AND_MATCHER but does match TOOL_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the tool matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the tool matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (TOOL_MATCHER): the tool matches TOOL_MATCHER

  • !BASIC_MATCHER: the tool does not match BASIC_MATCHER

  • any(): any tool matches

  • none(): no tools matches

  • language(LANGUAGE[||LANGUAGE]*): the tool is for one of the LANGUAGEs

  • std(STD_MATCHER): the tool uses a standard that matches STD_MATCHER standard (see the -stds global configuration)

  • tool(FILE_MATCHER): the tool’s file matches FILE_MATCHER (see the -file_tag global configuration)

  • version(REGEX): the tool’s version matches REGEX

  • command(REGEX): the tool’s command line matches REGEX

  • tag(ID): the tool has tag ID

LANGUAGE

accepted forms are:

  • c: the C language

  • c++: the C++ language

REGEX

accepted forms are:

Default:

-tool_tag={}
Option -type_selector
-type_selector
-type_selector={ID, TYPE_MATCHER},...

Associates a selection identifier to an expression defining the matching types.

The configuration’s content is a collection of named selectors for types.

ID:

type selection identifier.

TYPE_MATCHER:

an expression defining the matching types. Accepted forms are:

  • [+]AND_MATCHER: the type matches AND_MATCHER

  • -AND_MATCHER: the type does not match AND_MATCHER

  • [+]AND_MATCHER||TYPE_MATCHER: either the type matches AND_MATCHER or it matches TYPE_MATCHER

  • -AND_MATCHER||TYPE_MATCHER: the type does not match AND_MATCHER but does match TYPE_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the type matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the type matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (TYPE_MATCHER): the type matches TYPE_MATCHER

  • !BASIC_MATCHER: the type does not match BASIC_MATCHER

  • any(): any type matches

  • none(): no type matches

  • ^REGEX$: the type is named and the fully qualified name matches ^REGEX$

  • address(TYPE_MATCHER): the type is a pointer or reference and its addressed type matches TYPE_MATCHER

  • all_param(RANGE,TYPE_MATCHER): the type is a function where all parameters in range RANGE match TYPE_MATCHER

  • anonymous(): the type is unnamed

  • any_param(RANGE,TYPE_MATCHER): the type is a function where any parameter in range RANGE matches TYPE_MATCHER

  • arithmetic(): the type is arithmetic

  • array(TYPE_MATCHER): the type is an array of a type that matches TYPE_MATCHER

  • array_kind(ARRAY_KIND): the type is an array with kind is ARRAY_KIND

  • array_mod(ARRAY_SIZE_MOD): the type is an array with size modifier ARRAY_SIZE_MOD

  • array_qual(TYPE_QUALIFIER): the type is an array with qualification TYPE_QUALIFIER (Note: the presence of the _Atomic qualifier should be checked with the node(atomic) matcher)

  • array_size(POS_MIN_MAX): the type is an array with size in range POS_MIN_MAX

  • bitfield_signedness(BIT_SIGNEDNESS): the bitfield type has signedness BIT_SIGNEDNESS

  • builtin(BUILTIN): the type is the builtin BUILTIN

  • call(CALL_MATCHER): the type is a call to a function that matches CALL_MATCHER

  • canonical(TYPE_MATCHER): the input term’s canonical type matches TYPE_MATCHER

  • child(ID[||ID]*,TYPE_MATCHER): there is a child matching TYPE_MATCHER for a type child that matches one of the ID

  • decl(DECL_MATCHER): the type is declared and the declaration matches DECL_MATCHER

  • desugar(TYPE_MATCHER): the fully desugared type matches TYPE_MATCHER

  • exception(EXCEPT[||EXCEPT]*): the type has an exception-specifier that matches matches one of EXCEPT

  • floating(): the type is floating

  • incomplete(): the type is incomplete

  • inner(TYPE_MATCHER): the inner type matches TYPE_MATCHER

  • integral(): the type is integral

  • item(TYPE_MATCHER): after skipping any number of desugared array types, the non-array or pointer type of the innermost item matches TYPE_MATCHER TYPE_MATCHER

  • lib_builtin(LIB_BUILTIN): the type is the same as builtin LIB_BUILTIN

  • max_array(TYPE_MATCHER): an array type whose maximum level non-array type matches TYPE_MATCHER

  • max_pointer(TYPE_MATCHER): a pointer type whose maximum level pointee matches TYPE_MATCHER

  • misra_boolean(): the type is MISRA Boolean

  • node(ASTF[||ASTF]*): the type matches one of the AST functors

  • pointer(TYPE_MATCHER): the type is a pointer and its pointee type matches TYPE_MATCHER

  • promoted(BUILTIN_EXTENDED): the type is the promoted builtin BUILTIN_EXTENDED

  • qual(TYPE_QUALIFIER,TYPE_PTR_WHERE): the type at pointer depth TYPE_PTR_WHERE has a qualifier matching TYPE_QUALIFIER (Note: the presence of the _Atomic qualifier should be checked with the node(atomic) matcher)

  • record_kind(RECORD_KIND): the type is a RECORD_KIND

  • ref_specifier(REF_SPECIFIER[||REF_SPECIFIER]*): the type is a function with ref-specifier one of REF_SPECIFIER

  • return(TYPE_MATCHER): the type is a function with return type matching TYPE_MATCHER

  • save(ID,TYPE_MATCHER): the type that matches TYPE_MATCHER is saved with identifier ID

  • scalar(): the type is scalar

  • signed(): the type is signed

  • single_inheritance_hierarchy(): the type is a class with a single inheritance hierarchy

  • skip(TYPE_MATCHER0,TYPE_MATCHER1): the node, possibly wrapped with types matching TYPE_MATCHER0, matches TYPE_MATCHER1 (note that the unwrapping is greedy so that TYPE_MATCHER0 is always checked before TYPE_MATCHER1)

  • std(STDS_MATCHER): the standard used is STDS_MATCHER (see the -stds global configuration)

  • this_qual(TYPE_QUALIFIER): the type of this has a qualifier matching TYPE_QUALIFIER

  • unsigned(): the type is signed

  • variably_modified(): the type is a variably modified array

  • variadic(): the type is a variadic function

  • wrapped(TYPE_MATCHER0,TYPE_MATCHER1): the node, possibly wrapped with types matching TYPE_MATCHER0, matches TYPE_MATCHER1 (note that the unwrapping is lazy so that TYPE_MATCHER1 is always checked before TYPE_MATCHER0)

  • ID: the type matches the matcher associated to ID in -type_selector global configuration

POS_MIN_MAX

accepted forms are:

  • POS_NUM_MINRANGE_SEPPOS_NUM_MAX: range is from (non-negative) POS_NUM_MIN to POS_NUM_MAX

  • POS_NUMRANGE_SEP: range is all values equal or more than (non-negative) POS_NUM

  • POS_NUM: range is the single non-negative value POS_NUM

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

REGEX

accepted forms are:

BUILTIN

accepted forms are:

  • _Bool: _Bool

  • __int128_t: __int128_t

  • __uint128_t: __uint128_t

  • bool: bool

  • char: char

  • char8_t: char8_t

  • char16_t: char16_t

  • char32_t: char32_t

  • double: double

  • float: float

  • half: half

  • __bf16: __bf16

  • _Float16: _Float16

  • int: int

  • long double: long double

  • long long: long long

  • long: long

  • short: short

  • signed char: signed char

  • unsigned char: unsigned char

  • unsigned long long: unsigned long long

  • unsigned long: unsigned long

  • unsigned short: unsigned short

  • unsigned: unsigned

  • void: void

  • wchar_t: wchar_t

  • nullptr_t: nullptr_t

  • short _Accum: short _Accum

  • _Accum: _Accum

  • long _Accum: long _Accum

  • unsigned short _Accum: unsigned short _Accum

  • unsigned _Accum: unsigned _Accum

  • unsigned long _Accum: unsigned long _Accum

  • short _Fract: short _Fract

  • _Fract: _Fract

  • long _Fract: long _Fract

  • unsigned short _Fract: unsigned short _Fract

  • unsigned _Fract: unsigned _Fract

  • unsigned long _Fract: unsigned long _Fract

  • _Sat short _Accum: _Sat short _Accum

  • _Sat _Accum: _Sat _Accum

  • _Sat long _Accum: _Sat long _Accum

  • _Sat unsigned short _Accum: _Sat unsigned short _Accum

  • _Sat unsigned _Accum: _Sat unsigned _Accum

  • _Sat unsigned long _Accum: _Sat unsigned long _Accum

  • _Sat short _Fract: _Sat short _Fract

  • _Sat _Fract: _Sat _Fract

  • _Sat long _Fract: _Sat long _Fract

  • _Sat unsigned short _Fract: _Sat unsigned short _Fract

  • _Sat unsigned _Fract: _Sat unsigned _Fract

  • _Sat unsigned long _Fract: _Sat unsigned long _Fract

  • UNSIZED_UNSIGNED_INTEGRAL: unsigned, unsized, integral built-in

  • UNSIZED_SIGNED_INTEGRAL: signed, unsized, integral built-in

  • FLOATING: floating point built-in

UNSIZED_UNSIGNED_INTEGRAL

accepted forms are:

  • unsigned char: unsigned char

  • unsigned long long: unsigned long long

  • unsigned long: unsigned long

  • unsigned short: unsigned short

  • unsigned: unsigned

UNSIZED_SIGNED_INTEGRAL

accepted forms are:

  • signed char: signed char

  • long long: long long

  • long: long

  • short: short

  • int: int

FLOATING

accepted forms are:

  • double: double

  • long double: long double

  • float: float

  • half: half

LIB_BUILTIN

accepted forms are:

  • size_t: the underlying type of size_t

  • ssize_t: the underlying type of ssize_t

  • intmax_t: the underlying type of intmax_t

  • uintmax_t: the underlying type of uintmax_t

  • ptrdiff_t: the underlying type of ptrdiff_t

  • uptrdiff_t: the underlying type of uptrdiff_t

  • wchar_t: the underlying type of wchar_t

  • wint_t: the underlying type of wint_t

REF_SPECIFIER

accepted forms are:

  • rvalue: type is a function with ref-specifier &&

  • lvalue: type is a function with ref-specifier &

  • empty: type is a function with no ref-specifier

ARRAY_KIND

accepted forms are:

  • any: any array kind

  • incomplete: incomplete array

  • variable: variable array

  • constant: constant array

  • dependent: dependent array

TYPE_QUALIFIER

accepted forms are:

  • restrict: restrict qualifier

  • volatile: volatile qualifier

  • const: const qualifier

  • plain: no qualifier

ARRAY_SIZE_MOD

accepted forms are:

  • normal: normal

  • star: star

  • static: static

RECORD_KIND

accepted forms are:

  • class: class

  • struct: structure

  • union: union

TYPE_PTR_WHERE

accepted forms are:

  • top_level: the top level type

  • any_pointer_level: the top level type or a type at any pointee level

BIT_SIGNEDNESS

accepted forms are:

  • explicit_signed: the bitfield is explicitly signed

  • explicit_unsigned: the bitfield is explicitly unsigned

  • implementation_signed: it is implementation-defined whether the bitfield is signed

  • implementation_unsigned: it is implementation-defined whether the bitfield is unsigned

EXCEPT

accepted forms are:

  • nothrow: the nothrow exception specifier

  • throw_any: the nothrow_any exception specifier

  • unevaluated: the unevaluated exception specifier

  • uninstantiated: the uninstantiated exception specifier

  • unparsed: the unparsed exception specifier

  • throw: the throw exception specifier

  • noexcept: the noexcept exception specifier

Option -value_selector
-value_selector
-value_selector={ID, VALUE_MATCHER},...

Associates a selection identifier to an expression defining the matching report area values.

The configuration’s content is a collection of named selectors for report area values.

ID:

message value selection identifier.

VALUE_MATCHER:

an expression defining the matching values. Accepted forms are:

  • [+]AND_MATCHER: the value matches AND_MATCHER

  • -AND_MATCHER: the value does not match AND_MATCHER

  • [+]AND_MATCHER||VALUE_MATCHER: either the value matches AND_MATCHER or it matches VALUE_MATCHER

  • -AND_MATCHER||VALUE_MATCHER: the value does not match AND_MATCHER but does match VALUE_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the value matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the value matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (VALUE_MATCHER): the value matches VALUE_MATCHER

  • !BASIC_MATCHER: the value does not match BASIC_MATCHER

  • any(): any value matches

  • none(): no value matches

  • ^REGEX$: the value matches ^REGEX$

  • fmt(REGEX): value’s format label matches REGEX

  • field(ID,VALUE_MATCHER): value whose field ID matches VALUE_MATCHER

  • item(MIN_MAX,VALUE_MATCHER): value where at least one item in MIN_MAX range matches VALUE_MATCHER

  • text(TEXT): value text

  • ID: the value matches the matcher associated to ID in -value_selector global configuration

REGEX

accepted forms are:

File classification

Option -public_files
-public_files
-public_files=FILE_MATCHERS,...

Specify the files that should be considered public API files.

FILE_MATCHERS,…:

set of file matchers. Accepted members are:

  • FILE_MATCHER: a -file_tag identifier or a matcher expression whose matching files are all considered as public API files.

Default:

-public_files="kind(system||extern_c_system)"
Option -std_files
-std_files
-std_files=FILE_MATCHERS,...

Specify the files that should be considered part of the standard library. If unset, files with kind system and extern_c_system are considered as being definitely part of standard library, while other files are considered as being possibly part of standard library.

FILE_MATCHERS,…:

set of file matchers. Accepted members are:

  • FILE_MATCHER: a -file_tag identifier or a matcher expression used to select the files.

Default:

-std_files={}

Declaration properties

Option -decl_properties
-decl_properties
-decl_properties={MATCHER, {PROPERTY,...}},...

Specify a declaration’s properties.

The configuration’s content is a list of declaration specifications with known properties.

MATCHER:

decl or macro matcher. Accepted forms are:

  • <MACRO_MATCHER: the input term is a macro that matches MACRO_MATCHER (see the -macro_selector global configuration)

  • DECL_MATCHER: the input term is declaration that matches DECL_MATCHER (see the -decl_selector global configuration)

PROPERTY:

declaration property. Accepted forms are:

  • unused: declaration is considered unused

  • used: declaration is considered used

  • fixed_signature: declaration is considered to have a fixed signature

  • alloc_id(ID): declaration has allocation identifier Id

Option -default_decl_properties
-default_decl_properties
-default_decl_properties=PROPERTY,...

Specify the default properties for declarations.

The configuration’s content is list of default properties.

PROPERTY:

declaration property. Accepted forms are:

  • unused: declaration is considered unused

  • used: declaration is considered used

  • fixed_signature: declaration is considered to have a fixed signature

  • alloc_id(ID): declaration has allocation identifier Id

Default:

-default_decl_properties={}
Option -extra_definitions
-extra_definitions
-extra_definitions=MATCHERS,...

Specifies undefined entities.

MATCHERS,…:

the matcher matches the entity. Accepted members are:

  • MATCHER: the entity matches MATCHER (see -entity_selector global configuration).

Default:

-extra_definitions="visibility(program)&&all_decl(forward_decl()&&loc(top(std()))||(std(c++)&&origin(synthetic)))"
Option -extra_references
-extra_references
-extra_references={FROM_MATCH, TO_MATCH},...

Specifies functions with the functions they call.

The configuration’s content is a set of pairs of FROM and TO entities; the FROM definition calls/refers to the TO entity.

FROM_MATCH:

the referee entity matches the entity matcher FROM_MATCH (see the -entity_selector global configuration). Use an empty string as matcher if the referred entities (the ones matching TO_MATCH) are entry points or interrupt handlers.

TO_MATCH:

the referred entity matches the entity matcher TO_MATCH (see the -entity_selector global configuration).

Default:

-extra_references={"", __main_function_entity},
  {"", "any_decl(property(used))"}
Option -function_error
-function_error
-function_error={ID, WHERE, FMT, {{VALUE_TAG, VALUES, FMT},...}},...

Specify function error conditions.

The configuration’s content is a collection of named error value conditions.

ID:

a unique identifier for this caller error specification.

WHERE:

either where the value is stored or indicate that it is the returned value. Accepted forms are:

  • return_value: the error value is the called function’s return value

  • errno: the error value is the value of errno

  • STMT_MATCHER: the error value is in an expression that matches STMT_MATCHER (see the -stmt_selector global configuration)

  • prepost(STMT_MATCHER0,STMT_MATCHER1): immediately before the call, a pre-action expression matches STMT_MATCHER0 and the error value is an expression that matches STMT_MATCHER1 (see the -stmt_selector global configuration)

FMT:

format (see the -fmt template g_function_error__default_fmt) to specify the message describing WHERE.

VALUE_TAG:

the identifier for this value specification; the empty string indicates that the value is ok.

VALUES:

values that represent errors. Accepted forms are:

  • any(): any value

  • true: the Boolean value true

  • false: the Boolean value false

  • null: the null pointer

  • in(MIN_MAX): the error value is in MIN_MAX

  • not_in(MIN_MAX): the error value is not in MIN_MAX

  • return_type_cast(NUM): the type value is VALUE; if type is unsigned, then NUM is wrapped

  • STMT_MATCHER: the error value is evaluated by an expression that matches STMT_MATCHER (see the -stmt_selector global configuration)

FMT:

format (see the -fmt template g_function_error__default_fmt) to specify the message describing VALUE_TAG.

Call properties

Option -call_properties
-call_properties
-call_properties={CALL_MATCHER, {PROPERTY,...}},...

Specify a call expression’s properties.

The configuration’s content is a list of call specifications with known properties.

For each call_specification, each property should be specified at most once.

Example of usage:

-call_properties+={"name(fun)",{"pointee_write(1..3=maybe)",
                                "pointee_read(1=never&&2=maybe)"
                                "nothrow",
                                "taken(1..3=never)"}}

The above configuration informs ECLAIR that:

  • for all calls to functions named fun

    • the first 3 arguments may be written,

    • the first argument is never read,

    • the second argument may be read,

    • no exceptions are thrown and

    • the first 3 arguments are not taken

The properties const, fp_const, pure, noeffect, nothrow and any are called impact properties. There is a (transitive) relation implied for the impact properties given by:

const > fp_const > pure > noeffect > nothrow > any

where IMPACT1 > IMPACT2 signifies that IMPACT1 implies IMPACT2.

Note that if a property has impact pure (resp., const), it is assumed that the called function is pure or (resp., const) (see GCC official documentation)

Where supported by the standard, it is assumed that any properties assigned to a function using the attribute specifier always hold. For example, with the declaration:

void f() __attribute__((pure));

it is assumed that the impact pure holds for all calls to function f()

CALL_MATCHER:

a -call_selector identifier or a matcher expression used to select the calls.

PROPERTY:

call property. Accepted forms are:

  • const_pointee_read(POINTEE_RW[&&POINTEE_RW]*): indicate the read use for call arguments that correspond to parameters whose pointee types are const

  • const_pointee_write(POINTEE_RW[&&POINTEE_RW]*): indicate the write use for call arguments that correspond to parameters whose pointee types are const

  • data_kind(POS_MIN_MAX,TKIND): the call arguments or return in the specified index range POS_MIN_MAX have the specified data kind. Index 0 refers the return value, the indices of the arguments start from 1

  • errno[(MODE)]: if the argument is omitted or MODE is true, then, when an error occurs, the errno indicator will be set. If MODE is false, then the errno indicator is not set

  • error(ID[&&ID]*): function error is specified by ID

  • heap[(MODE)]: if the argument is omitted or MODE is true, then the call is considered as having the heap property. If MODE is false, then the call is considered as not having the heap property

  • ignorable_result[(MODE)]: if the argument is omitted or MODE is true, then the call is considered as having an ignorable result. If MODE is false, then the call is considered as having a non-ignorable result

  • IMPACT: the call has impact IMPACT

  • impact(IMPACT): the call has impact IMPACT

  • malloc[(MODE)]: if the argument is omitted or MODE is true, then the call is considered as having the malloc property. If MODE is false, then the call is considered as not having the malloc property

  • math_err[(MODE)]: if the argument is omitted or MODE is true, then the call is considered as possibly setting the errno indicator and/or raising a floating-point exception if an error occurs according to the value of math_errhandling. If MODE is false, then the call is considered as not setting the errno indicator and/or raising a floating-point exception. non-const

  • noeffect: like pure but can also read volatile variable not triggering side effects. This is equivalent to impact(noeffect)

  • noreturn[(MODE)]: if the argument is omitted or MODE is true, then the call is considered to be non-returning. If MODE is false, then the call is considered to be returning

  • pointee_read(POINTEE_RW[&&POINTEE_RW]*): indicate the read use for call arguments that correspond to parameters whose pointee types are non-const

  • pointee_write(POINTEE_RW[&&POINTEE_RW]*): indicate the write use for call arguments that correspond to parameters whose pointee types are non-const

  • points_to(POINTS_TO_ITEM[&&POINTS_TO_ITEM]*): all the points_to properties must hold

  • resource(RESOURCE_ITEM[,RESOURCE_ITEM]*): indicates a set of property resources that must hold

  • returned([RETURNED[&&RETURNED]*]): indicates that the specified address arguments may be returned; address arguments not listed are never returned

  • tag(Id[&&Id]*): user-defined property tags

  • taken([TAKEN[&&TAKEN]*]): indicates that the specified address arguments may be stored in objects that persist after the function has ceased to exist (excluding the returned value); address arguments not listed are never taken

POINTEE_ARG

accepted forms are:

  • POS_MIN_MAX: argument index for callee. Index 0 refers to the return value, the indices of the arguments start from 1

  • this: this argument for callee

PRE_POST

accepted forms are:

  • pre: the property holds before the call

  • post: the property holds after the call

POINTEE_LEVEL

accepted forms are:

  • *[*]*: the dereference level is shown by the number of *‘s (the default level is 1)

POINTEE

accepted forms are:

  • POS_NUM: the pointee at index POS_NUM, the indices of the arguments start from 1

  • this: this argument

POINTEE_LHS

accepted forms are:

  • static: points to static lifetime objects

  • any: points to any object

  • POINTEE_LEVELPOINTEE: the PTEE pointee and dereference level POINTEE_LEVEL

POINTEE_RHS

accepted forms are:

  • new: a pointer to a new unaliased object

  • none: not a pointer

  • null: points to null

  • static: points to static lifetime objects

  • PRE_POST(POINTEE_LEVELPOINTEE): the PTEE pointee and dereference level POINTEE_LEVEL PRE_POST

  • POINTEE_LEVELPOINTEE: the PTEE pointee and dereference level POINTEE_LEVEL PRE_POST

PRE_POST_LHS

accepted forms are:

  • POINTEE_LHS[||POINTEE_LHS]*: one of the pointees must match

  • !POINTEE_LHS[&&POINTEE_LHS]*: none of the specified pointees match

PRE_POST_RHS

accepted forms are:

  • POINTEE_RHS[||POINTEE_RHS]*: one of the pointees must match

  • !POINTEE_RHS[&&POINTEE_RHS]*: none of the specified pointees match

POINTS_TO_ITEM

accepted forms are:

  • PRE_POST(PRE_POST_LHS=PRE_POST_RHS): the pointees specified by PRE_POST_LHS has a PRE_POST relation with the pointees specified by PRE_POST_RHS. The indices start from 1

RESOURCE_ITEM

accepted forms are:

  • RESOURCE_WHERE=ID:RESOURCE_STATES0>RESOURCE_STATES1: the resource RESOURCE_WHERE with identifier ID has input state RESOURCE_STATES0 and output state RESOURCE_STATES1

RW

accepted forms are:

  • always: for pointee_read: argument pointee is expected to be fully initialized at function enter and, for pointee_write: argument pointee is fully initialized at function exit

  • maybe: for pointee_read: argument pointee may be expected to be initialized at function enter and, for pointee_write: argument pointee may be written by function body

  • never: for pointee_read: argument pointee is not expected to be initialized at function enter and, for pointee_write: argument pointee is never written by function body

POINTEE_RW

accepted forms are:

  • POINTEE_ARG=RW: the known read or write use of each argument pointee passed by reference or pointer with index in range POS_MIN_MAX or this. The indices start from 1

RESOURCE_WHERE

accepted forms are:

  • POS_NUM: if POS_NUM = 0, then the return value otherwise the argument index; the argument indices start from 1

  • ENTITY_MATCHER: an entity matching ENTITY_MATCHER (see the -entity_selector global configuration)

RESOURCE_STATES

accepted forms are:

  • ID[||ID]*: set of resource states

BOOL3

accepted forms are:

  • always: the action happens always before the function returns

  • maybe: the action might happen or not happen before the function returns

  • never: the action never happens before the function returns

MODE

accepted forms are:

  • true: the property is true

  • false: the property is false

IMPACT

accepted forms are:

  • const: call is const. That is, it is assumed that the called function is const

  • fp_const: the floating-point environment is unchanged and the call is const

  • pure: call is pure. That is, it is assumed that the called function is pure

  • noeffect: a call to a function with no external side effect. That is, it is assumed that: there are no indirect calls; any throw is caught within the function; there are no calls to new, delete, a non-trivial constructor or a destructor; it does not write to a variable that is volatile or has static storage; and it does not read from a volatile variable that triggers a side effects

  • nothrow: a call to a function for which it is assumed that any thrown exceptions are caught within the function

  • any: the call can have any impact

RETURNED

accepted forms are:

  • POINTEE_ARG=BOOL3: the arguments passed by reference or pointer with indices included in POINTEE_ARG may be returned. The indices start from 1

TAKEN

accepted forms are:

  • POINTEE_ARG=BOOL3: the arguments passed by reference or pointer with indices included in POINTEE_ARG may be taken. The indices start from 1

TKIND

accepted forms are:

  • bool: the argument is effectively boolean

  • int_bool: the argument is a boolean represented as an integer

  • int_byte: the argument is a byte represented as an integer

POS_MIN_MAX

accepted forms are:

  • POS_NUM_MINRANGE_SEPPOS_NUM_MAX: range is from (non-negative) POS_NUM_MIN to POS_NUM_MAX

  • POS_NUMRANGE_SEP: range is all values equal or more than (non-negative) POS_NUM

  • POS_NUM: range is the single non-negative value POS_NUM

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

Option -default_call_properties
-default_call_properties
-default_call_properties=PROP,...

Specify the default properties for call expressions. Default properties are not taken into account for indirect calls and call to functions listed in the -extra_definitions global configuration (whose body is not visible to ECLAIR).

The configuration’s content is a set of properties.

PROP:

call property.

Default:

-default_call_properties="const_pointee_read(1..=maybe&&this=maybe)",
  "pointee_read(1..=maybe&&this=maybe)",
  "const_pointee_write(1..=never&&this=never)",
  "pointee_write(1..=maybe&&this=maybe)"
Option -variadic_fmt
-variadic_fmt
-variadic_fmt={ID, CALL_MATCHER, {{REGEX, {{REGEX, MATCHER},...}},...}},...

Specify nonstandard format specifiers for calls to variadic functions.

The configuration’s content is list of identifiers with call matchers, format specifiers and matchers for the corresponding arguments.

ID:

identifier.

CALL_MATCHER:

a -call_selector identifier or a matcher expression used to select the calls.

REGEX:

regex to match the conversion specification from a formatting string and where the capturing groups are for texts to be matched by the argument specifiers.

REGEX:

regex matching a conversion specifier.

MATCHER:

a -stmt_selector identifier or a matcher expression used to select the arguments.

Default:

-variadic_fmt={std_print, "name(printf||fprintf||sprintf||snprintf||wprintf||fwprintf||swprintf)", {{^.*$, {}}}}, {std_scan, "name(scanf||fscanf||sscanf||wscanf||fwscanf||swscanf)", {{^.*$, {}}}}

Requirements tracking

Option -requirement_coverages
-requirement_coverages
-requirement_coverages={ID, COVERAGE_TAG, {Flags,...}},...

Specify requirement_coverages.

The configuration’s content is a collection of coverage identifiers paired with a set of requirement tags and a set of flags. The coverage identifiers are used in the declaration of requirements sets (see the -requirements global configuration content).

ID:

coverage identifier.

COVERAGE_TAG:

coverage Doxygen tag to be matched.

Flags,…:

flags. Accepted members are:

  • FLAG: flag. Accepted forms are:

  • single: the coverage comment shall refer to a single requirement

Default:

-requirement_coverages={}
Option -requirements
-requirements
-requirements={SET_ID, {REQ_TAGS,...}, {COV_IDS,...}},...

Specify requirements sets.

The configuration’s content is a collection of requirement identifiers paired with a set of requirement tags.

SET_ID:

set identifier.

REQ_TAGS,…:

requirement tags. Accepted members are:

  • REQ_TAG: requirement tag.

COV_IDS,…:

coverage identifiers. Accepted members are:

  • COV_IDS: coverage identifier.

Default:

-requirements={}
Option -requirements_list
-requirements_list
-requirements_list=REQUIREMENT_ID,...

Specify the list of requirements.

The configuration’s content is a list of identifiers that represent requirements for a software sytem.

REQUIREMENT_ID:

id for a requirement.

Default:

-requirements_list={}

Standard libraries

Option -stdlib_description
-stdlib_description
-stdlib_description={LIB, LANG, YEAR, STD, BRIEF, FULL},...

Specifies descriptions for libraries included in source code.

The configuration’s content is library descriptions.

LIB:

used library.

LANG:

language.

YEAR:

year.

STD:

the library is based on a standard that matches STD (see the -stds global configuration).

BRIEF:

brief description.

FULL:

full description.

Default:

-stdlib_description={posix, c, 1990, c90_, POSIX, "Portable Operating System Interface (POSIX.1-2008)"}
Option -stdlib_reserved
-stdlib_reserved
-stdlib_reserved={LIB, HEADER, NAME_MATCHER, ID_CLASSES, RESERVE},...

Specifies identifiers reserved by non-standard libraries that are included in source code.

The configuration’s content is library reserved identifers.

LIB:

library defined by a -stdlib.

HEADER:

regular expression or verbatim text to select the header names.

NAME_MATCHER:

a -name_selector name or a matcher expression for the identifiers, optionally preceded by a qualifier and ‘:’.

ID_CLASSES:

identifier classes. Accepted forms are:

  • any: any entity class or macro (this excludes any keyword or common_extension)

  • code: any entity class

  • keyword: any keyword

  • common_extension: any common extension

  • function(ARITY): a function with arity ARITY

  • function_like(ARITY): a function or function-like macro with arity ARITY

  • fun_macro(ARITY): a function-like macro with arity ARITY

  • ID_CLASS[||ID_CLASS]*: the identifier class is one of ID_CLASS

ID_CLASS

accepted forms are:

  • class: class name

  • enum: an enumerator name

  • enum_constant: enum_constant name

  • function: function name

  • fun_macro: function-like macro name

  • member: field name

  • namespace: namespace name

  • operator: operator name

  • pragma: pragma name

  • struct: struct name

  • union: union name

  • typedef: typedef name

  • variable: variable name

RESERVE:

when the identifier is reserved. Accepted forms are:

  • always: always reserved

  • never: never reserved

  • define: reserved except for macro #define and #undef

  • std_global: reserved in namespace std and in the global namespace

  • namespace_decl: reserved for namespace identifiers

  • decl(DECL_MATCHER[,STRING]): is reserved for identifiers with a declarations that match DECL_MATCHER (see the -decl_selector global configuration); an optional brief description for the report messages is given by STRING

  • C_CONDS[&&C_COND]*: reserved in the C language for an identifier satisfying all of C_COND

C_COND

accepted forms are:

  • file_scope: the identifier has file scope

  • external_linkage: the identifier has external linkage

  • name_space(NAME_SPACE[||NAME_SPACE]*): reserved for an identifier in one of the name spaces NAME_SPACE

NAME_SPACE

accepted forms are:

  • label: name space label

  • member: name space member

  • ordinary: name space ordinary

  • tag: name space tag

Option -stdlib
-stdlib
-stdlib=LIBRARIES,...

Specifies standard libraries included in source code.

LIBRARIES,…:

libraries used. Accepted members are:

  • LIB: used library.

Default:

-stdlib={}

Others

Option -shift_state
-shift_state
-shift_state=REGEX,...

Specifies recognized shift change characters.

The configuration’s content is a set of ranges of allowed character codes.

REGEX:

a regular expression matching shift state change characters.

Default:

-shift_state="(\\x0F|\\x0E|\\x1B\\x28|\\x1B\\x29|\\x1B\\x6E|\\x1B\\x6F|\\x8E|\\x8F)"
Option -multibyte_character_prefixes
-multibyte_character_prefixes
-multibyte_character_prefixes=REGEX,...

Specifies allowed characters.

The configuration’s content is a set of ranges of allowed character codes.

REGEX:

a regular expression matching multibyte character prefixes.

Default:

-multibyte_character_prefixes="([\\x7F-\\xFF]+)"
Option -reference_std
-reference_std
-reference_std={TAG, STD_SPEC},...

Specify the reference standard referred to by TAG.

The configuration’s content is a collection of named reference language standards.

TAG:

selection tag.

STD_SPEC:

standard expression. Accepted forms are:

  • max(STD): the oldest standard between STD and the unit standard

  • min(STD): the newest standard between STD and the unit standard

  • std(STD): the reference standard is STD

STD

accepted forms are:

  • c90: the C90 standard [28]

  • c95: the C95 standard [29]

  • c99: the C99 standard [31]

  • c11: the C11 standard [35]

  • c18: the C18 standard [39]

  • c++98: the C++98 standard [30]

  • c++03: the C++03 standard [32]

  • c++11: the C++11 standard [34]

  • c++14: the C++14 standard [36]

  • c++17: the C++17 standard [38]

  • c++20: the C++20 standard [40]

Default:

-reference_std={STD, "std()"}

Intercepting the Toolchain

One of the main strengths of ECLAIR is that it intercepts every invocation of the toolchain components (compilers, linker, assembler, librarian or archive manager) and it automatically extracts and interprets the options that the build system has passed to them. This allows for the seamless integration with any build system, whether it is makefile-based, script-based or a hybrid.

Automatic Toolchain Identification

By default, ECLAIR automatically identifies and intercepts all the toolchain components invoked by the build procedure without requiring any configuration from the user.

Manual Tool Identification

On the other hand, the high configurability of ECLAIR also allows the user to override the default and explicitly identify the toolchain components to be intercepted.

Each component of a toolchain is identified by the tool’s front end program; that is, the program that is directly invoked by the build procedure. The fact that the front end might, in turn, invoke other programs does not matter if these are not invoked directly by the build procedure. A tool can be specified in two ways: by its name or by its full path.

PATH-Based Tool Specification by Name

The front end program of a tool can be specified by name only when there is no doubt that the build procedure will invoke the correct instance of the named program, that is, the selected program will be the one contained in the first directory in PATH that contains an executable program with that name.

It must be stressed that this method of tool specification can only be used when the build procedure invokes the tool using the standard PATH-based mechanism. In case of doubt, specification by full path should be used.

Warning

It should be the case that the PATH variable that is used by all the toolchain components invocations (i.e., the processes with the toolchain components as executable name) contains as the first fragment a path ending with .eclair/<version>/bin/, otherwise the PATH-based interception will not work.

Tool Specification by Full Path

The front end program of a tool can also be specified by providing its full (absolute) path or a regular expression that matches the full path.

Tool Specification Variables

Use environment variables to tell ECLAIR which tools should be intercepted. These are:

CC_ALIASES

for the C compiler;

CXX_ALIASES

for the C++ compiler;

AS_ALIASES

for the assembler;

AR_ALIASES

for the librarian;

LD_ALIASES

for the linker;

FILEMANIP_ALIASES

for file copiers and movers such as cp, objcopy and mv;

EXTRA_ALIASES

for other tools that should be intercepted.

Such environment variables take multiple specifications (by name or by full path) separated by blank space. For example, with a Windows command-line interpreter, one could use

set CC_ALIASES=cc gcc-4.8.1 ^.*clang.*$

to tell ECLAIR to intercept PATH-based invocations of cc, gcc, and gcc-4.8.1 and intercept invocations of C compilers whose full path contains the string clang. Note that there is no need to add an executable extension to the program names because ECLAIR will use the same algorithm used by the command interpreter. Hence, in response to command cc, a program called cc.exe or cc.bat would be executed (i.e., ECLAIR will do the right thing). Of course, if you want to restrict interception to .exe files, you can use

set CC_ALIASES=cc.exe gcc.exe gcc-4.8.1.exe ^.*clang.*\.exe$

With a Bourne shell derivative one would obtain the same effect by setting the CC_ALIASES environment variable as follows:

export CC_ALIASES="cc gcc gcc-4.8.1 ^.*clang.*$"

Note that, if one or more the tool specifications contain blank spaces, quoting is necessary. For an example on Windows consider

set LD_ALIASES="path with space/lnk1" lnk2 lnk3

whereas with a Bourne shell derivative we would use

export LD_ALIASES="'path with space/lnk1' lnk2 lnk3"

Tool Exclusion Variables

Environment variables can be used also to tell ECLAIR which tools should not be intercepted. These are:

CC_NALIASES

for the C compiler;

CXX_NALIASES

for the C++ compiler;

AS_NALIASES

for the assembler;

AR_NALIASES

for the librarian;

LD_NALIASES

for the linker;

FILEMANIP_NALIASES

for file copiers and movers such as cp, objcopy and mv.

Such environment variables take multiple specifications by full paths separated by blank space.

For example, with a Bourne shell derivative, one would use

export CC_NALIASES="^.*(gcc-4\.8\.1|clang).*$"

to tell ECLAIR not to intercept invocations of C compilers whose full path contains the string gcc-4.8.1 or clang.

Note that the tool exclusion variables (*_NALIASES) take precedence over the tool selection variables (*_ALIASES).

Services

This section contains generic documentation that applies to all services integrated in the ECLAIR instance this manual refers to. A templates for the configuration of service SERVICE is provided in

PREFIX/eclair-VERSION/share/config/templates/SERVICE.ecl

In the following sections we present the services supported by this release of ECLAIR and the means to configure their behaviour.

The description of each service includes

  • a list of other services, called aliases, that have the same description as the current service and not included in the table of contents;

  • a short summary of the service: most often this is the headline under which the service is presented in the corresponding coding standard;

  • a detailed description of the service: this contains a best-effort interpretation of the service’s letter and spirit, taking into account all the available, authoritative sources of information;

  • information about the implementation: a best-effort description of what the checker actually checks (only for services where the ECLAIR checker is not exact with respect to the description);

  • information on the configuration: several services and all checkers are configurable to some extent and this part explains everything.

File portions and sources

The description section of each service clarifies, among other things, which portions of the project files and the supporting files are checked. The following terminology is used:

project file contents

This is the contents of all the files that belong to the project being checked, typically all files in the directory trees rooted into a specified set of root project directories. Note that not all these files will contain code and even those containing code might not be opened by the compiler due to the particular project configuration in force or because the build procedure decided not to (re)compile them.

external source file contents

This is the contents of all the source files that are opened by the compiler during the build process and are not project files. This includes the system header files, non-system library header files, source files of libraries that are not part of the project.

compiled file contents

This is the contents of all the source files that are opened by the compiler during the build process. This may include both project source files and external source files.

non-skipped compiled file contents

This consists of the portions of the compiled files that have not been excluded by conditional compilation directives, such as #if, #ifdef, #ifndef.

preprocessed source

This consists of all the source code output by the preprocessor during the build, which does not include comments, does not include portions excluded by conditional compilation directives, and contains the final result of macro expansion.

non-pattern source

This is the portion of the preprocessed source that does not contain the (uninstantiated) C++ templates.

pattern source

This is the portion of the preprocessed source consisting of all (uninstantiated) C++ templates.

template instances

This is the code resulting from the full instantiation of the pattern preprocessed code. Note that this code, which is the outcome of an intermediate phase of the compilation process, is not part of the preprocessed source. In other words, template instances are not (explicitly) written in the code; they are synthesized by the compiler.

object source

This is the union of the non-pattern source and template instances.

The following examples should clarify the above concepts and terminology:

 1/*
 2
 3  `project files contents':
 4    <PROJECT_ROOT>/README.txt
 5    <PROJECT_ROOT>/non_compiled.c
 6    <PROJECT_ROOT>/include/never_included.h
 7    <PROJECT_ROOT>/test.cc
 8
 9  `compiled files contents':
10    <PROJECT_ROOT>/test.cc
11    /usr/include/stdio.h
12
13  `external source files contents':
14    /usr/include/stdio.h
15
16*/
17
18/* This comment and the lines below down to #if 0 are part of
19   `non-skipped compiled file contents'.  */
20/* The preprocessed contents of /usr/include/stdio.h is part of
21   `preprocessed source'.  */
22#include <stdio.h>
23
24/* The tokens in the line after next comment are part of `preprocessed
25   source' and `non-pattern source'.  */
26double our_var;
27
28#define our_macro(x) x + 1
29
30#if 0
31/* This comment and the two lines below are *not* part of
32   `non-skipped compiled file contents'.  */
33int their_var;
34#define their_macro(x) x + 2
35#endif
36
37/* The following contents is part of `non-skipped compiled file
38   contents'.  */
39/* Macros and comments are *not* part of `preprocessed source' */
40/* The following contents (comments apart) is part of `preprocessed
41   source'.  */
42
43/* The following function declaration source is part of `non-pattern
44   source'.  */
45void f();
46
47/* The following function template source is part of `pattern
48   source'.  */
49template <typename T>
50T id(T x) {
51  return x;
52}
53
54/* The following function definition source is part of `non-pattern
55   source'.  */
56int g(int x) {
57  /* The content of the instance of function template `id'
58     instantiated with T = int by the following statement is part of
59     `template instances'.  */
60  printf("%d\n", id(x));
61}

Redundant code classification

Several services require checking for and, where necessary, reporting on specific forms of redundant code. The description and implementation sections for these services use the following terminology to indicate more precisely the exact form of redundant code being referred to:

unreachable

The code is not evaluated because, for purely syntactical or type analysis reasons (i.e., independent from the result of previous evaluations), it can not be reached by control flow; for instance:

return; unreachable();

Note that code that is unreachable following this definition will be unreachable according to the descriptions in MISRA C:2012 (see pages 40, 41 ☞ and 225, 226 ☞) of [43]. However unfeasible code as specified below, is also MISRA C:2012 unreachable.

unfeasible

The code is reachable, but not evaluated because no actual control flow that leads to it can be followed. As unfeasibility will depend on the precise values of variables used in the guards, any compile-time analysis for proving unfeasibility will be imprecise, the degree of the precision depending on the analysis technique:

  • constant: compile time constant guards are taken in account. Hence the call to unreachable() in the example below has constant unfeasibility; for example:

    if (0) unreachable();

  • type-range: the type ranges of variables in the guards are taken into account; for example:

    unsigned int u;
...
if (u < 0) unreachable();

  • value-intervals: guards value intervals are taken into account; for example:

    unsigned char uc;
...
if (uc + 1 < 1000) unreachable();

  • live-variable: live variable analysis results are taken into account; for example:

    unsigned u;
u = 3;
if (u == 0) unreachable();

  • trivial-filter: the conjunction of tests in the guards is taken into account; for example:

    int i;
...
if (i > 0 && i < 0) unreachable();
if (i > 0 && b) {
  if (i < 0) unreachable();
}

  • linear-constraints: linear constraints on the values of variables in the guards are taken into account; for example:

    int i, j;
...
if (i + j > 2 && i < 2 && j < 2) unreachable();

  • linear-congruences: linear congruence relations on the values of variables in the guards are taken into account; for example:

    unsigned u;
...
u = 2 * u;
if (u % 2) unreachable();

Note that unfeasible code as defined here will be unreachable according to the description in MISRA C:2012 (see page 40 of [43] ☞).

effectless

The code is not unfeasible, but its evaluation is redundant because it has no side effects at all; for instance:

3 + 5 * 18;
dead-effects

The code is not effectless, but its effects do not change the program semantics; for instance:

unsigned u;
...
u = 2; // dead-effects
u = 3;

Note that effectless or dead-effects code as defined here will be dead code according to the description in MISRA C:2012 (see page 41 of [43] ☞).

Configuring a service

Each service can be configured to fine-tune its behaviour according to each project’s needs. To specify such service-dependent configurations, use the option described below.

Option -config

-config

-config=TAG,OPTION=VALUE,...

where TAG is an identifier denoting a single service or a set of services to which the option applies and

OPTION=VALUE,...: a set of options with associated values.

Each OPTION must be either a generic service option or service-specific option. and VALUE a valid value for this option. In some cases, the =VALUE can be omitted and the default value true is used. For example, to enable (respectively disable) the services defined by the tag, use just the OPTION enabled (respectively, disabled).

Generic Service Options

The configuration section of the presentation of each service includes descriptions of several service-specific configure options that will enable the reports that are output to be fine-tuned to suit the project.

There are also some general configuration options that allow for service dependent control of the service checking and reporting. Other global service-independent configuration options are documented in the section Global Options.

Option enabled
enabled
-config=SERVICE,enabled=BOOL

Enable the service (see also the global configuration -enable for a shorter way to enable services).

BOOL:

the service state. Accepted values are:

  • false: the service is disabled;

  • true: the service is enabled;

Option disabled
disabled
-config=SERVICE,disabled=BOOL

Disable the service (see also the global configuration -disable for a shorter way to disable services).

BOOL:

the service state. Accepted values are:

  • false: the service is enabled;

  • true: the service is disabled;

Option summary
summary
-config=SERVICE,summary=SUMMARY

Summary for the service.

SUMMARY:

a string to be used as summary for the service.

Option strictness
strictness
-config=SERVICE,strictness=STRICTNESS

Service strictness.

STRICTNESS:

the strictness of this service.

Option tag
tag
-config=SERVICE,tag=TAG,...

List of tags associated to a specific service alias.

The configuration’s content is a list of tags associated to service.

TAG:

the tag for the service.

Option ntag
ntag
-config=SERVICE,ntag=TAG,...

List of tags associated to service without defining a preferred alias.

The configuration’s content is a list of tags associated to service.

TAG:

the tag for the service.

Option untag
untag
-config=SERVICE,untag=TAG,...

List of tags to be disassociated from the service.

The configuration’s content is user tags.

TAG:

the tag for the service.

Option reports
reports
-config=SERVICE,reports={TAGS, REPORT_MATCHER},...

Specifies the reports to hide.

The configuration’s content is a list of clauses specifying the reports and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

REPORT_MATCHER:

a -report_selector identifier or a matcher expression used to select the reports.

Option frames
frames
-config=SERVICE,frames={TAG, FRAME_MATCHER},...

Specify the interesting analysis frames using a short-circuit sequence.

The configuration’s content is a short-circuit sequence specifying the frames that should not be analyzed.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

FRAME_MATCHER:

a -frame_selector identifier or a matcher expression used to select the frames.

Option fmt
fmt
-config=SERVICE,fmt={FMT, TPL_FMT, CONTENT},...

Specify the format for the reports.

The configuration’s content is a collection of named message formats.

FMT:

format identifier.

TPL_FMT:

template identifier.

CONTENT:

format content string. Accepted forms are:

  • PARTPARTS: non empty parts

  • : empty parts

PART

accepted forms are:

  • %{EXPR}: result of EXPR

  • TEXT: text TEXT

EXPR

accepted forms are:

  • 'TEXT': text TEXT

  • n(PARAM): value of parameter PARAM

  • q(PARAM): quoted value of parameter PARAM

  • seq(EXPR,SEP): value of items in list EXPR separated by SEP

  • cond(EXPR_COND,EXPR_DEFAULT,CASES): value of EXPR_COND is tested against CASES, if nothing matches EXPR_DEFAULT is used

  • FMT(OPT_ARGS): fmt FMT is called

  • FMT(EXPROPT_COMMA_SEPOPT_COMMA_ARGS): fmt FMT is called on EXPR

  • ifmt(EXPR_FMT,IDOPT_COMMA_ARGS): fmt specified by EXPR_FMT (whose template is ID) is called

  • ifmte(EXPR_FMT,EXPR_VALUEOPT_COMMA_ARGS): fmt specified by EXPR_FMT is called on EXPR_VALUE

  • ifmts(EXPR_FMT,EXPR_SEQ,EXPR_SEPOPT_COMMA_ARGS): fmt specified by EXPR_FMT is called on sequence EXPR_SEQ using separator EXPR_SEP

OPT_ARGS

accepted forms are:

  • ID:EXPROPT_COMMA_ARGS: optional comma separated EXPR sequence

  • : no more expressions

OPT_COMMA_ARGS

accepted forms are:

  • ,OPT_ARGS: optional comma separated OPT_ARGS sequence

  • : no more args

OPT_COMMA_SEP

accepted forms are:

  • ,EXPR: comma followed by EXPR

  • : no more expressions

The BUGSENG Application Hazard Scanner Services

This section contains documentation on the Application Hazard Scanner services. These have been provided by BUGSENG to report code that is vulnerable to bugs in a build tool such as the compiler or linker.

Each of the service names is formed from the tool name and the bug’s reference tag. Thus, GCC.89698 checks for code vulnerable to the GCC bug 89698.

Rule AHS.GCC.63944

Summary

Code is vulnerable to GCC bug 63944. (See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=63944 ☞.)

Description

Partial overriding of non-constant struct/union initializers is shown.

Configuration

See generic service options.

Option diagnostics
diagnostics
-config=AHS.GCC.63944,diagnostics={TAGS, DIAG_TAG},...

Assigns report tags to the parser diagnostics.

The configuration’s content is a list of clauses specifying the diagnostics and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DIAG_TAG:

a -name_selector identifier or a matcher expression used to select the diagnostics. Accepted forms are:

  • ^REGEX$: the name matches ^REGEX$

  • !NAME_MATCHER: the name does not match NAME_MATCHER

  • TEXT: the name is TEXT

Rule AHS.GCC.89698

Summary

Code is vulnerable to GCC bug 89698. (See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=89698 ☞.)

Description

All conversions from void* to a class type that inherits from another class are reported as cautions.

Configuration

See generic service options.

Option casts
casts
-config=AHS.GCC.89698,casts={TAGS, MATCHER},...

Specifies the report tags for casts.

The configuration’s content is a list of clauses specifying the casts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MATCHER:

comma-separated sequence of cast conditions. Accepted forms are:

  • [+]AND_MATCHER: the node matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||CAST_MATCHER: either the cast matches AND_MATCHER or it matches CAST_MATCHER

  • -AND_MATCHER||CAST_MATCHER: the cast does not match AND_MATCHER but does match CAST_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the cast matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the cast matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CAST_MATCHER): the cast matches CAST_MATCHER

  • !BASIC_MATCHER: the cast does not match BASIC_MATCHER

  • any(): any cast matches

  • none(): no cast matches

  • class(CAST_CLASS): the cast class is CAST_CLASS

  • context(CONTEXT_MATCHER): the cast is in a context matching CONTEXT_MATCHER (see the -context_selector global configuration)

  • from(FROM_MATCHER): the cast whose source expression matches FROM_MATCHER

  • syntactic(FROM_MATCHER)): the cast whose syntactic source expression (i.e., after removing all non-syntactic wrappers from the source) matches FROM_MATCHER

  • kind(CAST_KIND[||CAST_KIND]*): the cast kind is one of the CAST_KIND

  • language(LANGUAGE): the language is LANGUAGE

  • to(type(TYPE_MATCHER)): the cast whose destination type is matching TYPE_MATCHER (see the -type_selector global configuration)

  • relation(RELATION[||RELATION]*): the cast satisfies one of RELATION

CAST_KIND

accepted forms are:

  • no_op: no_op

  • address_space_conversion: address_space_conversion

  • array_to_pointer_decay: array_to_pointer_decay

  • atomic_to_non_atomic: atomic_to_non_atomic

  • base_to_derived: base_to_derived

  • base_to_derived_member_pointer: base_to_derived_member_pointer

  • bitcast: bitcast

  • boolean_to_signed_integral: boolean_to_signed_integral

  • builtin_function_to_pointer_decay: builtin_function_to_pointer_decay

  • constructor_conversion: constructor_conversion

  • dependent: dependent

  • derived_to_base: derived_to_base

  • derived_to_base_member_pointer: derived_to_base_member_pointer

  • dynamic: dynamic

  • floating_cast: floating_cast

  • floating_complex_cast: floating_complex_cast

  • floating_complex_to_boolean: floating_complex_to_boolean

  • floating_complex_to_integral_complex: floating_complex_to_integral_complex

  • floating_complex_to_real: floating_complex_to_real

  • floating_real_to_complex: floating_real_to_complex

  • floating_to_boolean: floating_to_boolean

  • floating_to_integral: floating_to_integral

  • function_to_pointer_decay: function_to_pointer_decay

  • integral_cast: integral_cast

  • integral_complex_cast: integral_complex_cast

  • integral_complex_to_boolean: integral_complex_to_boolean

  • integral_complex_to_floating_complex: integral_complex_to_floating_complex

  • integral_complex_to_real: integral_complex_to_real

  • integral_real_to_complex: integral_real_to_complex

  • integral_to_boolean: integral_to_boolean

  • integral_to_floating: integral_to_floating

  • integral_to_pointer: integral_to_pointer

  • lvalue_bitcast: lvalue_bitcast

  • lvalue_to_rvalue: lvalue_to_rvalue

  • member_pointer_to_boolean: member_pointer_to_boolean

  • non_atomic_to_atomic: non_atomic_to_atomic

  • null_to_member_pointer: null_to_member_pointer

  • null_to_pointer: null_to_pointer

  • pointer_to_boolean: pointer_to_boolean

  • pointer_to_integral: pointer_to_integral

  • reinterpret_member_pointer: reinterpret_member_pointer

  • to_union: to_union

  • to_void: to_void

  • unchecked_derived_to_base: unchecked_derived_to_base

  • user_defined_conversion: user_defined_conversion

  • vector_splat: vector_splat

CAST_CLASS

accepted forms are:

  • implicit: the cast is implicit

  • explicit: the cast is explicit

  • c_style: the cast is c_style

  • functional: the cast is functional

  • const: the cast is a const named cast

  • dynamic: the cast is a dynamic named cast

  • reinterpret: the cast is a reinterpret named cast

  • static: the cast is a static named cast

RELATION

accepted forms are:

  • : bigger_sizea cast to a bigger type

  • : bigger_size_pointeea cast from a pointer to another pointer with a bigger pointee

  • cast_away_const: a cast from a pointer to a const type to a pointer without the qualifier

  • cast_away_volatile: a cast from a pointer to a volatile type to a pointer without the qualifier

  • compatible_deep_unqualified: a cast from a type to a type that has the same pointee depth and where the innermost types without qualifiers are compatible

  • definitely_changes_value: a cast that definitely does change the source expression’s value

  • definitely_in_range: a cast whose cast value is definitely in the range of its type

  • definitely_out_range: a cast whose cast value is definitely out of range of its type

  • definitely_preserves_value: a cast that definitely does not change the source expression’s value

  • derived_to_virtual_base: a cast from a pointer to a class to a pointer to a virtual base class

  • enum_constant: a cast whose source expression is an enumeration constant and whose destination type is the same as the enumerator type

  • forget_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const or is void or Boolean

  • forget_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile or is void or Boolean

  • incompatible_unqualified_pointee: a cast from a pointer to a pointer with an incompatible unqualified pointee type

  • more_aligned_pointee: a cast from a pointer to a pointer with a more aligned pointee type

  • polymorphic_base_to_derived: a cast from a pointer to a base class with polymorphic type to a pointer to a derived class

  • qualification: a cast from a pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_from_void_pointee: a cast from a void pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_to_void_pointee: a cast from a pointer to void pointer where the destination pointee has all the qualifiers in the source pointee

  • same_type: a cast that does not change the type

  • same_unqualified_pointee: a cast from a pointer to a pointer with the same pointee type, ignoring any qualifications

  • signed_to_unsigned: a cast from a signed integral type to an unsigned integral type

  • unqualify_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const

  • unqualify_pointee: a cast from a pointer with a pointee type qualifier to another pointer whose pointee type does not have that qualifier

  • unqualify_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile

  • unqualify_atomic_pointee: a cast from a pointer with an _Atomic pointee type to another pointer whose pointee is not _Atomic

  • unsigned_to_signed: a cast from an unsigned integral type to a signed integral type

  • virtual_base_to_derived: a cast from a pointer to a virtual base class to a pointer to a derived class

FROM_MATCHER

accepted forms are:

  • type(TYPE_MATCHER): the type of the source expression matches TYPE_MATCHER (see the -type_selector global configuration)

  • expr(STMT_MATCHER): the source expression matches STMT_MATCHER (see the -stmt_selector global configuration)

LANGUAGE

accepted forms are:

  • c: C

  • cpp: C++

The BUGSENG ECLAIR Services

This section contains documentation on ECLAIR services that were designed by BUGSENG in a completely independent way, that is, with no reference to existing coding standards or previous designs.

Debug B.CONST_DEBUG

Summary

Service for testing servant const.

Configuration

See generic service options.

Option declarations
declarations
-config=B.CONST_DEBUG,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Debug B.DECLFIND_PROG

Summary

Service for checking the decl matcher at link time.

Description

Pseudo checker for checking decl matchers at link time.

Configuration

See generic service options.

Option declarations
declarations
-config=B.DECLFIND_PROG,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option decl_select
decl_select
-config=B.DECLFIND_PROG,decl_select={TAG, FIXME, {EVID,...}, FMT},...

Specify declarations with formats to be reported.

TAG:

a report tag. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • error: show as error report if it matches the associated conditions;

  • caution: show as a caution report if it matches the associated conditions;

  • information: show as an information report if it matches the associated conditionsbugs will be reported as information;

  • violation: show as violation report if it matches the associated conditions;

FIXME:

a -decl_selector identifier or a matcher expression used to select the declarations.

{EVID,…}

Accepted members are:

  • redeclared: any redeclaration is included as evidence;

FMT:

format (see the -fmt global configuration content, template declslct__default_fmt).

Default:

-config=B.DECLFIND_PROG,decl_select={}
Option extra_declarations
extra_declarations
-config=B.DECLFIND_PROG,extra_declarations={FIXME, {EVID,...}},...

Specify which declarations, in addition to the non-compliant ones, must be reported for information purposes.

FIXME:

a -decl_selector identifier or a matcher expression used to select the declarations.

{EVID,…}

Accepted members are:

  • redeclared: any redeclaration is included as evidence;

Default:

-config=B.DECLFIND_PROG,extra_declarations={}

Debug B.ENTTNAME_DEBUG

Summary

Pseudo-checker for enttname servant.

Configuration

See generic service options.

Option misnamed_entity_fmt
misnamed_entity_fmt
-config=B.ENTTNAME_DEBUG,misnamed_entity_fmt={TAG, ENTITY_MATCHER, NAME_MATCHER, FMT},...

Specify entities and the misnaming matcher to be shown using a short-circuit sequence with message format.

The configuration’s content is an ordered tagged list of entity and misnaming matchers with message format; the hide-show tag and message format are associated with the first matching entity and name.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

ENTITY_MATCHER:

a -entity_selector identifier or a matcher expression used to select the entities.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

FMT:

format (see the -fmt global configuration content, template enttname__default_fmt) with fields:

node

entity description;

name

unqualified identifier;

kind

entity kind;

name_info_tag

tag returned by name matcher;

vocab_msg

vocabulary error message or ''.

Option misnamed_macro_fmt
misnamed_macro_fmt
-config=B.ENTTNAME_DEBUG,misnamed_macro_fmt={TAG, MACRO_MATCHER, NAME_MATCHER, KIND, FMT},...

Specify macro and the misnaming matcher to be shown using a short-circuit sequence with message format.

The configuration’s content is an ordered tagged list of macro, name matcher, name-flag indicating if the macro name or the parameter names should be matched, and a message format; the hide-show tag is associated with the first matching macro and macro or parameter names (depending on the name-flag).

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

KIND:

whether to check macro or macro parameters. Accepted values are:

  • macro: macro name;

  • param: macro parameter;

  • any: macro name or macro parameters;

FMT:

format (see the -fmt global configuration content, template enttname__default_fmt) with fields:

node

macro or macro parameter;

name

the identifier;

kind

entity kind;

name_info_tag

tag returned by name matcher;

vocab_msg

vocabulary error message or ‘’.

Option misnamed_entity
misnamed_entity
-config=B.ENTTNAME_DEBUG,misnamed_entity={ENTITY_MATCHER, NAME_MATCHER},...

Specify the entity and name matchers.

The configuration’s content is an ordered tagged list of entity and misnaming matchers; the hide-show tag is associated with the first matching entity and name.

ENTITY_MATCHER:

a -entity_selector identifier or a matcher expression used to select the entities.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

Option misnamed_macro
misnamed_macro
-config=B.ENTTNAME_DEBUG,misnamed_macro={MACRO_MATCHER, NAME_MATCHER, KIND},...

Specify the macro and name matchers.

The configuration’s content is an ordered tagged list of macro, name matcher and name-flag indicating if the macro name or the parameter names should be matched; the hide-show tag is associated with the first matching macro and name(s).

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

KIND:

whether to check macro or macro parameters. Accepted values are:

  • macro: macro name;

  • param: macro parameter;

  • any: macro name or macro parameters;

Option declarations
declarations
-config=B.ENTTNAME_DEBUG,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option macros
macros
-config=B.ENTTNAME_DEBUG,macros={TAGS, MACRO_MATCHER},...

Specifies the report tags for macros.

The configuration’s content is a list of clauses specifying the macros and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Option all_decls
all_decls
-config=B.ENTTNAME_DEBUG,all_decls=BOOL

Specify whether to show all or just a single representative declaration for each reported entity.

BOOL:

boolean indicating whether to show one or all declarations. Accepted values are:

  • true: show all declarations for each reported entity;

  • false: show a representative declaration for each reported entity;

Debug B.EXPR_EVALUATOR_DEBUG

Summary

Pseudo-checker for expr_evaluator.

Configuration

See generic service options.

Debug B.FQNAME_DEBUG

Summary

Pseudo-checker for fqname.

Configuration

See generic service options.

Debug B.NODESLCT

Summary

Service for checking selectors using the save options.

Description

Pseudo checker for checking decl, entity, stmt and type matchers using the save option.

Configuration

See generic service options.

Option node_select
node_select
-config=B.NODESLCT,node_select=MATCHER,...

Specify the matcher.

The configuration’s content is a list of node matchers.

MATCHER:

a node matcher. Accepted forms are:

  • decl(DECL_MATCHER): the node is a declaration that matches DECL_MATCHER> (see the -decl_selector global configuration)

  • entity(ENTITY_MATCHER): the node is an entity that matches ENTITY_MATCHER> (see the -entity_selector global configuration)

  • type(TYPE_MATCHER): the node is an expression that matches TYPE_MATCHER (see the -type_selector global configuration)

  • stmt(STMT_MATCHER): the node is a statement or expression that matches STMT_MATCHER (see the -stmt_selector global configuration)

Default:

-config=B.NODESLCT,node_select={}
Option saved_areas
saved_areas
-config=B.NODESLCT,saved_areas={ID, Selector, Loc, AKIND, FMT},...

Specify the areas (e.g., locations, area kinds and message formats) for the saved ast nodes that should be included in the report.

The configuration’s content is saved area formats.

ID:

identifier ID saved by the Selector using the basic matcher save(ID, Matcher).

Selector:

the selector where the data is saved. Accepted values are:

Loc:

what is reported and how the node is shown. Accepted forms are:

  • LKIND: the node is shown using loc-kind LKIND

  • loc(WHAT,LKIND): WHAT is shown using loc-kind LKIND

WHAT

accepted forms are:

  • node: the saved node (after dropping any non-syntactic wrappers)

  • parent: the nearest syntactic ancestor for the saved context_selector’s ancestor chain

LKIND

accepted forms are:

  • any: an appropriate part of the node’s range

  • range: the complete node range

  • begin: the first part of the node

  • name: the name of the node if it exists, otherwise the range

  • operator: the node operator if it exists, otherwise the range

AKIND:

area kind. Accepted values are:

  • culprit: culprit;

  • context: context;

  • evidence: evidence;

  • information: information;

FMT:

the message format depends on the selector:

call_selector

-fmt global configuration content, template selareas__call_default_fmt, with fields:

node_msg

the function or macro call;

call_msg

the function or macro call;

called_msg

the called function.

context_selector

-fmt global configuration content, template selareas__context_default_fmt, with fields:

node_msg

the current node;

parent_msg

the nearest syntactic ancestor;

child_kind_msg

the child relation between the node and its parent;

decl_selector

-fmt global configuration content, template selareas__decl_default_fmt, with fields:

node_msg

the declaration;

decl_msg

the declaration;

entity_msg

the entity;

type_msg

the type of the declaration (or none).

entity_selector

-fmt global configuration content, template selareas__entity_default_fmt, with fields:

node_msg

the entity;

entity_msg

the entity;

type_msg

the type of the entity (or none).

macro_selector

-fmt global configuration content, template selareas__macro_default_fmt>) with fields:

node_msg

the macro call;

stmt_msg

the expansion;

macro_id

the macro name.

stmt_selector

-fmt global configuration content, template selareas__stmt_default_fmt, with fields:

node_msg

the statement or expression;

stmt_msg

the statement (or empty string);

expr_msg

the expression (or empty string);

ref_msg

the referred entity (or empty string);

type

the type of the expression (or empty string).

class

expr or stmt.

type_selector

-fmt global configuration content, template selareas__type_default_fmt, with fields:

node_msg

the type;

type_msg

the type.

Default:

-config=B.NODESLCT,saved_areas={}

Debug B.POINTS_TO_DEBUG

Summary

Service for testing servant points_to.

Configuration

See generic service options.

Debug B.PTO_DEBUG

Summary

Pseudo-checker for debugging the points-to analyzer.

Configuration

See generic service options.

Debug B.TAKEN_DEBUG

Summary

Pseudo-checker for taken servant.

Configuration

See generic service options.

Debug B.XREF_DEBUG

Summary

Pseudo-checker for xref and xref_nodes servants.

Configuration

See generic service options.

The BUGSENG Meters

This section contains documentation for ECLAIR services for metric reporting of any selected metrics.

Meter B.METER

Summary

Supports the selection and reporting of source code metrics.

Description

Reports the source code metrics.

Note that the metric_show service configuration must be used to specify the metrics to be reported.

Configuration

See generic service options.

Option metric_default_fmt
metric_default_fmt
-config=B.METER,metric_default_fmt=FMT

Specify the default format.

FMT:

the default format (see the -fmt global configuration content, template reprtmtc__id_default_fmt) that should be used if no other format is specified; it has fields:

subject_kind

subject kind;

subject_msg

subject message;

subject_name

subject name;

subject_named

Boolean indicating if the subject has a name;

metric_id

metric identifier;

metric_summary

metric summary;

lower_case_metric_summary

metric summary in lowercase;

context_kind

context kind;

context_name

context name;

context_desc

context description;

report_where

a tag with values incremental or final indicating where the metric is reported;

domain

the environment or entity where the metric is reported;

domain_msg

a message describing the environment or entity where the metric is reported;

limit

the metric limit;

rel

the relation used to compare the limit with the metric value;

good_limit

the metric limit that must not be exceeded;

subject_eq_context

Boolean indicating if the context and subject are the same;

value

the actual value for the metric.

Default:

-config=B.METER,metric_default_fmt="%{__nolimit_fmt()}"
Option metric_fmt
metric_fmt
-config=B.METER,metric_fmt={METRIC, FMT},...

Specify metric message format.

METRIC:

name of a supported metric.

FMT:

format (see the -fmt global configuration content, template reprtmtc__id_default_fmt) with fields:

subject_kind

subject kind;

subject_msg

subject message;

subject_name

subject name;

subject_named

Boolean indicating if the subject has a name;

metric_id

metric identifier;

metric_summary

metric summary;

lower_case_metric_summary

metric summary in lowercase;

context_kind

context kind;

context_name

context name;

context_desc

context description;

report_where

is incremental or final indicating where the metric is reported;

domain

the environment or entity where the metric is reported;

domain_msg

a message describing the environment or entity where the metric is reported;

limit

the metric limit;

rel

the relation used to compare the limit with the metric value;

good_limit

the metric limit that must not be exceeded;

subject_eq_context

indicates if the context and subject are the same;

raw_value

the actual value for the metric;

value

the formatted value for the metric.

Default:

-config=B.METER,metric_fmt={}
Option metric_show
metric_show
-config=B.METER,metric_show={METRIC, LIM},...

Specify metrics to be used with hide, show or limit.

METRIC:

name of a supported metric.

LIM:

hide, show or the limit (the maximal value that is compliant) or a relation (=, <, >), followed by the value.

Default:

-config=B.METER,metric_show={}
Option metric_decimal_digits
metric_decimal_digits
-config=B.METER,metric_decimal_digits={METRIC, DEC},...

Specify the number of decimal digits shown.

The configuration’s content is list of metrics with the number of decimal digits to be shown.

METRIC:

name of a supported metric.

DEC:

the number of decimal digits. It must be an integer greater than or equal to 0.

Option declarations
declarations
-config=B.METER,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Meter B.THRESHOLD

Summary

Supports the selection and reporting of source code metrics as violations.

Description

Reports the source code metrics that reach the specified threshold.

The metrics and their thresholds are specified using the metric_show service configuration.

Configuration

See generic service options.

Option metric_fmt
metric_fmt
-config=B.THRESHOLD,metric_fmt={METRIC, FMT},...

Specify metric message format.

METRIC:

name of a supported metric.

FMT:

format (see the -fmt global configuration content, template reprtmtc__id_default_fmt) with fields:

subject_kind

subject kind;

subject_msg

subject message;

subject_name

subject name;

subject_named

Boolean indicating if the subject has a name;

metric_id

metric identifier;

metric_summary

metric summary;

lower_case_metric_summary

metric summary in lowercase;

context_kind

context kind;

context_name

context name;

context_desc

context description;

report_where

is incremental or final indicating where the metric is reported;

domain

the environment or entity where the metric is reported;

domain_msg

a message describing the environment or entity where the metric is reported;

limit

the metric limit;

rel

the relation used to compare the limit with the metric value;

good_limit

the metric limit that must not be exceeded;

subject_eq_context

indicates if the context and subject are the same;

raw_value

the actual value for the metric;

value

the formatted value for the metric.

Default:

-config=B.THRESHOLD,metric_fmt={}
Option metric_show
metric_show
-config=B.THRESHOLD,metric_show={METRIC, LIM},...

Specify metrics to be used with hide, show or limit.

METRIC:

name of a supported metric.

LIM:

hide, show or the limit (the maximal value that is compliant) or a relation (=, <, >), followed by the value.

Default:

-config=B.THRESHOLD,metric_show={}
Option metric_decimal_digits
metric_decimal_digits
-config=B.THRESHOLD,metric_decimal_digits={METRIC, DEC},...

Specify the number of decimal digits shown.

The configuration’s content is list of metrics with the number of decimal digits to be shown.

METRIC:

name of a supported metric.

DEC:

the number of decimal digits. It must be an integer greater than or equal to 0.

Option declarations
declarations
-config=B.THRESHOLD,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

The ECLAIR C/C++ Parser

Parser B.PARSER

Summary

The code shall be parsable without errors by the ECLAIR parser. If the code is parsed with errors the AST is incomplete and the results of ECLAIR analyses are likely to be incorrect.

Description

Reports any errors found when parsing the source code.

Note that, for this service, the report category is the diagnostic identifier.

Configuration

See generic service options.

Option diagnostics
diagnostics
-config=B.PARSER,diagnostics={TAGS, DIAG_TAG},...

Assigns report tags to the parser diagnostics.

The configuration’s content is a list of clauses specifying the diagnostics and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DIAG_TAG:

a -name_selector identifier or a matcher expression used to select the diagnostics. Accepted forms are:

  • ^REGEX$: the name matches ^REGEX$

  • !NAME_MATCHER: the name does not match NAME_MATCHER

  • TEXT: the name is TEXT

The BUGSENG Report Services

Reporter B.REPORT.ECB

Summary

Output reports in ECB format.

Configuration

See generic service options.

Option output
output
-config=B.REPORT.ECB,output=OUTPUT_FILE

Specify the output destinations of the reports.

OUTPUT_FILE:

the output file name. The pattern @FRAME@ is replaced with current analysis frame number.

Default:

-config=B.REPORT.ECB,output=/tmp/FRAMES.ecb
Option includes
includes
-config=B.REPORT.ECB,includes=LEVELS

Specify if the #include chains should be in the report.

LEVELS:

the number of #include chain levels to be shown.

Default:

-config=B.REPORT.ECB,includes=0
Option macros
macros
-config=B.REPORT.ECB,macros=LEVELS

Specify if the expansion chains should be output.

LEVELS:

the number of expansion chain levels to be shown.

Default:

-config=B.REPORT.ECB,macros=0
Option preprocessed
preprocessed
-config=B.REPORT.ECB,preprocessed=TAG

Specify if the preprocessed tokens should be output.

TAG:

a tag indicating if the preprocessed tokens should be shown. Accepted values are:

  • hide: preprocessed tokens are not shown;

  • show: preprocessed tokens are shown;

Default:

-config=B.REPORT.ECB,preprocessed=hide
Option presumed
presumed
-config=B.REPORT.ECB,presumed=TAG

Specify if the presumed sources should be output.

TAG:

a tag indicating if the presumed sources should be shown. Accepted values are:

  • hide: presumed sources are not shown;

  • show: presumed sources are shown;

Default:

-config=B.REPORT.ECB,presumed=hide
Option tags
tags
-config=B.REPORT.ECB,tags=TAG

Specify if the report tags and their origin should be output.

TAG:

a tag indicating if the report tags should be shown. Accepted values are:

  • hide: report tags are not shown;

  • show: report tags are shown;

Default:

-config=B.REPORT.ECB,tags=hide

Reporter B.REPORT.ERR

Summary

Output B.PARSER error reports in plain text to standard error.

Configuration

See generic service options.

Option snippet
snippet
-config=B.REPORT.ERR,snippet=NAME

Specify the format of the source text output.

NAME:

the source text output format name. Accepted forms are:

  • hide: don’t show source snippet

  • underline: show underlined source snippet

  • color: show colored source snippet

  • ID: user-defined format

Default:

-config=B.REPORT.ERR,snippet=underline
Option output
output
-config=B.REPORT.ERR,output=OUTPUT_FILE

Specify the output destinations of the reports.

OUTPUT_FILE:

the output file name. The pattern @FRAME@ is replaced with current analysis frame number.

Default:

-config=B.REPORT.ERR,output=/dev/stderr
Option includes
includes
-config=B.REPORT.ERR,includes=LEVELS

Specify if the #include chains should be in the report.

LEVELS:

the number of #include chain levels to be shown.

Default:

-config=B.REPORT.ERR,includes=0
Option macros
macros
-config=B.REPORT.ERR,macros=LEVELS

Specify if the expansion chains should be output.

LEVELS:

the number of expansion chain levels to be shown.

Default:

-config=B.REPORT.ERR,macros=10
Option preprocessed
preprocessed
-config=B.REPORT.ERR,preprocessed=TAG

Specify if the preprocessed tokens should be output.

TAG:

a tag indicating if the preprocessed tokens should be shown. Accepted values are:

  • hide: preprocessed tokens are not shown;

  • show: preprocessed tokens are shown;

Default:

-config=B.REPORT.ERR,preprocessed=hide
Option presumed
presumed
-config=B.REPORT.ERR,presumed=TAG

Specify if the presumed sources should be output.

TAG:

a tag indicating if the presumed sources should be shown. Accepted values are:

  • hide: presumed sources are not shown;

  • show: presumed sources are shown;

Default:

-config=B.REPORT.ERR,presumed=hide
Option tags
tags
-config=B.REPORT.ERR,tags=TAG

Specify if the report tags and their origin should be output.

TAG:

a tag indicating if the report tags should be shown. Accepted values are:

  • hide: report tags are not shown;

  • show: report tags are shown;

Default:

-config=B.REPORT.ERR,tags=hide

Reporter B.REPORT.TXT

Summary

Output reports in plain text.

Configuration

See generic service options.

Option snippet
snippet
-config=B.REPORT.TXT,snippet=NAME

Specify the format of the source text output.

NAME:

the source text output format name. Accepted forms are:

  • hide: don’t show source snippet

  • underline: show underlined source snippet

  • color: show colored source snippet

  • ID: user-defined format

Default:

-config=B.REPORT.TXT,snippet=underline
Option output
output
-config=B.REPORT.TXT,output=OUTPUT_FILE

Specify the output destinations of the reports.

OUTPUT_FILE:

the output file name. The pattern @FRAME@ is replaced with current analysis frame number.

Default:

-config=B.REPORT.TXT,output=/dev/stdout
Option includes
includes
-config=B.REPORT.TXT,includes=LEVELS

Specify if the #include chains should be in the report.

LEVELS:

the number of #include chain levels to be shown.

Default:

-config=B.REPORT.TXT,includes=0
Option macros
macros
-config=B.REPORT.TXT,macros=LEVELS

Specify if the expansion chains should be output.

LEVELS:

the number of expansion chain levels to be shown.

Default:

-config=B.REPORT.TXT,macros=0
Option preprocessed
preprocessed
-config=B.REPORT.TXT,preprocessed=TAG

Specify if the preprocessed tokens should be output.

TAG:

a tag indicating if the preprocessed tokens should be shown. Accepted values are:

  • hide: preprocessed tokens are not shown;

  • show: preprocessed tokens are shown;

Default:

-config=B.REPORT.TXT,preprocessed=hide
Option presumed
presumed
-config=B.REPORT.TXT,presumed=TAG

Specify if the presumed sources should be output.

TAG:

a tag indicating if the presumed sources should be shown. Accepted values are:

  • hide: presumed sources are not shown;

  • show: presumed sources are shown;

Default:

-config=B.REPORT.TXT,presumed=hide
Option tags
tags
-config=B.REPORT.TXT,tags=TAG

Specify if the report tags and their origin should be output.

TAG:

a tag indicating if the report tags should be shown. Accepted values are:

  • hide: report tags are not shown;

  • show: report tags are shown;

Default:

-config=B.REPORT.TXT,tags=hide

The BUGSENG Rules

Rule B.AUTOINIT

Summary

Service for checking defassgn and autoinit servants.

Configuration

See generic service options.

Option member_areas
member_areas
-config=B.AUTOINIT,member_areas=MAX

Specify the maximum number of uninitialized members to be shown as evidence when reporting a (possibly) uninitialized struct or a class.

MAX:

maximum number of areas in a report showing uninstantiated class or struct members. It must be an integer greater than or equal to 0.

Option declarations
declarations
-config=B.AUTOINIT,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule B.BUGFIND.apiModeling.Errno

Summary

Make the special value ‘errno’ available to other checkers.

Configuration

See generic service options.

Rule B.BUGFIND.apiModeling.TrustNonnull

Summary

Trust that returns from framework methods annotated with _Nonnull are not null.

Configuration

See generic service options.

Rule B.BUGFIND.apiModeling.TrustReturnsNonnull

Summary

Trust that returns from methods annotated with returns_nonnull are not null.

Configuration

See generic service options.

Rule B.BUGFIND.apiModeling.google.GTest

Summary

Model gtest assertion APIs.

Configuration

See generic service options.

Rule B.BUGFIND.apiModeling.llvm.CastValue

Summary

Model implementation of custom RTTIs.

Configuration

See generic service options.

Rule B.BUGFIND.apiModeling.llvm.ReturnValue

Summary

Model certain Error() methods that always return true by convention.

Configuration

See generic service options.

Rule B.BUGFIND.core.BitwiseShift

Summary

Finds cases where bitwise shift operation causes undefined behaviour.

Configuration

See generic service options.

Rule B.BUGFIND.core.BoolAssignment

Summary

Warn about assigning non-{0,1} values to Boolean variables.

Configuration

See generic service options.

Rule B.BUGFIND.core.C11Lock

Summary

Simple lock -> unlock checker.

Configuration

See generic service options.

Rule B.BUGFIND.core.CallAndMessage

Summary

Check for logical errors for function calls (e.g., uninitialized arguments, null function pointers).

Configuration

See generic service options.

Rule B.BUGFIND.core.CastToStruct

Summary

Check for cast from non-struct pointer to struct pointer.

Configuration

See generic service options.

Rule B.BUGFIND.core.Conversion

Summary

Loss of sign/precision in implicit conversions.

Configuration

See generic service options.

Rule B.BUGFIND.core.DivideZero

Summary

Check for division by zero.

Configuration

See generic service options.

Rule B.BUGFIND.core.DynamicTypeChecker

Summary

Check for cases where the dynamic and the static type of an object are unrelated.

Configuration

See generic service options.

Rule B.BUGFIND.core.DynamicTypePropagation

Summary

Generate dynamic type information.

Configuration

See generic service options.

Rule B.BUGFIND.core.EnumCastOutOfRange

Summary

Check integer to enumeration casts for out of range values.

Configuration

See generic service options.

Rule B.BUGFIND.core.FixedAddr

Summary

Check for assignment of a fixed address to a pointer.

Configuration

See generic service options.

Rule B.BUGFIND.core.FixedAddressDereference

Summary

Check for dereferences of fixed addresses.

Configuration

See generic service options.

Rule B.BUGFIND.core.NonNullParamChecker

Summary

Check for null pointers passed as arguments to a function whose arguments are references or marked with the ‘nonnull’ attribute.

Configuration

See generic service options.

Rule B.BUGFIND.core.NonnilStringConstants

Summary

Assume that const string-like globals are non-null.

Configuration

See generic service options.

Rule B.BUGFIND.core.NullDereference

Summary

Check for dereferences of null pointers.

Configuration

See generic service options.

Rule B.BUGFIND.core.NullPointerArithm

Summary

Check for undefined arithmetic operations on null pointers.

Configuration

See generic service options.

Rule B.BUGFIND.core.PointerArithm

Summary

Check for pointer arithmetic on locations other than array elements.

Configuration

See generic service options.

Rule B.BUGFIND.core.PthreadLockBase

Summary

Helper registering multiple checks.

Configuration

See generic service options.

Rule B.BUGFIND.core.StackAddressAsyncEscape

Summary

Check that addresses to stack memory do not escape the function.

Configuration

See generic service options.

Rule B.BUGFIND.core.StackAddressEscape

Summary

Check that addresses to stack memory do not escape the function.

Configuration

See generic service options.

Rule B.BUGFIND.core.StdVariant

Summary

Check for bad type access for std::variant.

Configuration

See generic service options.

Rule B.BUGFIND.core.StoreToImmutable

Summary

Check for writes to immutable memory regions. This implements part of SEI CERT Rule ENV30-C.

Configuration

See generic service options.

Rule B.BUGFIND.core.TestAfterDivZero

Summary

Check for division by variable that is later compared against 0. Either the comparison is useless or there is division by zero.

Configuration

See generic service options.

Rule B.BUGFIND.core.UndefinedBinaryOperatorResult

Summary

Check for undefined results of binary operators.

Configuration

See generic service options.

Rule B.BUGFIND.core.VLASize

Summary

Check for declarations of VLA of undefined or zero size.

Configuration

See generic service options.

Rule B.BUGFIND.core.builtin.AssumeModeling

Summary

Model compiler builtin assume functions and the assume attribute.

Configuration

See generic service options.

Rule B.BUGFIND.core.builtin.BuiltinFunctions

Summary

Evaluate compiler builtin functions (e.g., alloca()).

Configuration

See generic service options.

Rule B.BUGFIND.core.builtin.NoReturnFunctions

Summary

Evaluate “panic” functions that are known to not return to the caller.

Configuration

See generic service options.

Rule B.BUGFIND.core.uninitialized.ArraySubscript

Summary

Check for uninitialized values used as array subscripts.

Configuration

See generic service options.

Rule B.BUGFIND.core.uninitialized.Assign

Summary

Check for assigning uninitialized values.

Configuration

See generic service options.

Rule B.BUGFIND.core.uninitialized.Branch

Summary

Check for uninitialized values used as branch conditions.

Configuration

See generic service options.

Rule B.BUGFIND.core.uninitialized.CapturedBlockVariable

Summary

Check for blocks that capture uninitialized values.

Configuration

See generic service options.

Rule B.BUGFIND.core.uninitialized.NewArraySize

Summary

Check if the size of the array in a new[] expression is undefined.

Configuration

See generic service options.

Rule B.BUGFIND.core.uninitialized.UndefReturn

Summary

Check for uninitialized values being returned to the caller.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.ArrayDelete

Summary

Reports destructions of arrays of polymorphic objects that are destructed as their base class.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.ContainerModeling

Summary

Models C++ containers.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.DeleteWithNonVirtualDtor

Summary

Reports destructions of polymorphic objects with a non-virtual destructor in their base class.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.InnerPointer

Summary

Check for inner pointers of C++ containers used after re/deallocation.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.InvalidatedIterator

Summary

Check for use of invalidated iterators.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.IteratorModeling

Summary

Models iterators of C++ containers.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.IteratorRange

Summary

Check for iterators used outside their valid ranges.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.MismatchedIterator

Summary

Check for use of iterators of different containers where iterators of the same container are expected.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.Move

Summary

Find use-after-move bugs in C++.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.NewDelete

Summary

Check for double-free and use-after-free problems. Traces memory managed by new/delete.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.NewDeleteLeaks

Summary

Check for memory leaks. Traces memory managed by new/delete.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.PlacementNew

Summary

Check if default placement new is provided with pointers to sufficient storage capacity.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.PureVirtualCall

Summary

Check pure virtual function calls during construction/destruction.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.STLAlgorithmModeling

Summary

Models the algorithm library of the C++ STL.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.SelfAssignment

Summary

Checks C++ copy and move assignment operators for self assignment.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.SmartPtr

Summary

Find the dereference of null SmrtPtr.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.SmartPtrModeling

Summary

Model behavior of C++ smart pointers.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.StringChecker

Summary

Checks C++ std::string bugs.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.UninitializedObject

Summary

Reports uninitialized fields after object construction.

Configuration

See generic service options.

Rule B.BUGFIND.cplusplus.VirtualCall

Summary

Check virtual function calls during construction/destruction.

Configuration

See generic service options.

Rule B.BUGFIND.deadcode.DeadStores

Summary

Check for values stored to variables that are never read afterwards.

Configuration

See generic service options.

Rule B.BUGFIND.deadcode.UnreachableCode

Summary

Check unreachable code.

Configuration

See generic service options.

Rule B.BUGFIND.nullability.NullPassedToNonnull

Summary

Warns when a null pointer is passed to a pointer which has a _Nonnull type.

Configuration

See generic service options.

Rule B.BUGFIND.nullability.NullReturnedFromNonnull

Summary

Warns when a null pointer is returned from a function that has _Nonnull return type.

Configuration

See generic service options.

Rule B.BUGFIND.nullability.NullableDereferenced

Summary

Warns when a nullable pointer is dereferenced.

Configuration

See generic service options.

Rule B.BUGFIND.nullability.NullablePassedToNonnull

Summary

Warns when a nullable pointer is passed to a pointer which has a _Nonnull type.

Configuration

See generic service options.

Rule B.BUGFIND.nullability.NullableReturnedFromNonnull

Summary

Warns when a nullable pointer is returned from a function that has _Nonnull return type.

Configuration

See generic service options.

Rule B.BUGFIND.performance.GCDAntipattern

Summary

Check for performance anti-patterns when using Grand Central Dispatch.

Configuration

See generic service options.

Rule B.BUGFIND.performance.Padding

Summary

Check for excessively padded structs.

Configuration

See generic service options.

Rule B.BUGFIND.portability.UnixAPI

Summary

Finds dynamic memory allocation with size zero.

Configuration

See generic service options.

Rule B.BUGFIND.security.ArrayBound

Summary

Warn about out of bounds access to memory.

Configuration

See generic service options.

Rule B.BUGFIND.security.FloatLoopCounter

Summary

Warn on using a floating point value as a loop counter (CERT: FLP30-C, FLP30-CPP).

Configuration

See generic service options.

Rule B.BUGFIND.security.MmapWriteExec

Summary

Warn on mmap() calls with both writable and executable access.

Configuration

See generic service options.

Rule B.BUGFIND.security.PointerSub

Summary

Check for pointer subtractions on two pointers pointing to different memory chunks.

Configuration

See generic service options.

Rule B.BUGFIND.security.PutenvStackArray

Summary

Finds calls to the function ‘putenv’ which pass a pointer to an automatic (stack-allocated) array as the argument.

Configuration

See generic service options.

Rule B.BUGFIND.security.ReturnPtrRange

Summary

Check for an out-of-bound pointer being returned to callers.

Configuration

See generic service options.

Rule B.BUGFIND.security.SetgidSetuidOrder

Summary

Warn on possible reversed order of ‘setgid(getgid()))’ and ‘setuid(getuid())’ (CERT: POS36-C).

Configuration

See generic service options.

Rule B.BUGFIND.security.VAList

Summary

Warn on misuse of va_list objects.

Configuration

See generic service options.

Rule B.BUGFIND.security.cert.env.InvalidPtr

Summary

Finds usages of possibly invalidated pointers.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.DeprecatedOrUnsafeBufferHandling

Summary

Warn on uses of unsecure or deprecated buffer manipulating functions.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.SecuritySyntaxChecker

Summary

Base of various security function related checkers.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.UncheckedReturn

Summary

Warn on uses of functions whose return values must be always checked.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.bcmp

Summary

Warn on uses of the ‘bcmp’ function.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.bcopy

Summary

Warn on uses of the ‘bcopy’ function.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.bzero

Summary

Warn on uses of the ‘bzero’ function.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.getpw

Summary

Warn on uses of the ‘getpw’ function.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.gets

Summary

Warn on uses of the ‘gets’ function.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.mkstemp

Summary

Warn when ‘mkstemp’ is passed fewer than 6 X’s in the format string.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.mktemp

Summary

Warn on uses of the ‘mktemp’ function.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.rand

Summary

Warn on uses of the ‘rand’, ‘random’, and related functions.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.strcpy

Summary

Warn on uses of the ‘strcpy’ and ‘strcat’ functions.

Configuration

See generic service options.

Rule B.BUGFIND.security.insecureAPI.vfork

Summary

Warn on uses of the ‘vfork’ function.

Configuration

See generic service options.

Rule B.BUGFIND.taint.GenericTaint

Summary

Reports potential injection vulnerabilities.

Configuration

See generic service options.

Rule B.BUGFIND.taint.TaintPropagation

Summary

Generate taint information used by other checkers.

Configuration

See generic service options.

Rule B.BUGFIND.taint.TaintedAlloc

Summary

Check for memory allocations, where the size parameter might be a tainted (attacker controlled) value.

Configuration

See generic service options.

Rule B.BUGFIND.taint.TaintedDiv

Summary

Check for divisions where the denominator is tainted (attacker controlled) and might be 0.

Configuration

See generic service options.

Rule B.BUGFIND.unix.API

Summary

Check calls to various UNIX/Posix functions.

Configuration

See generic service options.

Rule B.BUGFIND.unix.BlockInCriticalSection

Summary

Check for calls to blocking functions inside a critical section.

Configuration

See generic service options.

Rule B.BUGFIND.unix.Chroot

Summary

Check improper use of chroot.

Configuration

See generic service options.

Rule B.BUGFIND.unix.DynamicMemoryModeling

Summary

The base of several malloc() related checkers. On its own it emits no reports, but adds valuable information to the analysis when enabled.

Configuration

See generic service options.

Rule B.BUGFIND.unix.Errno

Summary

Check for improper use of ‘errno’.

Configuration

See generic service options.

Rule B.BUGFIND.unix.Malloc

Summary

Check for memory leaks, double free, and use-after-free problems. Traces memory managed by malloc()/free().

Configuration

See generic service options.

Rule B.BUGFIND.unix.MallocSizeof

Summary

Check for dubious malloc arguments involving sizeof.

Configuration

See generic service options.

Rule B.BUGFIND.unix.MismatchedDeallocator

Summary

Check for mismatched deallocators.

Configuration

See generic service options.

Rule B.BUGFIND.unix.PthreadLock

Summary

Simple lock -> unlock checker.

Configuration

See generic service options.

Rule B.BUGFIND.unix.SimpleStream

Summary

Check for misuses of stream APIs.

Configuration

See generic service options.

Rule B.BUGFIND.unix.StdCLibraryFunctions

Summary

Check for invalid arguments of C standard library functions, and apply relations between arguments and return value.

Configuration

See generic service options.

Rule B.BUGFIND.unix.Stream

Summary

Check stream handling functions.

Configuration

See generic service options.

Rule B.BUGFIND.unix.Vfork

Summary

Check for proper usage of vfork.

Configuration

See generic service options.

Rule B.BUGFIND.unix.cstring.BadSizeArg

Summary

Check the size argument passed into C string functions for common erroneous patterns.

Configuration

See generic service options.

Rule B.BUGFIND.unix.cstring.BufferOverlap

Summary

Checks for overlap in two buffer arguments.

Configuration

See generic service options.

Rule B.BUGFIND.unix.cstring.CStringModeling

Summary

The base of several CString related checkers. On its own it emits no reports, but adds valuable information to the analysis when enabled.

Configuration

See generic service options.

Rule B.BUGFIND.unix.cstring.NotNullTerminated

Summary

Check for arguments passed to C string functions which are not null-terminated strings.

Configuration

See generic service options.

Rule B.BUGFIND.unix.cstring.NullArg

Summary

Check for null pointers being passed as arguments to C string functions.

Configuration

See generic service options.

Rule B.BUGFIND.unix.cstring.OutOfBounds

Summary

Check for out-of-bounds access in string functions.

Configuration

See generic service options.

Rule B.BUGFIND.unix.cstring.UninitializedRead

Summary

Checks if the string manipulation function would read uninitialized bytes.

Configuration

See generic service options.

Rule B.CALL.noeffect

Summary

Reports functions declared with wrong or missing effects-related property.

Description

The service reports each function not labelled with the strictest possible pureness impact property or functions labelled with a not-respected pureness property.

The pureness impact properties are:

  • noeffect;

  • pure;

  • fp_const;

  • const.

In particular the service reports:

  • if a function is declared noeffect and:

    • calls a function not declared noeffect;

    • has indirect calls;

    • may throw an exception that is not caught within the function;

    • calls new, delete, a non-trivial constructor or a destructor;

    • writes to a variable that is volatile or has static storage; or

    • reads a volatile variable that triggers side effects;

  • if a function is declared pure:

    • all the situations reported for noeffect;

    • if it calls functions not being pure;

    • if it reads from a volatile variable;

  • if a function is declared const:

    • all the situations reported for pure;

    • if it calls functions not being const;

    • if it read a variable without automatic storage;

  • conversions from a certain function type to another with a less strict property that does not concern formal parameters types in function overridings (contravariance principle).

  • in conversion between formal parameters types due to function overloading, any conversion from a certain function type to another with a stricter property.

Notes:

  • where supported by the standard, the pureness properties pure and const can be assigned to a function using the attribute specifier. For example:

void f() __attribute__((pure));

  • alternatively, a function can be assigned a property using -call_properties global configuration. For example:

-call_properties+={"type(^pure_fun_t$)", {pure}}
-call_properties+={"name(no_effect_f)", {noeffect}}

  • any overriding of a virtual function inherits the property of the overridden function.

  • destructors and virtual non-final methods are not checked;

  • the impacts service configuration can be used to tag reports for functions where the pureness property of the body is stricter than the declared property.

Imprecision

if the analyzer is uncertain whether a type that does not have the noeffect property could be converted to a function type with the noeffect property

A call to a function not declared noeffect is considered a side effect even if, with the given arguments, it cannot cause any observable side effects.

Configuration

See generic service options.

Option impacts
impacts
-config=B.CALL.noeffect,impacts={TAGS, PROP_MATCHER},...

Associates a set of tags to a matching pair of impact properties (the function’s declared impact and the inferred body’s impact).

The configuration’s content is list of pairs of a set of report taggers with a impacts matcher.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

PROP_MATCHER:

an expression defining the matching impacts. Accepted forms are:

  • [+]AND_MATCHER: the property pair matches AND_MATCHER

  • -AND_MATCHER: the property pair does not match AND_MATCHER

  • [+]AND_MATCHER||PROP_MATCHER: either the property pair matches AND_MATCHER or it matches PROP_MATCHER

  • -AND_MATCHER||PROP_MATCHER: the property pair does not match AND_MATCHER but does match PROP_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the property pair matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the property pair matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (PROP_MATCHER): the property pair matches PROP_MATCHER

  • !BASIC_MATCHER: the property pair does not match BASIC_MATCHER

  • any(): any property pair matches

  • none(): no property pair matches

  • decl([REL]IMPACTS): the declared property must be in a strictness relation REL with IMPACTS; if no relation is specified, the declared property must be the same as IMPACTS

  • body([REL]IMPACTS): the body’s property must be in a strictness relation REL with IMPACTS; if no relation is specified, the body’s property must be the same as IMPACTS

IMPACTS

accepted forms are:

  • IMPACT[||IMPACT]*): one of the IMPACTs

IMPACT

accepted forms are:

  • const: call is const. That is, it is assumed that the called function is const

  • fp_const: the floating-point environment is unchanged and the call is const

  • pure: call is pure. That is, it is assumed that the called function is pure

  • noeffect: a call to a function with no external side effect. That is, it is assumed that: there are no indirect calls; any throw is caught within the function; there are no calls to new, delete, a non-trivial constructor or a destructor; it does not write to a variable that is volatile or has static storage; and it does not read from a volatile variable that triggers a side effects

  • nothrow: a call to a function for which it is assumed that any thrown exceptions are caught within the function

  • any: the call can have any impact

REL

accepted forms are:

  • =: the same

  • >: less strict

  • >=: the same or less strict

  • <: stricter

  • <=: the same or stricter

Default:

-config=B.CALL.noeffect,impacts={hide, "body(noeffect)"}
Option declarations
declarations
-config=B.CALL.noeffect,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule B.CALL.nothrow

Summary

Reports functions with wrong nothrow property.

Description

The service reports each function labelled with the nothrow impact property:

  • if it has an uncaught throw;

  • if it calls a function that does not have the nothrow property and does not have a catch-all for that call;

  • if a type that does not have the nothrow property is converted to a function type with the nothrow property.

Notes:

  • A function has the impact property nothrow if it is declared with a noexcept-specifier to not throw exceptions or it is specified as nothrow using -call_properties global configuration;

  • A destructor could be called implicitly from stack deallocation, if it occurs after the completing the initialization of an exception object but before activation of a handler for the exception and cause a call to terminate(). For this reason, the service reports all the destructors with possible exceptions.

  • the impacts service configuration can be used to tag reports about functions where the declared property is less strict than the body’s property

Using the default configuration of the impacts service configuration, functions with the nothrow property, but not declared as such are not reported. This can be changed by setting the properties service configuration.

Imprecision

The following cases are reported as cautions if not handled with a catch-all block:

  • implicit and explicit calls to functions that do not have the property nothrow;

  • implicit calls to destructors due to the stack deallocation;

  • typeid expressions on polymorphic arguments;

  • dynamic_cast expressions.

  • if the analyzer is uncertain whether a type that does not have the nothrow property could be converted to a function type with the nothrow property

Configuration

See generic service options.

Option impacts
impacts
-config=B.CALL.nothrow,impacts={TAGS, PROP_MATCHER},...

Associates a set of tags to a matching pair of impact properties (the function’s declared impact and the inferred body’s impact).

The configuration’s content is list of pairs of a set of report taggers with a impacts matcher.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

PROP_MATCHER:

an expression defining the matching impacts. Accepted forms are:

  • [+]AND_MATCHER: the property pair matches AND_MATCHER

  • -AND_MATCHER: the property pair does not match AND_MATCHER

  • [+]AND_MATCHER||PROP_MATCHER: either the property pair matches AND_MATCHER or it matches PROP_MATCHER

  • -AND_MATCHER||PROP_MATCHER: the property pair does not match AND_MATCHER but does match PROP_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the property pair matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the property pair matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (PROP_MATCHER): the property pair matches PROP_MATCHER

  • !BASIC_MATCHER: the property pair does not match BASIC_MATCHER

  • any(): any property pair matches

  • none(): no property pair matches

  • decl([REL]IMPACTS): the declared property must be in a strictness relation REL with IMPACTS; if no relation is specified, the declared property must be the same as IMPACTS

  • body([REL]IMPACTS): the body’s property must be in a strictness relation REL with IMPACTS; if no relation is specified, the body’s property must be the same as IMPACTS

IMPACTS

accepted forms are:

  • IMPACT[||IMPACT]*): one of the IMPACTs

IMPACT

accepted forms are:

  • const: call is const. That is, it is assumed that the called function is const

  • fp_const: the floating-point environment is unchanged and the call is const

  • pure: call is pure. That is, it is assumed that the called function is pure

  • noeffect: a call to a function with no external side effect. That is, it is assumed that: there are no indirect calls; any throw is caught within the function; there are no calls to new, delete, a non-trivial constructor or a destructor; it does not write to a variable that is volatile or has static storage; and it does not read from a volatile variable that triggers a side effects

  • nothrow: a call to a function for which it is assumed that any thrown exceptions are caught within the function

  • any: the call can have any impact

REL

accepted forms are:

  • =: the same

  • >: less strict

  • >=: the same or less strict

  • <: stricter

  • <=: the same or stricter

Default:

-config=B.CALL.nothrow,impacts={hide, "any()"}
Option declarations
declarations
-config=B.CALL.nothrow,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule B.CFBODY

Summary

Uncontrolled function bodies are shown.

Configuration

See generic service options.

Rule B.CMNTVCBL

Summary

The vocabulary used for code comments should be precisely defined in a way that is amenable to automatic checking.

Description

Reports if code comments do not use the defined vocabulary. See vocabulary for more information about the vocabulary dictionaries and their use

Configuration

See generic service options.

Option good_words_file
good_words_file
-config=B.CMNTVCBL,good_words_file=GOOD_WORDS

A file containing a list of words, one per line, all in lowercase, that can be used in the project (see string interpolation clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

GOOD_WORDS:

good words filename.

Default:

-config=B.CMNTVCBL,good_words_file=""
Option bad_words_file
bad_words_file
-config=B.CMNTVCBL,bad_words_file=BAD_WORDS

A file containing a list of words, one per line, all in lowercase, that cannot be used in the project (see string interpolatn clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

BAD_WORDS:

bad words filename.

Default:

-config=B.CMNTVCBL,bad_words_file=""
Option good_items_file
good_items_file
-config=B.CMNTVCBL,good_items_file=GOOD_ITEMS

A file containing a list of lexical items, one per line, that can be used in the project (see string interpolation clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

GOOD_ITEMS:

good items filename.

Default:

-config=B.CMNTVCBL,good_items_file=""
Option bad_items_file
bad_items_file
-config=B.CMNTVCBL,bad_items_file=BAD_ITEMS

A file containing a list of lexical items, one per line, that cannot be used in the project (see string interpolation clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

BAD_ITEMS:

bad items filename.

Default:

-config=B.CMNTVCBL,bad_items_file=""
Option good_item_regexs
good_item_regexs
-config=B.CMNTVCBL,good_item_regexs=GOOD_REGEX,...

A list of regular expressions matching good identifiers. For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

{GOOD_REGEX,…}:

regular expressions matching good identifiers. Accepted members are:

Default:

-config=B.CMNTVCBL,good_item_regexs={}
Option bad_item_regexs
bad_item_regexs
-config=B.CMNTVCBL,bad_item_regexs=BAD_REGEX,...

A list of regular expressions matching bad identifiers. For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

{BAD_REGEX,…}:

regular expressions matching bad identifiers. Accepted members are:

Default:

-config=B.CMNTVCBL,bad_item_regexs={}
Option project_dictionary
project_dictionary
-config=B.CMNTVCBL,project_dictionary=PROJECT_DICT

The dictionary contains a list of words in lowercase that can be used in the project along with their frequencies (see string interpolation clause for how to specify the file).

PROJECT_DICT:

project dictionary filename.

Default:

-config=B.CMNTVCBL,project_dictionary=""
Option context_dictionary
context_dictionary
-config=B.CMNTVCBL,context_dictionary=CONTEXT_DICT

The dictionary contains a list of words in lowercase along with their frequencies (see string interpolation clause for how to specify the file). Note that the words and their frequencies are only used to assist the segmentation process.

CONTEXT_DICT:

context dictionary filename.

Default:

-config=B.CMNTVCBL,context_dictionary=""
Option splitter_regexs
splitter_regexs
-config=B.CMNTVCBL,splitter_regexs=SPLITTER,...

A list of regular expressions defining custom splitters.

{SPLITTER,…}:

set of regular expressions defining custom splitters. Accepted members are:

Default:

-config=B.CMNTVCBL,splitter_regexs={}
Option segmentation_stops_after
segmentation_stops_after
-config=B.CMNTVCBL,segmentation_stops_after=SAMURAI

Last step of the Samurai segmentation algorithm to be executed.

SAMURAI:

last step of the Samurai segmentation algorithm to be executed. Accepted values are:

  • none: no segmentation even on non-alpha characters;

  • underscore: segment on underscore characters;

  • non_alpha: segment on non-alpha characters;

  • lower_to_upper: segment on non-alpha and a change from lowercase to uppercase;

  • camel_case: segment on non-alpha, a change from lowercase to uppercase, and camel case;

  • no_case: segment on non-alpha, a change from lowercase to uppercase, camel case, and a score-based heuristics that is independent of any case consideration unless the word length exceeds the max-no-case-length value;

Default:

-config=B.CMNTVCBL,segmentation_stops_after=camel_case
Option max_no_case_length
max_no_case_length
-config=B.CMNTVCBL,max_no_case_length=MAX_LEN

The maximum length of a string upon which the “no case” step of the Samurai segmentation algorithm is applied.

MAX_LEN:

maximum string length for “no case” segmentation. It must be an integer greater than or equal to 2.

Default:

-config=B.CMNTVCBL,max_no_case_length=16
Option comment_regexs
comment_regexs
-config=B.CMNTVCBL,comment_regexs=SPLITTER,...

A list of regular expressions defining comment splitters.

{SPLITTER,…}:

set of regular expressions defining custom splitters. Accepted members are:

  • SPLITTER: regular expression defining a custom splitter.

Option ignored_comments
ignored_comments
-config=B.CMNTVCBL,ignored_comments=COMMENT_MATCHER,...

Specify the comments that should be ignored.

The configuration’s content is a list of comment matchers.

COMMENT_MATCHER:

a -comment_selector identifier or a matcher expression used to select the comments.

Option comments
comments
-config=B.CMNTVCBL,comments={TAGS, COMMENT_MATCHER},...

Specifies the report tags for comments.

The configuration’s content is a list of clauses specifying the comments and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

COMMENT_MATCHER:

a -comment_selector identifier or a matcher expression used to select the comments.

Rule B.CMPREXPR-01

Summary

In an equality test, if the second operand is not an lvalue then the first operand is not an lvalue.

Configuration

See generic service options.

Option statements
statements
-config=B.CMPREXPR-01,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Option contexts
contexts
-config=B.CMPREXPR-01,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Rule B.CMPREXPR-02

Summary

String literals shall not be arguments of relational and equality operators.

Configuration

See generic service options.

Option statements
statements
-config=B.CMPREXPR-02,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Option contexts
contexts
-config=B.CMPREXPR-02,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Rule B.COLLDICT

Summary

Collects dictionaries to be used for defining and checking program vocabularies.

Description

Collects the project vocabulary and creates a dictionary. See vocabulary for more information about the vocabulary dictionaries and their use

Configuration

See generic service options.

Option output_dictionary
output_dictionary
-config=B.COLLDICT,output_dictionary=OUTPUT_DICT

The output dictionary: for outputting the collected list of words used in the project, along with their frequencies.

OUTPUT_DICT:

output dictionary filename.

Default:

-config=B.COLLDICT,output_dictionary=""
Option project_dictionary
project_dictionary
-config=B.COLLDICT,project_dictionary=PROJECT_DICT

The dictionary contains a list of words in lowercase that can be used in the project along with their frequencies (see string interpolation clause for how to specify the file).

PROJECT_DICT:

project dictionary filename.

Default:

-config=B.COLLDICT,project_dictionary=""
Option context_dictionary
context_dictionary
-config=B.COLLDICT,context_dictionary=CONTEXT_DICT

The dictionary contains a list of words in lowercase along with their frequencies (see string interpolation clause for how to specify the file). Note that the words and their frequencies are only used to assist the segmentation process.

CONTEXT_DICT:

context dictionary filename.

Default:

-config=B.COLLDICT,context_dictionary=""
Option splitter_regexs
splitter_regexs
-config=B.COLLDICT,splitter_regexs=SPLITTER,...

A list of regular expressions defining custom splitters.

{SPLITTER,…}:

set of regular expressions defining custom splitters. Accepted members are:

Default:

-config=B.COLLDICT,splitter_regexs={}
Option segmentation_stops_after
segmentation_stops_after
-config=B.COLLDICT,segmentation_stops_after=SAMURAI

Last step of the Samurai segmentation algorithm to be executed.

SAMURAI:

last step of the Samurai segmentation algorithm to be executed. Accepted values are:

  • none: no segmentation even on non-alpha characters;

  • underscore: segment on underscore characters;

  • non_alpha: segment on non-alpha characters;

  • lower_to_upper: segment on non-alpha and a change from lowercase to uppercase;

  • camel_case: segment on non-alpha, a change from lowercase to uppercase, and camel case;

  • no_case: segment on non-alpha, a change from lowercase to uppercase, camel case, and a score-based heuristics that is independent of any case consideration unless the word length exceeds the max-no-case-length value;

Default:

-config=B.COLLDICT,segmentation_stops_after=camel_case
Option max_no_case_length
max_no_case_length
-config=B.COLLDICT,max_no_case_length=MAX_LEN

The maximum length of a string upon which the “no case” step of the Samurai segmentation algorithm is applied.

MAX_LEN:

maximum string length for “no case” segmentation. It must be an integer greater than or equal to 2.

Default:

-config=B.COLLDICT,max_no_case_length=16

Rule B.DIAGNOSTICS

Summary

Service for parsing toolchain diagnostic messages.

Description

Service for parsing toolchain components diagnostics messages.

This service converts toolchain components diagnostics messages (e.g., warnings and errors) emitted to standard output and standard error streams into ECLAIR reports. Tool warnings are reported as a caution report and errors are reported as a violation report.

Optionally, the generated reports may be tagged using a ready-made recipe:

-eval_file=DIAGNOSTICS.ecl

This recipe will add tags to the generated reports based on the command line option (if available) that enables that warning or error; this feature is typically found in compilers.

Configuration

See generic service options.

Option report_grammar
report_grammar
-config=B.DIAGNOSTICS,report_grammar=GRAM

Specify the grammar to be used to parse input files.

GRAM:

grammar identifier.

Option grammar_globals
grammar_globals
-config=B.DIAGNOSTICS,grammar_globals={var_name, var_value},...

Specify global variables for the grammar.

The configuration’s content is a list of name-value pairs for global variables.

var_name:

the name of the global variable.

var_value:

the value of the global variable.

Default:

-config=B.DIAGNOSTICS,grammar_globals={}
Option sel_frames
sel_frames
-config=B.DIAGNOSTICS,sel_frames=FRAME_MATCHER,...

Specify which frames should be processed.

The configuration’s content is a list of frame selectors to be applied.

FRAME_MATCHER:

a -frame_selector matcher expression used to select frames.

Default:

-config=B.DIAGNOSTICS,sel_frames="any()"
Option grammar
grammar
-config=B.DIAGNOSTICS,grammar={ID, {ACTION,...}},...

Specify the grammar clauses.

The configuration’s content is a list of grammar clauses associated to non-terminals.

ID:

the non-terminal identifier.

ACTION:

the action specifier text and the destination of related value. Accepted forms are:

  • OPT_DESTS[NUM]^REGEX: the text should match ^REGEX, the consumed text ends at group OPT_NUM (default 0), matched groups are assigned to OPT_DESTS

  • OPT_DESTSID(OPT_ARGS): the non-terminal or builtin action ID is performed using arguments OPT_ARGS and its matches assigned to OPT_DESTS

  • OPT_DESTSARG: the argument ARG is assigned to OPT_DESTS

OPT_DESTS

accepted forms are:

  • [DEST[,]*]DEST_OP: update the optional list of destinations DEST according to the associated operator DEST_OP; if DEST has multiple destinations and DEST_OP is a relational operator, the result is the conjunction of the operator applied to each destination

  • DESTDEST_OP: update the destination DEST according to the associated DEST_OP; if DEST has multiple destinations and DEST_OP is a relational operator, the result is the conjunction of the operator applied to each destination

DEST

accepted forms are:

  • VAR: the destination is the grammar variable VAR

  • @: the value produced by the action is returned

DEST_OP

accepted forms are:

  • =: assign the result of the action to the destination

  • +=: append the result of the action to the destination if the destination is a list; otherwise, adds the numeric value

  • -=: subtracts the result of the action from the destination (only numeric values are allowed)

  • ==: the destination is equal to the result of the action (fails if either variable is undefined)

  • !=: the destination is not equal to the result of the action (this succeeds if either argument is an undefined variable)

  • <: the destination is less than the result of the action (only numeric values are allowed)

  • <=: the destination is less than or equal to the result of the action (only numeric values are allowed)

  • >: the destination is greater than the result of the action (only numeric values are allowed)

  • >=: the destination is greater than or equal to the result of the action (only numeric values are allowed)

OPT_ARGS

accepted forms are:

  • [ARG][ARG,]*: arguments list

  • : no arguments

ARG

accepted forms are:

  • NUM: argument is an integer

  • "STRING": argument is a quoted string

  • VAR: argument is a variable

  • [OPT_ARGS]: argument is a list of arguments

VAR

accepted forms are:

  • @ID: the variable is global

  • ID: the variable is local

REGEX

accepted forms are:

Option input_files
input_files
-config=B.DIAGNOSTICS,input_files=FILE,...

Specify the list of input files.

The configuration’s content is a list of input files.

FILE:

input file path.

Default:

-config=B.DIAGNOSTICS,input_files=stdout, stderr

Rule B.ECLRVLDT

Summary

Files not validated by ECLAIR with the given configuration are shown.

Configuration

See generic service options.

Rule B.ENTTRFRN

Summary

A program should not contain unreferenced entities.

Description

Every project must define all (documented and undocumented) entry points using the -extra_references global configuration.

Reports entities that are unused or unreferenced where:

  • an entity is referenced if (apart from its definition) it appears in the program code;

  • an entity is used if is referenced from an entry point entity or an ancestor entity or an entity already found to be used.

Implementation

An entity can be shown during unit work if its visibility is not the whole program.

Configuration

See generic service options.

Option declarations
declarations
-config=B.ENTTRFRN,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option all_decls
all_decls
-config=B.ENTTRFRN,all_decls=BOOL

Specify whether to show all or just a single representative declaration for each reported entity.

BOOL:

boolean indicating whether to show one or all declarations. Accepted values are:

  • true: show all declarations for each reported entity;

  • false: show a representative declaration for each reported entity;

Rule B.EXPRPRNS

Summary

Parentheses shall be used in expressions to clarify code.

Configuration

See generic service options.

Option trusted_pairs
trusted_pairs
-config=B.EXPRPRNS,trusted_pairs={TAGS, PAIRS},...

Specify the tags for trusted pairs of main and child operators.

The configuration’s content is a set of tagged main and child operator pairs.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

PAIRS:

the main and child operator trusted pair. Accepted forms are:

  • OP_PAIR[||OP_PAIR]*: main and child operator pairs

OP_PAIR

accepted forms are:

  • OPERATOR_TAG1:OPERATOR_TAG2: main and child operator pair

OPERATOR_TAG

accepted forms are:

  • arrow: -> member designation operator

  • dot: . member designation operator

  • arrow_star: ->* pointer to member operator

  • dot_star: .* pointer to member operator

  • addrof: & address-of operator

  • co_await: co_await operator

  • deref: * indirection operator

  • imag: imaginary part operator

  • real: real part operator

  • plus: + unary plus operator

  • minus: - unary minus operator

  • not: ~ one’s complement operator

  • lnot: ! logical negation operator

  • post_dec: -- postfix decrement operator

  • post_inc: ++ postfix increment operator

  • pre_dec: -- prefix decrement operator

  • pre_inc: ++ prefix increment operator

  • sizeof_expr: sizeof operator

  • sizeof_type: sizeof operator

  • alignof_expr: alignof operator

  • alignof_type: alignof operator

  • vec_step_expr: vec_step operator

  • vec_step_type: vec_step operator

  • extension: extension operator

  • div: / division operator

  • mul: * multiplication operator

  • rem: % remainder operator

  • add: + addition operator

  • sub: - subtraction operator

  • shl: << left shift operator

  • shr: >> right shift operator

  • ge: >= greater-than or equal operator

  • gt: > greater-than operator

  • le: <= less-than or equal operator

  • lt: < less-than operator

  • eq: == equality operator

  • ne: != inequality operator

  • and: & bitwise AND operator

  • or: | bitwise OR operator

  • xor: ^ bitwise XOR operator

  • land: && logical AND operator

  • lor: || logical OR operator

  • conditional: ?: conditional operator

  • binary_conditional: ?: binary conditional operator

  • assign: = assignment operator

  • add_assign: += addition assignment operator

  • and_assign: &= bitwise AND assignment operator

  • div_assign: /= division assignment operator

  • mul_assign: *= multiplication assignment operator

  • or_assign: |= bitwise OR assignment operator

  • rem_assign: %= remainder assignment operator

  • shl_assign: <<= left shift assignment operator

  • shr_assign: >>= right shift assignment operator

  • sub_assign: -= subtraction assignment operator

  • xor_assign: ^= bitwise XOR assignment operator

  • throw: throw operator

  • comma: , comma operator

  • OP_COLLECTION: operator collections

OP_COLLECTION

accepted forms are:

  • multiplicative: *, / or % operator

  • additive: + or - operator

  • equality: == or != operator

  • relational: <, <=, > or >= operator

  • bitwise: ^, & or | operator

  • binary_logical: || or &&

  • logical: ||, && or ! operator

  • arithmetic: +, -, *, /, %, real or imag operator

  • assignment: =, +=, &=, /=, *=, <<=, >>=, -= or ^= operator

Rule B.FORCNTRL

Summary

For statements that cannot be guaranteed to terminate are shown.

Configuration

See generic service options.

Option for_structure
for_structure
-config=B.FORCNTRL,for_structure={TAGS, STRUCTURE},...

Specify report tags for the for statement head structures.

The configuration’s content is a set of pairs that associates report tags to the head’s parts with constraints indicating if they must be present or, if present, the number of side effects.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STRUCTURE:

the for statement head matches if it satisfies all the constraints. Accepted forms are:

  • STRUCT_FORMAT[&&STRUCT_FORMAT]*: a for statement structure

STRUCT_FORMAT

accepted forms are:

  • before(STRUCT_PART): the for statement before part satisfies the STRUCT_PART constraint

  • cond(STRUCT_PART): the for statement condition part satisfies the STRUCT_PART constraint

  • after(STRUCT_PART): the for statement after part satisfies the STRUCT_PART constraint

STRUCT_PART

accepted forms are:

  • empty: the for statement part must be empty

  • non-empty: the for statement part must be non-empty

  • write(CLASS,POS_MIN_MAX): the sub-expressions of the head part or the declarations in a declaration statement (depending on the value of CLASS) must have side effects in the range POS_MIN_MAX

CLASS

accepted forms are:

  • decl: the before part is a declaration statement; each of the included declarations is checked for the number of side effects

  • expr: the part is an expression split into a comma separated list of sub-expressions; each of the sub-expressions is checked for the number of side effects

POS_MIN_MAX

accepted forms are:

  • POS_NUM_MINRANGE_SEPPOS_NUM_MAX: range is from (non-negative) POS_NUM_MIN to POS_NUM_MAX

  • POS_NUMRANGE_SEP: range is all values equal or more than (non-negative) POS_NUM

  • POS_NUM: range is the single non-negative value POS_NUM

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

Option for_counter
for_counter
-config=B.FORCNTRL,for_counter={TAGS, COUNTER},...

Specify report tags for the loop counters of for statements.

The configuration’s content is a set of pairs that associates report tags to the for statement loop counter that satisfies the constraints.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

COUNTER:

an expression defining the constraints on the loop counters. Accepted forms are:

  • [+]AND_MATCHER: the loop counter AND_MATCHER

  • -AND_MATCHER: the loop counter does not match AND_MATCHER

  • [+]AND_MATCHER||COUNT_MATCHER: either the loop counter matches AND_MATCHER or it matches COUNT_MATCHER

  • -AND_MATCHER||COUNT_MATCHER: the loop counter does not match AND_MATCHER but does match COUNT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the loop counter matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the loop counter matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (COUNT_MATCHER): the loop counter matches COUNT_MATCHER

  • !BASIC_MATCHER: the loop counter does not match BASIC_MATCHER

  • any(): any loop counter matches

  • none(): no loop counter matches

  • global(): the loop counter is a global variable

  • is_in_test(): the loop counter is in a relational or equality test or in a function call in the condition part of the head

  • tested_in_condition(): the loop counter is an operand of a relational or equality test or in a function call in the condition part of the head

  • tested_in_relation(): the loop counter is an operand of a relational test in the condition part of the head

  • modify_is_monotonic(): the loop counter is monotonically incremented or decremented in the after part of the head

  • taken(): the loop counter is stored or passed

  • has_body_modification(): the loop counter is modified in the body

  • variable(): the loop counter is a variable

  • single(): the loop counter is unique

  • type(TYPE_MATCHER): the loop counter has a type that matches TYPE_MATCHER (see the -type_selector global configuration)

Option for_parts
for_parts
-config=B.FORCNTRL,for_parts={TAGS, PARTS},...

Specify report tags for the different parts of a for statement (i.e, the three parts of the head and the body).

The configuration’s content is a list of pairs of report tags and an expression specifying constraints on the for statement’s parts.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

PARTS:

an expression defining the constraints on the for statement’s parts; note that these constraints only apply if the part is non-empty. Accepted forms are:

  • [+]AND_MATCHER: the for statement AND_MATCHER

  • -AND_MATCHER: the for statement does not match AND_MATCHER

  • [+]AND_MATCHER||PARTS_MATCHER: either the for statement matches AND_MATCHER or it matches PARTS_MATCHER

  • -AND_MATCHER||PARTS_MATCHER: the for statement does not match AND_MATCHER but does match PARTS_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the for statement matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the for statement matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (PARTS_MATCHER): the for statement matches PARTS_MATCHER

  • !BASIC_MATCHER: the for statement does not match BASIC_MATCHER

  • any(): any for statement matches

  • none(): no for statement matches

  • before(BEFORE_CONSTR[&&BEFORE_CONSTR]*): the set of conditions that the before part of a for statement head must satisfy

  • cond(COND_CONSTR[&&COND_CONSTR]*): the set of conditions that the condition part of a for statement head must satisfy

  • after(AFTER_CONSTR[&&AFTER_CONSTR]*): the set of conditions that the after part of a for statement head must satisfy

  • body(BODY_CONSTR[&&BODY_CONSTR]*): the set of conditions that the body of a for statement must satisfy

BEFORE_CONSTR

accepted forms are:

  • only_init: the before part is an initializing expression or set of declarations with non-empty initializers

  • only_assign: the before part is a comma separated list of assignments or set of declarations with non-empty initializers

COND_CONSTR

accepted forms are:

  • counter_tests_are_relational: the value of numeric loop counters is tested directly or with a relational operator

  • expression_is_a_bool: the condition part is a single counter or a MISRA Boolean expression

  • tests_are_indirect: the condition part tests only uses relational or equality operators

  • counter_test_is_simple: the condition part has a simple test for the single loop counter

  • numeric_counter_tests_are_relational: the condition part tests each numeric loop counter using a relational or equality operators

  • counters_are_operands: the condition part tests each numeric loop counter using a relational or equality operators where the counter is an operand

  • counter_is_modified: a loop counter is modified in the condition part

  • taken_control_variable: the condition part does not use any taken control variable

AFTER_CONSTR

accepted forms are:

  • expression_modifies: the after part of the head is a comma sequence of expressions that only modify control variables

  • modify_is_inc_dec: the after part of the head is a comma sequence of increment or decrement expressions

  • modify_is_safe: the after part of the head increments or decrements the (single) loop counter by a constant amount and this increase or decrease is safe relative to the relation in one of the tests for that counter

  • single_write: the after part of the head is an expression that only modifies a single counter

  • modify_is_const_inc_dec: the after part of the head is a comma sequence of expressions that increment or decrement a variable by a constant amount

  • only_counter_is_modified: the after part of the head is an expression that only modifies loop counters

BODY_CONSTR

accepted forms are:

  • modified_variables_are_bool: every non-counter control variable (that is, a variable that occurs in the head) that is modified in the body has a MISRA Boolean type

  • modified_cond_variables_are_bool: every non-counter control variable that occurs in the condition part of the head and is modified in the body has a MISRA Boolean type

  • after_variable_modified: there exists a control variable that occurs in the after part of the head that is modified

  • counter_is_modified: a loop counter is modified in the body

  • has_jumps: the body contains a goto or a label statement

Rule B.GCOV

Summary

Service for parsing Gcov coverage files.

Description

Service for parsing GCC coverage tools output and generating code coverage reports.

This service analyzes coverage data from gcov output to detect insufficient code coverage, including function coverage, branch coverage, and condition coverage results.

The service can parse coverage reports generated by gcov with various options including --branch-counts, --branch-probabilities, --conditions (for MC/DC analysis), and --function-summaries. Coverage data can be provided either through input files or by capturing the tool’s stdout/stderr output.

For example, to parse an output file generated with gcov, the following configuration can be used:

-config=B.GCOV,input_files="gcov_output.txt"

Note that if the output file contains relative paths, they are resolved with respect to the parent directory of the file.

To parse the output directly from gcov stdout, you can set EXTRA_ALIASES to include the gcov executable (See “Tool Specification Variables“).

Violations are reported when coverage metrics fall below configurable thresholds. The default executed blocks threshold is 100%, but can be customized using the executed_blocks_threshold grammar global variable, for example:

-config=B.GCOV,grammar_globals+={executed_blocks_threshold,80}

Similarly, returned_threshold can be set to define the minimum percentage of function returns that must be covered.

This service has been tested for the following llvm verisons: 8.5.0, 9.5.0, 10.4.0, 11.4.0, 12.4.0, 13.4.0, 14.3.0, 15.2.0.

Configuration

See generic service options.

Option report_grammar
report_grammar
-config=B.GCOV,report_grammar=GRAM

Specify the grammar to be used to parse input files.

GRAM:

grammar identifier.

Option grammar_globals
grammar_globals
-config=B.GCOV,grammar_globals={var_name, var_value},...

Specify global variables for the grammar.

The configuration’s content is a list of name-value pairs for global variables.

var_name:

the name of the global variable.

var_value:

the value of the global variable.

Default:

-config=B.GCOV,grammar_globals={executed_blocks_threshold, 100}, {returned_threshold, 100}
Option sel_frames
sel_frames
-config=B.GCOV,sel_frames=FRAME_MATCHER,...

Specify which frames should be processed.

The configuration’s content is a list of frame selectors to be applied.

FRAME_MATCHER:

a -frame_selector matcher expression used to select frames.

Default:

-config=B.GCOV,sel_frames="kind(command)&&tool(command(^(\".*)?[^\\s]*gcov(-\\d+)?(?(1)\")\\s.*$))"
Option grammar
grammar
-config=B.GCOV,grammar={ID, {ACTION,...}},...

Specify the grammar clauses.

The configuration’s content is a list of grammar clauses associated to non-terminals.

ID:

the non-terminal identifier.

ACTION:

the action specifier text and the destination of related value. Accepted forms are:

  • OPT_DESTS[NUM]^REGEX: the text should match ^REGEX, the consumed text ends at group OPT_NUM (default 0), matched groups are assigned to OPT_DESTS

  • OPT_DESTSID(OPT_ARGS): the non-terminal or builtin action ID is performed using arguments OPT_ARGS and its matches assigned to OPT_DESTS

  • OPT_DESTSARG: the argument ARG is assigned to OPT_DESTS

OPT_DESTS

accepted forms are:

  • [DEST[,]*]DEST_OP: update the optional list of destinations DEST according to the associated operator DEST_OP; if DEST has multiple destinations and DEST_OP is a relational operator, the result is the conjunction of the operator applied to each destination

  • DESTDEST_OP: update the destination DEST according to the associated DEST_OP; if DEST has multiple destinations and DEST_OP is a relational operator, the result is the conjunction of the operator applied to each destination

DEST

accepted forms are:

  • VAR: the destination is the grammar variable VAR

  • @: the value produced by the action is returned

DEST_OP

accepted forms are:

  • =: assign the result of the action to the destination

  • +=: append the result of the action to the destination if the destination is a list; otherwise, adds the numeric value

  • -=: subtracts the result of the action from the destination (only numeric values are allowed)

  • ==: the destination is equal to the result of the action (fails if either variable is undefined)

  • !=: the destination is not equal to the result of the action (this succeeds if either argument is an undefined variable)

  • <: the destination is less than the result of the action (only numeric values are allowed)

  • <=: the destination is less than or equal to the result of the action (only numeric values are allowed)

  • >: the destination is greater than the result of the action (only numeric values are allowed)

  • >=: the destination is greater than or equal to the result of the action (only numeric values are allowed)

OPT_ARGS

accepted forms are:

  • [ARG][ARG,]*: arguments list

  • : no arguments

ARG

accepted forms are:

  • NUM: argument is an integer

  • "STRING": argument is a quoted string

  • VAR: argument is a variable

  • [OPT_ARGS]: argument is a list of arguments

VAR

accepted forms are:

  • @ID: the variable is global

  • ID: the variable is local

REGEX

accepted forms are:

Option input_files
input_files
-config=B.GCOV,input_files=FILE,...

Specify the list of input files.

The configuration’s content is a list of input files.

FILE:

input file path.

Default:

-config=B.GCOV,input_files=stdout, stderr

Rule B.GLOBALVAR

Summary

Global variables shall not be declared.

Description

Reports global variables

Configuration

See generic service options.

Option declarations
declarations
-config=B.GLOBALVAR,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule B.IDB_TIE

Summary

Rule for tying and summarizing any of the IDB ancillary servants. This service depends upon the configuration of the following ancillary services: STD.abortbhr STD.asrtterm STD.bitfldby STD.bitfldor STD.bitfldtp STD.bitopsgn STD.bytebits STD.caselimt STD.charlcle STD.charmmap STD.charmult STD.charppif STD.charppim STD.charsmap STD.charsmem STD.charsobj STD.charsval STD.clockera STD.cmralloc STD.ctypechr STD.datetime STD.decllimt STD.diagidnt STD.divrmsgn STD.enumtype STD.errnofgt STD.exitstat STD.extidsig STD.extinttp STD.feraisex STD.filebuff STD.filemopn STD.fileposi STD.fimename STD.floatcct STD.floatcst STD.floatexc STD.floatiex STD.floatnrw STD.floatrnd STD.floatstd STD.floatunf STD.floatval STD.fltevmth STD.fltevtyp STD.fmodzero STD.fprintfp STD.freesten STD.freestnd STD.fscanfms STD.fscanfp STD.getenvfn STD.inclangl STD.inclexpd STD.inclfile STD.inclhead STD.intfloat STD.intrpntr STD.intvdevc STD.mainargv STD.maindefn STD.mathdmer STD.mathrner STD.mathrond STD.multbchr STD.multbtid STD.multbtsl STD.nexidsig STD.nullchar STD.nullpntr STD.objbytes STD.plainbit STD.planchar STD.pragmdir STD.pragmfpc STD.pragmfva STD.pragmhdr STD.ptrdifft STD.register STD.removefl STD.remquofn STD.renamefl STD.rtsigned STD.setlocle STD.shortsgn STD.signalbk STD.signalfn STD.signalsl STD.signalsm STD.signalst STD.signdint STD.sizettyp STD.spacechr STD.stdmacro STD.strerror STD.stringfy STD.strtwcst STD.strtwcsu STD.structma STD.systemfn STD.textterm STD.timelocl STD.unionmbr STD.vaendmi STD.volatltp STD.widechar STD.widestng STD.witespac STD.writetxt STD.zerolnfl

Configuration

See generic service options.

Option behavior_sampling
behavior_sampling
-config=B.IDB_TIE,behavior_sampling={SERVICE, MAX},...

Specify sample size for matching ancillary service.

The configuration’s content is a set of ancillary service matchers with sample size.

SERVICE:

a service matcher used to select the ancillary services.

MAX:

unlimited or the maximum number of samples to be shown.

Option sample_reports
sample_reports
-config=B.IDB_TIE,sample_reports={TAG, REPORT_MATCHER},...

Specifies the sample reports that should be shown/counted.

The configuration’s content is a short-circuit sequence specifying the reports to be chosen as samples.

TAG:

a short-circuit sequence for sample reports. Accepted values are:

  • hide: discard if it matches the associated conditions;

  • hate: avoid when possible if it matches the associated conditions;

  • kill: ignore if it matches the associated conditions;

  • show: show if it matches the associated conditions;

REPORT_MATCHER:

a -report_selector identifier or a matcher expression used to select the reports.

Option behaviors
behaviors
-config=B.IDB_TIE,behaviors={TAGS, BEHAVIOR_MATCHER},...

Specifies the behaviors and ancillary services to be tagged.

The configuration’s content is associate report tags to behavior matchers.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

BEHAVIOR_MATCHER:

an expression selecting behaviors. Accepted forms are:

  • [+]AND_MATCHER: the behavior matches AND_MATCHER

  • -AND_MATCHER: the behavior does not match AND_MATCHER

  • [+]AND_MATCHER||BEHAVIOR_MATCHER: either the behavior matches AND_MATCHER or it matches BEHAVIOR_MATCHER

  • -AND_MATCHER||BEHAVIOR_MATCHER: the behavior does not match AND_MATCHER but does match BEHAVIOR_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the behavior matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the behavior matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (BEHAVIOR_MATCHER): the behavior matches BEHAVIOR_MATCHER

  • !BASIC_MATCHER: the behavior does not match BASIC_MATCHER

  • any(): any behavior matches

  • none(): no behavior matches

  • report(CLASS[||CLASS]*): the report class matches one of the classes

  • standard(CLASS[||CLASS]*): the standard class matches one of the classes

  • service(SERVICE_MATCHER): the behavior referring is for an ancillary service matching SERVICE_MATCHER (see the -service_selector global configuration)

  • category(REGEX): the behavior category matches ^REGEX$

REGEX

accepted forms are:

CLASS

accepted forms are:

  • implementation: implementation-defined

  • ill_formed: ill-formed

  • undefined: undefined

  • unspecified_critical: unspecified and critical

  • unspecified_not_critical: unspecified and not critical

  • unspecified: unspecified

  • limit: implementation limit

Rule B.IDNTVCBL

Summary

The vocabulary used to compose identifiers should be precisely defined in a way that is amenable to automatic checking.

Description

Reports if entity names do not use the defined vocabulary. See vocabulary for more information about the vocabulary dictionaries and their use

Configuration

See generic service options.

Option misnamed_entity_fmt
misnamed_entity_fmt
-config=B.IDNTVCBL,misnamed_entity_fmt={TAG, ENTITY_MATCHER, NAME_MATCHER, FMT},...

Specify entities and the misnaming matcher to be shown using a short-circuit sequence with message format.

The configuration’s content is an ordered tagged list of entity and misnaming matchers with message format; the hide-show tag and message format are associated with the first matching entity and name.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

ENTITY_MATCHER:

a -entity_selector identifier or a matcher expression used to select the entities.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

FMT:

format (see the -fmt global configuration content, template enttname__default_fmt) with fields:

node

entity description;

name

unqualified identifier;

kind

entity kind;

name_info_tag

tag returned by name matcher;

vocab_msg

vocabulary error message or ''.

Option misnamed_macro_fmt
misnamed_macro_fmt
-config=B.IDNTVCBL,misnamed_macro_fmt={TAG, MACRO_MATCHER, NAME_MATCHER, KIND, FMT},...

Specify macro and the misnaming matcher to be shown using a short-circuit sequence with message format.

The configuration’s content is an ordered tagged list of macro, name matcher, name-flag indicating if the macro name or the parameter names should be matched, and a message format; the hide-show tag is associated with the first matching macro and macro or parameter names (depending on the name-flag).

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

KIND:

whether to check macro or macro parameters. Accepted values are:

  • macro: macro name;

  • param: macro parameter;

  • any: macro name or macro parameters;

FMT:

format (see the -fmt global configuration content, template enttname__default_fmt) with fields:

node

macro or macro parameter;

name

the identifier;

kind

entity kind;

name_info_tag

tag returned by name matcher;

vocab_msg

vocabulary error message or ‘’.

Option misnamed_entity
misnamed_entity
-config=B.IDNTVCBL,misnamed_entity={ENTITY_MATCHER, NAME_MATCHER},...

Specify the entity and name matchers.

The configuration’s content is an ordered tagged list of entity and misnaming matchers; the hide-show tag is associated with the first matching entity and name.

ENTITY_MATCHER:

a -entity_selector identifier or a matcher expression used to select the entities.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

Option misnamed_macro
misnamed_macro
-config=B.IDNTVCBL,misnamed_macro={MACRO_MATCHER, NAME_MATCHER, KIND},...

Specify the macro and name matchers.

The configuration’s content is an ordered tagged list of macro, name matcher and name-flag indicating if the macro name or the parameter names should be matched; the hide-show tag is associated with the first matching macro and name(s).

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

KIND:

whether to check macro or macro parameters. Accepted values are:

  • macro: macro name;

  • param: macro parameter;

  • any: macro name or macro parameters;

Option declarations
declarations
-config=B.IDNTVCBL,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option macros
macros
-config=B.IDNTVCBL,macros={TAGS, MACRO_MATCHER},...

Specifies the report tags for macros.

The configuration’s content is a list of clauses specifying the macros and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Option all_decls
all_decls
-config=B.IDNTVCBL,all_decls=BOOL

Specify whether to show all or just a single representative declaration for each reported entity.

BOOL:

boolean indicating whether to show one or all declarations. Accepted values are:

  • true: show all declarations for each reported entity;

  • false: show a representative declaration for each reported entity;

Option good_words_file
good_words_file
-config=B.IDNTVCBL,good_words_file=GOOD_WORDS

A file containing a list of words, one per line, all in lowercase, that can be used in the project (see string interpolation clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

GOOD_WORDS:

good words filename.

Default:

-config=B.IDNTVCBL,good_words_file=""
Option bad_words_file
bad_words_file
-config=B.IDNTVCBL,bad_words_file=BAD_WORDS

A file containing a list of words, one per line, all in lowercase, that cannot be used in the project (see string interpolatn clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

BAD_WORDS:

bad words filename.

Default:

-config=B.IDNTVCBL,bad_words_file=""
Option good_items_file
good_items_file
-config=B.IDNTVCBL,good_items_file=GOOD_ITEMS

A file containing a list of lexical items, one per line, that can be used in the project (see string interpolation clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

GOOD_ITEMS:

good items filename.

Default:

-config=B.IDNTVCBL,good_items_file=""
Option bad_items_file
bad_items_file
-config=B.IDNTVCBL,bad_items_file=BAD_ITEMS

A file containing a list of lexical items, one per line, that cannot be used in the project (see string interpolation clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

BAD_ITEMS:

bad items filename.

Default:

-config=B.IDNTVCBL,bad_items_file=""
Option good_item_regexs
good_item_regexs
-config=B.IDNTVCBL,good_item_regexs=GOOD_REGEX,...

A list of regular expressions matching good identifiers. For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

{GOOD_REGEX,…}:

regular expressions matching good identifiers. Accepted members are:

Default:

-config=B.IDNTVCBL,good_item_regexs={}
Option bad_item_regexs
bad_item_regexs
-config=B.IDNTVCBL,bad_item_regexs=BAD_REGEX,...

A list of regular expressions matching bad identifiers. For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

{BAD_REGEX,…}:

regular expressions matching bad identifiers. Accepted members are:

Default:

-config=B.IDNTVCBL,bad_item_regexs={}
Option project_dictionary
project_dictionary
-config=B.IDNTVCBL,project_dictionary=PROJECT_DICT

The dictionary contains a list of words in lowercase that can be used in the project along with their frequencies (see string interpolation clause for how to specify the file).

PROJECT_DICT:

project dictionary filename.

Default:

-config=B.IDNTVCBL,project_dictionary=""
Option context_dictionary
context_dictionary
-config=B.IDNTVCBL,context_dictionary=CONTEXT_DICT

The dictionary contains a list of words in lowercase along with their frequencies (see string interpolation clause for how to specify the file). Note that the words and their frequencies are only used to assist the segmentation process.

CONTEXT_DICT:

context dictionary filename.

Default:

-config=B.IDNTVCBL,context_dictionary=""
Option splitter_regexs
splitter_regexs
-config=B.IDNTVCBL,splitter_regexs=SPLITTER,...

A list of regular expressions defining custom splitters.

{SPLITTER,…}:

set of regular expressions defining custom splitters. Accepted members are:

Default:

-config=B.IDNTVCBL,splitter_regexs={}
Option segmentation_stops_after
segmentation_stops_after
-config=B.IDNTVCBL,segmentation_stops_after=SAMURAI

Last step of the Samurai segmentation algorithm to be executed.

SAMURAI:

last step of the Samurai segmentation algorithm to be executed. Accepted values are:

  • none: no segmentation even on non-alpha characters;

  • underscore: segment on underscore characters;

  • non_alpha: segment on non-alpha characters;

  • lower_to_upper: segment on non-alpha and a change from lowercase to uppercase;

  • camel_case: segment on non-alpha, a change from lowercase to uppercase, and camel case;

  • no_case: segment on non-alpha, a change from lowercase to uppercase, camel case, and a score-based heuristics that is independent of any case consideration unless the word length exceeds the max-no-case-length value;

Default:

-config=B.IDNTVCBL,segmentation_stops_after=none
Option max_no_case_length
max_no_case_length
-config=B.IDNTVCBL,max_no_case_length=MAX_LEN

The maximum length of a string upon which the “no case” step of the Samurai segmentation algorithm is applied.

MAX_LEN:

maximum string length for “no case” segmentation. It must be an integer greater than or equal to 2.

Default:

-config=B.IDNTVCBL,max_no_case_length=16

Rule B.INDEPENDENCE

Aliases

B.PROJORG

Summary

Files, entities and macros shall satisfy the configured project organization constraints.

Description

For general information about this tool and some illustrative examples, see Keeping the Project Organization Under Control.

By default the service is flow-insensitive (i.e., a call is considered even when it appears in an unreachable path of the program). However, it is possible to configure the service to be flow-sensitive to discard definitely unreachable paths using the flow_sensitive service configuration:

-config=B.INDEPENDENCE,flow_sensitive=true

Configuration

See generic service options.

Option component_files
component_files
-config=B.INDEPENDENCE,component_files={FMT, FILE_MATCHER},...

Specifies that matching files are in the component defined by the format.

The configuration’s content is format and matcher for the component file names.

FMT:

format (see the -fmt global configuration content, template independence__file_default_fmt, specifying a mapping from a file to its component base name/area; this has fields:

name

file base name without extension;

extension

file name extension;

kind

file kind.

FILE_MATCHER:

a -file_tag identifier or a matcher expression used to select the files.

Default:

-config=B.INDEPENDENCE,component_files={}
Option all_component_entities
all_component_entities
-config=B.INDEPENDENCE,all_component_entities=ENTITY_MATCHER,...

Specifies that matching entities are interesting.

The configuration’s content is a set of entity matchers defining the universe of all interesting entities.

ENTITY_MATCHER:

an -entity_selector identifier or a matcher expression used to select the entities.

Default:

-config=B.INDEPENDENCE,all_component_entities={}
Option component_entities
component_entities
-config=B.INDEPENDENCE,component_entities={FMT, TRACKER, ENTITY_MATCHER},...

Specifies that matching entities with given tracking are in the component/area defined by the format.

The configuration’s content is a sequence of entity matchers with assigned tracking and component format; note that matchers that constrain the entity name will be checked before the more generic ones.

FMT:

format (see the -fmt global configuration content, template independence__entity_default_fmt), specifying a mapping from an entity to its component/area; this has fields:

name

entity name without qualifiers;

fqname

fully qualified entity name;

kind

entity kind.

TRACKER:

tracking determines the accesses to the matching entities. Accepted values are:

  • content: the accesses are to references to matching variables or functions;

  • field: the accesses are to references to matching fields;

  • address: the accesses are to the addresses of tracked pointees to references to matching variables;

ENTITY_MATCHER:

a -entity_selector identifier or a matcher expression used to select a subset of the interesting entities (selected using all_component_entities).

Default:

-config=B.INDEPENDENCE,component_entities={}
Option all_component_macros
all_component_macros
-config=B.INDEPENDENCE,all_component_macros=MACRO_MATCHER,...

Specifies that matching macros are interesting.

The configuration’s content is a set of macro matchers defining the universe of all interesting macros.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Default:

-config=B.INDEPENDENCE,all_component_macros={}
Option component_macros
component_macros
-config=B.INDEPENDENCE,component_macros={FMT, TRACKER, MACRO_MATCHER},...

Specifies that matching macros with given tracking are in the component defined by the format.

The configuration’s content is a short-circuit sequence of macro matchers with assigned tracking and component format.

FMT:

format (see the -fmt global configuration content, template independence__macro_default_fmt), specifying a mapping from a macro to its component base name/area; this has fields:

name

entity name without qualifiers;

function_like

boolean for selecting function-like (true) or object-like (false) macros;

variadic

boolean for selecting variadic (true) or non-variadic (false) macros;

used

boolean for selecting macros that are used (true) or unused (false);

guard

boolean for selecting macros that are used (true) or not used for guards (false).

TRACKER:

tracking determines the referrer; that is, who is responsible for the expansion. Accepted values are:

  • macro_file: if expanded in the body of a macro, use that macro; otherwise use the component for the file containing the expansion;

  • macro_entity: if expanded in the body of a macro, use that macro; if expanded in an entity, then use the entity;

  • entity: use entity of the top expansion;

  • address: if the macro expands to a possibly wrapped integer literal, use the innermost entity that contains the literal; it is checked that there is a possible read of the literal as an address;

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select a subset of the interesting macros (selected using all_component_macros).

Default:

-config=B.INDEPENDENCE,component_macros={}
Option component_tag
component_tag
-config=B.INDEPENDENCE,component_tag={COMP_MATCHER_T, DOMAIN, TAG},...

Specifies a matching component’s domain and tag; the assigned domains classify the components while the tags can provide a security mark or level.

The configuration’s content is a short-circuit sequence of component matchers with associated domains and tags.

COMP_MATCHER_T:

component matcher for specifying the domain and tag. Accepted forms are:

  • [+]AND_MATCHER: the component matches AND_MATCHER

  • -AND_MATCHER: the component does not match AND_MATCHER

  • [+]AND_MATCHER||COMP_MATCHER_T: either the component matches AND_MATCHER or it matches COMP_MATCHER_T

  • -AND_MATCHER||COMP_MATCHER_T: the component does not match AND_MATCHER but does match COMP_MATCHER_T

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the component matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the component matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (COMP_MATCHER_T): the component matches COMP_MATCHER_T

  • !COMP_MATCHER_T: the component does not match COMP_MATCHER_T

  • any(): any component matches

  • none(): no component matches

  • ID: component base name

  • ^REGEX$: the component base name matches ^REGEX$

REGEX

accepted forms are:

DOMAIN:

a domain identifier.

TAG:

a tag identifier or number in DOMAIN.

Default:

-config=B.INDEPENDENCE,component_tag={}
Option component_relation
component_relation
-config=B.INDEPENDENCE,component_relation={COMP_MATCHER_R, REL, COMP_MATCHER_R},...

Specifies the relation between matching from (or referring) components and matching to (or referred) components.

The configuration’s content is the relations between components.

COMP_MATCHER_R:

component matcher for specifying the from (referring) component. Accepted forms are:

  • [+]AND_MATCHER: the component matches AND_MATCHER

  • -AND_MATCHER: the component does not match AND_MATCHER

  • [+]AND_MATCHER||COMP_MATCHER_R: either the component matches AND_MATCHER or it matches COMP_MATCHER_R

  • -AND_MATCHER||COMP_MATCHER_R: the component does not match AND_MATCHER but does match COMP_MATCHER_R

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the component matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the component matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (COMP_MATCHER_R): the component matches COMP_MATCHER_R

  • !COMP_MATCHER_R: the component does not match COMP_MATCHER_R

  • any(): any component matches

  • none(): no component matches

  • ID: component base name

  • tag(DOMAIN_IDOPVALUE_ID): first component for which DOMAIN_ID OP VALUE_ID holds

  • tag(DOMAIN_ID=^REGEX$): first component for which DOMAIN_ID matches REGEX

REGEX

accepted forms are:

OP

accepted forms are:

  • ==: tags are identical

  • =: tags are identical

  • !=: tags differ

  • <: the first tag is less than the second (using numerical ordering if both are numeric, otherwise using lexicographic ordering)

  • <=: the first tag is less than or equal to the second (using numerical ordering if both are numeric, otherwise using lexicographic ordering)

  • >: the first tag is greater than the second (using numerical ordering if both are numeric, otherwise using lexicographic ordering)

  • >=: the first tag is greater than or equal to the second (using numerical ordering if both are numeric, otherwise using lexicographic ordering)

DOMAIN_ID

accepted forms are:

  • STRING: a domain identifier

VALUE_ID

accepted forms are:

  • STRING: a tag value (identifier or number)

REL:

relation identifier.

COMP_MATCHER_R:

component matcher for specifying the to (referred) component.

Default:

-config=B.INDEPENDENCE,component_relation={}
Option show_component_files
show_component_files
-config=B.INDEPENDENCE,show_component_files=COMP_MATCHERS,...

Specifies files and their components to be shown.

{COMP_MATCHERS,…}:

files whose components match one of COMP_MATCHERS are shown. Accepted members are:

  • COMP_MATCHER: component matcher. Accepted forms are:

  • [+]AND_MATCHER: the component matches AND_MATCHER

  • -AND_MATCHER: the component does not match AND_MATCHER

  • [+]AND_MATCHER||COMP_MATCHER: either the component matches AND_MATCHER or it matches COMP_MATCHER

  • -AND_MATCHER||COMP_MATCHER: the component does not match AND_MATCHER but does match COMP_MATCHER_R

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the component matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the component matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (COMP_MATCHER): the component matches COMP_MATCHER

  • !COMP_MATCHER: the component does not match COMP_MATCHER

  • COMP_MATCHER_R: the component matches COMP_MATCHER_R

  • ID1/ID2: the component’s full name is ID1/ID2

  • rel(RELS,COMP_MATCHER): the component being matched is in a relation in RELS with a component matching COMP_MATCHER

  • irel(RELS,COMP_MATCHER): a component matching COMP_MATCHER is in a relation in RELS with the component being matched

  • ^REGEX$: the component full name matches ^REGEX$

REGEX

accepted forms are:

RELS

accepted forms are:

  • ID[||ID]*: relation is one of ID that is defined by parameter component_relation

Option show_component_entities
show_component_entities
-config=B.INDEPENDENCE,show_component_entities=COMP_MATCHERS,...

Specifies entities and their components to be shown.

{COMP_MATCHERS,…}:

entities whose components match one of the COMP_MATCHERS are shown. Accepted members are:

  • COMP_MATCHER: any component entity that matches COMP_MATCHER is shown.

Option show_component_macros
show_component_macros
-config=B.INDEPENDENCE,show_component_macros=COMP_MATCHERS,...

Specifies macros and their components to be shown.

{COMP_MATCHERS,…}:

macros whose components match one of the COMP_MATCHERS are shown. Accepted members are:

  • COMP_MATCHER: any component entity that matches COMP_MATCHER is shown.

Option relation_report
relation_report
-config=B.INDEPENDENCE,relation_report={PERM_MATCHER, REPORT_KIND},...

Specifies the components’ permissions and associated report kinds.

The configuration’s content is a short-circuit sequence of permission matchers with report kinds.

PERM_MATCHER:

permission matcher. Accepted forms are:

  • [+]AND_MATCHER: the permission matches AND_MATCHER

  • -AND_MATCHER: the permission does not match AND_MATCHER

  • [+]AND_MATCHER||PERM_MATCHER: either the permission matches AND_MATCHER or it matches PERM_MATCHER

  • -AND_MATCHER||PERM_MATCHER: the permission does not match AND_MATCHER but does match PERM_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the permission matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the permission matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (PERM_MATCHER): the permission matches PERM_MATCHER

  • !BASIC_MATCHER: the permission does not match BASIC_MATCHER

  • any(): any permission matches

  • none(): no permission matches

  • from(COMP_MATCHER): the referring component matches COMP_MATCHER

  • to(COMP_MATCHER): the referred component matches COMP_MATCHER

  • action(ACTION[||ACTION]*): the action matches one of the ACTION tags

  • rel(ID[||ID]*): the relation between the referring and referred components matches one of the ID

  • tag(ID0OPID1): the tag for the domain ID0 of the referring component is OP the tag for the domain ID1 of the referred component

ACTION

accepted forms are:

  • read: the component tracks an entity that is read

  • write: the referred component tracks an entity that is written

  • call: the referred component tracks a function that is called

  • expand: the referred component tracks a macro that is expanded

  • include: the referred component contains a file that is included

OP

accepted forms are:

  • ==: tags are identical

  • =: tags are identical

  • !=: tags differ

  • <: the first tag is less than the second (using numerical ordering if both are numeric, otherwise using lexicographic ordering)

  • <=: the first tag is less than or equal to the second (using numerical ordering if both are numeric, otherwise using lexicographic ordering)

  • >: the first tag is greater than the second (using numerical ordering if both are numeric, otherwise using lexicographic ordering)

  • >=: the first tag is greater than or equal to the second (using numerical ordering if both are numeric, otherwise using lexicographic ordering)

REPORT_KIND:

report kind. Accepted values are:

  • violation: report is shown as a violation;

  • caution: report is shown as a caution;

  • information: report is shown as an information;

  • '': the report is not shown;

Default:

-config=B.INDEPENDENCE,relation_report={}
Option component_allows
component_allows
-config=B.INDEPENDENCE,component_allows=PERM_MATCHER,...

Specifies the allowed relations between the referred and referring components.

The configuration’s content is a short-circuit sequence of permission matchers.

PERM_MATCHER:

any relation between the referred and referring components that matches PERM_MATCHER is allowed.

Default:

-config=B.INDEPENDENCE,component_allows={}
Option flow_sensitive
flow_sensitive
-config=B.INDEPENDENCE,flow_sensitive=FLOW_SENSITIVITY

Specifies whether the checker should disregard references in unreachable parts of the program.

FLOW_SENSITIVITY:

whether to consider references in unreachable parts of the program. Accepted values are:

  • false: consider all references as reachable (flow-insensitive behavior);

  • true: do not consider references in definitely unreachable basic blocks;

Default:

-config=B.INDEPENDENCE,flow_sensitive=false

Rule B.INEXACT_FLT

Summary

Floating-point literals with an inherent representation error are shown.

Description

A floating-point literal is reported if its binary representation is inexact.

Imprecision

Cautions are reported for all inexact floating-point literals.

Configuration

See generic service options.

Option statements
statements
-config=B.INEXACT_FLT,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Rule B.INITDEST

Summary

Checker for initialization destinations.

Configuration

See generic service options.

Rule B.LIMITS

Summary

Source code should not breach the implementation’s limits.

Description

The source code must not breach the implementation’s limits.

This service depends upon the configuration of the following ancillary services: STD.argfcall STD.argmcall STD.blkident STD.byteobjt STD.caselimt STD.charline STD.charstrl STD.cissnest STD.cnstenum STD.extident STD.extidsig STD.inclnest STD.macident STD.membrecd STD.nexidsig STD.paramfun STD.parammac STD.pexpnest STD.ppifnest STD.ptypnest STD.recdnest STD.decllimt

Configuration

See generic service options.

Option behaviors
behaviors
-config=B.LIMITS,behaviors={TAGS, BEHAVIOR_MATCHER},...

Specifies the behaviors and ancillary services to be tagged.

The configuration’s content is associate report tags to behavior matchers.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

BEHAVIOR_MATCHER:

an expression selecting behaviors. Accepted forms are:

  • [+]AND_MATCHER: the behavior matches AND_MATCHER

  • -AND_MATCHER: the behavior does not match AND_MATCHER

  • [+]AND_MATCHER||BEHAVIOR_MATCHER: either the behavior matches AND_MATCHER or it matches BEHAVIOR_MATCHER

  • -AND_MATCHER||BEHAVIOR_MATCHER: the behavior does not match AND_MATCHER but does match BEHAVIOR_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the behavior matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the behavior matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (BEHAVIOR_MATCHER): the behavior matches BEHAVIOR_MATCHER

  • !BASIC_MATCHER: the behavior does not match BASIC_MATCHER

  • any(): any behavior matches

  • none(): no behavior matches

  • report(CLASS[||CLASS]*): the report class matches one of the classes

  • standard(CLASS[||CLASS]*): the standard class matches one of the classes

  • service(SERVICE_MATCHER): the behavior referring is for an ancillary service matching SERVICE_MATCHER (see the -service_selector global configuration)

  • category(REGEX): the behavior category matches ^REGEX$

REGEX

accepted forms are:

CLASS

accepted forms are:

  • implementation: implementation-defined

  • ill_formed: ill-formed

  • undefined: undefined

  • unspecified_critical: unspecified and critical

  • unspecified_not_critical: unspecified and not critical

  • unspecified: unspecified

  • limit: implementation limit

Rule B.LLVM_COV

Summary

Service for parsing llvm-cov coverage files.

Description

Service for parsing LLVM coverage tools output and generating code coverage reports.

This service analyzes coverage data from llvm-cov output to detect insufficient code coverage, including MC/DC (Modified Condition/Decision Coverage) results.

The service can parse coverage summaries generated by llvm-cov report (possibly with the --show-mcdc-summary option), as well as detailed coverage reports from llvm-cov show. Coverage data can be provided either through input files or by capturing the tool’s stdout/stderr output.

For example, to parse an output file generated with llvm-cov report or llvm-cov show, the following configuration can be used:

-config=B.LLVM_COV,input_files="llvm_cov_output.txt"

Note that if the output file contains relative paths, they are resolved with respect to the parent directory of the file.

To parse the output directly from llvm-cov stdout, you can set EXTRA_ALIASES to include the llvm-cov executable (See “Tool Specification Variables“).

Violations are reported when coverage metrics fall below configurable thresholds. The default MC/DC coverage threshold is 0%, but can be customized using the mcdc_threshold grammar global variable, for example:

-config=B.LLVM_COV,grammar_globals+={mcdc_threshold,50}

Note that this service requires the output of llvm-cov show to contain the source file path, but llvm-cov only displays it if either:

If satisfying one of these options is not possible or not desirable, one possibility is to place the file path at the beginning of the textual output, for example:

echo $FILE_NAME > mcdc.txt
llvm-cov-19 show ./executable -instr-profile=data.profdata --show-mcdc -sources $FILE_NAME >> mcdc.txt

This service has been tested for the following gcc verisons: 12.0.1, 13.0.1, 14.0.6, 15.0.7, 16.0.6, 17.0.6, 18.1.8, 19.1.7, 20.1.8, 21.1.8.

Configuration

See generic service options.

Option report_grammar
report_grammar
-config=B.LLVM_COV,report_grammar=GRAM

Specify the grammar to be used to parse input files.

GRAM:

grammar identifier.

Option grammar_globals
grammar_globals
-config=B.LLVM_COV,grammar_globals={var_name, var_value},...

Specify global variables for the grammar.

The configuration’s content is a list of name-value pairs for global variables.

var_name:

the name of the global variable.

var_value:

the value of the global variable.

Default:

-config=B.LLVM_COV,grammar_globals={regions_threshold, 0}, {functions_threshold, 0}, {lines_threshold, 0}, {branches_threshold, 0}, {mcdc_threshold, 0}
Option sel_frames
sel_frames
-config=B.LLVM_COV,sel_frames=FRAME_MATCHER,...

Specify which frames should be processed.

The configuration’s content is a list of frame selectors to be applied.

FRAME_MATCHER:

a -frame_selector matcher expression used to select frames.

Default:

-config=B.LLVM_COV,sel_frames="kind(command)&&tool(command(^(\".*)?[^\\s]*llvm-cov(-\\d+)?(?(1)\")\\s+(report|show).*$))"
Option grammar
grammar
-config=B.LLVM_COV,grammar={ID, {ACTION,...}},...

Specify the grammar clauses.

The configuration’s content is a list of grammar clauses associated to non-terminals.

ID:

the non-terminal identifier.

ACTION:

the action specifier text and the destination of related value. Accepted forms are:

  • OPT_DESTS[NUM]^REGEX: the text should match ^REGEX, the consumed text ends at group OPT_NUM (default 0), matched groups are assigned to OPT_DESTS

  • OPT_DESTSID(OPT_ARGS): the non-terminal or builtin action ID is performed using arguments OPT_ARGS and its matches assigned to OPT_DESTS

  • OPT_DESTSARG: the argument ARG is assigned to OPT_DESTS

OPT_DESTS

accepted forms are:

  • [DEST[,]*]DEST_OP: update the optional list of destinations DEST according to the associated operator DEST_OP; if DEST has multiple destinations and DEST_OP is a relational operator, the result is the conjunction of the operator applied to each destination

  • DESTDEST_OP: update the destination DEST according to the associated DEST_OP; if DEST has multiple destinations and DEST_OP is a relational operator, the result is the conjunction of the operator applied to each destination

DEST

accepted forms are:

  • VAR: the destination is the grammar variable VAR

  • @: the value produced by the action is returned

DEST_OP

accepted forms are:

  • =: assign the result of the action to the destination

  • +=: append the result of the action to the destination if the destination is a list; otherwise, adds the numeric value

  • -=: subtracts the result of the action from the destination (only numeric values are allowed)

  • ==: the destination is equal to the result of the action (fails if either variable is undefined)

  • !=: the destination is not equal to the result of the action (this succeeds if either argument is an undefined variable)

  • <: the destination is less than the result of the action (only numeric values are allowed)

  • <=: the destination is less than or equal to the result of the action (only numeric values are allowed)

  • >: the destination is greater than the result of the action (only numeric values are allowed)

  • >=: the destination is greater than or equal to the result of the action (only numeric values are allowed)

OPT_ARGS

accepted forms are:

  • [ARG][ARG,]*: arguments list

  • : no arguments

ARG

accepted forms are:

  • NUM: argument is an integer

  • "STRING": argument is a quoted string

  • VAR: argument is a variable

  • [OPT_ARGS]: argument is a list of arguments

VAR

accepted forms are:

  • @ID: the variable is global

  • ID: the variable is local

REGEX

accepted forms are:

Option input_files
input_files
-config=B.LLVM_COV,input_files=FILE,...

Specify the list of input files.

The configuration’s content is a list of input files.

FILE:

input file path.

Default:

-config=B.LLVM_COV,input_files=stdout, stderr

Rule B.MACREXPR

Summary

A macro invocation that expands to a sequence of tokens starting and ending on expression edges must be parenthesized or immediately enclosed in parentheses.

Description

Any macro expansion that is a complete expression must be parenthesized or immediately enclosed in parentheses.

Any macro expansion that does not expand to an expression but begins and ends with sub-expressions of a single larger expression is reported. Notes:

  • The following expansions are not reported:

    • a parenthesized expression

    • a call-like expression

    • a single token expression

    • an initializer list

    • an expression whose value is ignored

  • The expansion_context service configuration can be used to tag the reports for macro calls that expand to nodes with matching contexts.

Configuration

See generic service options.

Option macros
macros
-config=B.MACREXPR,macros={TAGS, MACRO_MATCHER},...

Specifies the report tags for macros.

The configuration’s content is a list of clauses specifying the macros and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Option expansion_context
expansion_context
-config=B.MACREXPR,expansion_context={TAGS, MATCHER},...

Specify the report tag for associated expansion context matcher.

The configuration’s content is list of report tags and their associated expansion matcher option.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MATCHER:

expansion context matcher. Accepted forms are:

  • [+]AND_MATCHER: the expansion matches AND_MATCHER

  • -AND_MATCHER: the expansion does not match AND_MATCHER

  • [+]AND_MATCHER||EXP_MATCHER: either the expansion matches AND_MATCHER or it matches EXP_MATCHER

  • -AND_MATCHER||EXP_MATCHER: the expansion does not match AND_MATCHER but does match EXP_MATCHER

EXP_MATCHER

accepted forms are:

  • BASIC_MATCHER: the expansion matches BASIC_MATCHER

  • BASIC_MATCHER||EXP_MATCHER: either the expansion matches BASIC_MATCHER or it matches EXP_MATCHER

BASIC_MATCHER

accepted forms are:

  • (EXP_MATCHER): the expansion matches EXP_MATCHER

  • !BASIC_MATCHER: the expansion does not match BASIC_MATCHER

  • any(): any expansion matches

  • none(): no expansion matches

  • left_right(REGEX1,REGEX2): the tokens preceding and following the expansion matches, respectively, ^REGEX1$ and ^REGEX2$

  • context(CONTEXT_MATCHER): the expansion is in a context matching CONTEXT_MATCHER (see the -context_selector global configuration)

  • single_token(): the expansion is a single token

  • single_expr(): the expansion is a single expression

  • part_of_larger_expr(): the expansion is part of a larger expression

  • pp_expr(PP_MATCHER): the expansion is a preprocessor expression matching PP_EXP_MATCHER

PP_EXP_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the preprocessor expansion matches AND_MATCHER

  • -AND_MATCHER: the preprocessor expansion does not match AND_MATCHER

  • [+]AND_MATCHER||PP_EXP_MATCHER: either the preprocessor expansion matches AND_MATCHER or it matches PP_EXP_MATCHER

  • -AND_MATCHER||PP_EXP_MATCHER: the preprocessor expansion does not match AND_MATCHER but does match PP_EXP_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the expansion matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the expansion matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (PP_EXP_MATCHER): the expansion matches PP_EXP_MATCHER

  • !BASIC_MATCHER: the expansion does not match BASIC_MATCHER

  • any(): any expansion matches

  • none(): no expansion matches

  • node(PP_ASTF[||PP_ASTF]*): the expansion’s representation matches one of the preprocessor AST functors

  • operator(PP_OPERATOR[||PP_OPERATOR]*): the expansion’s representation has a main operator that matches one of the preprocessor AST operators

PP_ASTF

accepted forms are:

  • binop: the expansion is a binary operator

  • unnop: the expansion is a unary operator (this includes the defined operator)

  • condop: the expansion is a conditional operator

  • pparen: the expansion is a parenthesized expression

  • pconst: the expansion is a constant value

PP_OPERATOR

accepted forms are:

  • comma: , comma operator

  • land: && logical AND operator

  • lor: || logical OR operator

  • plus: + unary plus operator

  • minus: - unary minus operator

  • eq: == equality operator

  • ne: != inequality operator

  • ge: >= greater-than or equal operator

  • gt: > greater-than operator

  • le: <= less-than or equal operator

  • lt: < less-than operator

  • shl: << left shift operator

  • shr: >> right shift operator

  • add: + addition operator

  • sub: - subtraction operator

  • div: / division operator

  • mul: * multiplication operator

  • rem: % remainder operator

  • not: ~ one’s complement operator

  • lnot: ! logical negation operator

  • plus: + unary plus operator

  • minus: - unary minus operator

  • defined: defined operator

Rule B.MONOINDENT

Summary

Use a monotonic indentation style.

Configuration

See generic service options.

Option indent_size
indent_size
-config=B.MONOINDENT,indent_size=SIZE

Specify size of indentation.

SIZE:

the number of spaces per indentation level. It must be an integer greater than or equal to 0.

Default:

-config=B.MONOINDENT,indent_size=1

Rule B.NAMING

Summary

Service for cloning by bespoke naming rules.

Description

The service enforces bespoke naming conventions for entities and macros.

Consider the following example:

-fmt={err_msg, enttname__default_fmt, "the identifier for %{node} is non-compliant"}

-doc_begin="Naming conventions for functions."
-clone_service=B.NAMING,Naming_Function
-config=Naming_Function,summary=
"Function names shall have a prefix congruent with the module name"
-config=Naming_Function,misnamed_entity_fmt+=
{hide,"kind(function)&&any_decl(loc(file(^.*_MOD1\.(h|c)$)))", "^MOD1_[a-zA-Z0-9]*$",""}
-config=Naming_Function,misnamed_entity_fmt+=
{hide,"kind(function)&&any_decl(loc(file(^.*_MOD2\.(h|c)$)))", "^MOD2_[a-zA-Z0-9]*$",""}
-config=Naming_Function,misnamed_entity_fmt+=
{show,"kind(function)", "^.*$",err_msg}
-doc_end

-doc_begin="Naming conventions for macros."
-clone_service=B.NAMING,Naming_Macro
-config=Naming_Macro,summary=
"Macro names shall be in uppercase with a prefix congruent with the module name"
-config=Naming_Macro,misnamed_macro_fmt=
{hide,"loc(file(^.*_MOD1\.(h|c)$))", "^MOD1_[A-Z0-9]*$",macro,""}
-config=Naming_Macro,misnamed_macro_fmt+=
{hide,"loc(file(^.*_MOD2\.(h|c)$))", "^MOD2_[A-Z0-9]*$",macro,""}
-config=Naming_Macro,misnamed_macro_fmt+=
{show,"any()", "^.*$",macro,err_msg}
-doc_end

The above configuration enforces the following naming rules:

  • function names shall have an uppercase prefix specifying the module name (e.g., “MOD1_fun()”);

  • macro names shall be preceded by the module prefix and has also to be declared in uppercase.

In our example, the source filenames follow the naming convention prefix_ModuleName.suffix (e.g., filename_MOD1.c). Making this assumption the module name can be inferred from the filename.

The misnamed_entity_fmt has been configured to check that the functions names follow the first rule, where the name of the module is taken from the filename.

Each module requires its own configuration: the first regular expression detects the entity to check, while the second checks the name of the function. If the function name is compatible with the file name no reports will be shown, otherwise the last row of the configuration will cause the reporting of the wrongly named function.

The last argument of the misnamed_macro_fmt (err_msg) can be used to provide a customizable error message (see the -fmt global configuration).

Entities and macros are treated differently by ECLAIR, for this reason two different configurations are required. misnamed_macro_fmt follows the same logics of misnamed_entity_fmt.

Configuration

See generic service options.

Option misnamed_entity_fmt
misnamed_entity_fmt
-config=B.NAMING,misnamed_entity_fmt={TAG, ENTITY_MATCHER, NAME_MATCHER, FMT},...

Specify entities and the misnaming matcher to be shown using a short-circuit sequence with message format.

The configuration’s content is an ordered tagged list of entity and misnaming matchers with message format; the hide-show tag and message format are associated with the first matching entity and name.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

ENTITY_MATCHER:

a -entity_selector identifier or a matcher expression used to select the entities.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

FMT:

format (see the -fmt global configuration content, template enttname__default_fmt) with fields:

node

entity description;

name

unqualified identifier;

kind

entity kind;

name_info_tag

tag returned by name matcher;

vocab_msg

vocabulary error message or ''.

Option misnamed_macro_fmt
misnamed_macro_fmt
-config=B.NAMING,misnamed_macro_fmt={TAG, MACRO_MATCHER, NAME_MATCHER, KIND, FMT},...

Specify macro and the misnaming matcher to be shown using a short-circuit sequence with message format.

The configuration’s content is an ordered tagged list of macro, name matcher, name-flag indicating if the macro name or the parameter names should be matched, and a message format; the hide-show tag is associated with the first matching macro and macro or parameter names (depending on the name-flag).

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

KIND:

whether to check macro or macro parameters. Accepted values are:

  • macro: macro name;

  • param: macro parameter;

  • any: macro name or macro parameters;

FMT:

format (see the -fmt global configuration content, template enttname__default_fmt) with fields:

node

macro or macro parameter;

name

the identifier;

kind

entity kind;

name_info_tag

tag returned by name matcher;

vocab_msg

vocabulary error message or ‘’.

Option misnamed_entity
misnamed_entity
-config=B.NAMING,misnamed_entity={ENTITY_MATCHER, NAME_MATCHER},...

Specify the entity and name matchers.

The configuration’s content is an ordered tagged list of entity and misnaming matchers; the hide-show tag is associated with the first matching entity and name.

ENTITY_MATCHER:

a -entity_selector identifier or a matcher expression used to select the entities.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

Option misnamed_macro
misnamed_macro
-config=B.NAMING,misnamed_macro={MACRO_MATCHER, NAME_MATCHER, KIND},...

Specify the macro and name matchers.

The configuration’s content is an ordered tagged list of macro, name matcher and name-flag indicating if the macro name or the parameter names should be matched; the hide-show tag is associated with the first matching macro and name(s).

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

NAME_MATCHER:

a -name_selector identifier or a matcher expression used to select the names.

KIND:

whether to check macro or macro parameters. Accepted values are:

  • macro: macro name;

  • param: macro parameter;

  • any: macro name or macro parameters;

Option declarations
declarations
-config=B.NAMING,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option macros
macros
-config=B.NAMING,macros={TAGS, MACRO_MATCHER},...

Specifies the report tags for macros.

The configuration’s content is a list of clauses specifying the macros and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Option all_decls
all_decls
-config=B.NAMING,all_decls=BOOL

Specify whether to show all or just a single representative declaration for each reported entity.

BOOL:

boolean indicating whether to show one or all declarations. Accepted values are:

  • true: show all declarations for each reported entity;

  • false: show a representative declaration for each reported entity;

Rule B.NARROWING

Summary

Narrowing integral to integral and pointer to integral casts are shown.

Configuration

See generic service options.

Rule B.NOMAGICC

Summary

Magic constants shall not be used.

Description

The explicit use of a constant literal is reported unless it is:

  • expanded from an object-like macro

  • a numeric literal appearing in the replacement list of an object-like macro whose fully expanded replacement list is an arithmetic constant expression

  • 0, 1 or 2 integer or floating literals, with optional suffixes

  • a character or string literal

  • a literal that appears in an initializer for a const or constexpr variable

  • a numeric literal used as part of the initializer of a const or constexpr object of class type

  • a scalar initializer for a const or constexpr variable that is a C-style cast or a static_cast of a literal

  • a literal that appears in a designated or list initializer for a const or constexpr variable

  • an initializer of an enum constant

Reports for selected literals can be tagged using the statements service configuration.

Configuration

See generic service options.

Option literal_matches
literal_matches
-config=B.NOMAGICC,literal_matches={TAG, {LIT_COND,...}},...

Specify what is a magic constant.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

LIT_COND:

literal condition. Accepted alternatives are:

  • {ancestors, CTXT}: .

    CTXT:

    a -context_selector identifier or a matcher expression used to select the contexts.

  • {text, TEXT_RE}: regular expression to match literal.

    TEXT_RE:

    constant text matcher.

  • {character_literal}: character literal.

  • {wide_char_literal}: wide char literal.

  • {utf16_char_literal}: utf16 char literal.

  • {utf32_char_literal}: utf32 char literal.

  • {floating_literal}: floating literal.

  • {integer_literal}: integer literal.

  • {string_literal}: string literal.

  • {wide_string_literal}: wide string literal.

  • {utf8_string_literal}: utf8 string literal.

  • {utf16_string_literal}: utf16 string literal.

  • {utf32_string_literal}: utf32 string literal.

Default:

-config=B.NOMAGICC,literal_matches={hide, {{integer_literal}, {text, "^(0|1|2)[LUlu]*$"}}}, {hide, {{floating_literal}, {text, "^(0|1|2)(\\.0*)?([eE][+-]?0+)?[FLflqQ]?$"}}}, {hide, {{character_literal}, {text, "^'.'$"}}}, {hide, {{string_literal}, {text, "^\".?\"$"}}}, {hide, {{ancestors, "skip(parent(__non_syntactic_or_paren_contexts||node(c_style_cast_expr||named_cast_expr)),is(init)&&parent(decl(__init_var_decls&&type(__const_top_level_types))))"}}}, {hide, {{ancestors, "skip(class(expr),node(temporary_object_expr)&&skip(class(expr),(is(init)&&parent(decl(__init_var_decls&&type(__const_top_level_types))))))"}}}, {hide, {{ancestors, "parent(skip(__non_syntactic_or_paren_contexts||node(c_style_cast_expr||named_cast_expr),node(designated_init_expr||init_list_expr)&&skip(class(expr),is(init)&&parent(decl(__init_var_decls&&type(__const_top_level_types))))))"}}}, {hide, {{ancestors, "skip(class(expr),is(init)&&parent(node(enum_constant_decl)))"}}}
Option literal_kinds
literal_kinds
-config=B.NOMAGICC,literal_kinds=LIT,...

Specify the kinds of literals to be checked.

{LIT,…}:

the literal families to be checked. Accepted members are:

  • floating_literal: floating literal;

  • integer_literal: integer literal;

  • character_literal: character literal;

  • string_literal: string literal;

  • ordinary: ordinary character or string literal;

  • wide: wide character or string literal;

  • utf16: utf16 character or string literal;

  • utf32: utf32 char literal;

  • utf8: utf8 string literal;

Default:

-config=B.NOMAGICC,literal_kinds=integer_literal, floating_literal
Option statements
statements
-config=B.NOMAGICC,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Rule B.ONESIDE

Summary

Except for function calls whose return value is stored, there should be no more than one side effect per expression.

Description

Reports:

  • An expression that has more than one side effect other than a function call whose return value is stored;

  • any expression whose value is ignored and has no side effects.Notes:

    • the side effect must be caused by the external operator/functor of the expression (and not just an effect of its sub-expressions);

    • explicit cast to void is not reported (see the corresponding Rule 2.2 on page 41 of MISRA C:2012 [43] ☞).

Configuration

See generic service options.

Option effects_count
effects_count
-config=B.ONESIDE,effects_count={TAGS, RANGE},...

>Specifies the report tags for effect counts.

The configuration’s content is a list of clauses specifying the effects count and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

RANGE:

range of number of effects. Accepted forms are:

  • MIN_MAX: the number of effects is in the range MIN_MAX

Option effects
effects
-config=B.ONESIDE,effects={TAGS, CONDS},...

Specifies the report tags for effects.

The configuration’s content is a list of report tags with a set of conditions on the effects found within the context specified by the guideline.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONDS:

the effects found in the expression and its context must match CONDS. Accepted forms are:

  • [+]AND_MATCHER: the effects matches AND_MATCHER

  • -AND_MATCHER: the effects does not match AND_MATCHER

  • [+]AND_MATCHER||CONDS: either the effects match AND_MATCHER or match EFFECT_MATCHER

  • -AND_MATCHER||CONDS: the effects do not match AND_MATCHER but do match CONDS

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the effects match BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the effects match BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CONDS): the effects match CONDS

  • !BASIC_MATCHER: the effects do not match BASIC_MATCHER

  • any(): any effects match

  • none(): no effects match

  • count(RANGE,EFFECT_MATCHER): the context’s effects must satisfy RANGE and EFFECT_MATCHER

  • empty stringEFFECT_KIND: one of the expression’s effects must match EFFECT_KIND

EFFECT_MATCHER

accepted forms are:

  • EFFECT_MATCHER[&&EFFECT_MATCHER]*): the constraint is one of the EFFECT_MATCHER

RANGE

accepted forms are:

  • all: there can be any number of effects

  • any: there must be at least one effect

  • MIN_MAX: the number of effects must be in the range MIN_MAX

EFFECT_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the effects matches AND_MATCHER

  • -AND_MATCHER: the effects does not match AND_MATCHER

  • [+]AND_MATCHER||EFFECT_MATCHER: either the effects match AND_MATCHER or match EFFECT_MATCHER

  • -AND_MATCHER||EFFECT_MATCHER: the effects do not match AND_MATCHER but do match EFFECT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the effects match BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the effects match BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (EFFECT_MATCHER): the effects match EFFECT_MATCHER

  • !BASIC_MATCHER: the effects do not match BASIC_MATCHER

  • any(): any effects match

  • none(): no effects match

  • EFFECT_KIND: an effect matches EFFECT_KIND

EFFECT_KIND

accepted forms are:

  • asm: an asm

  • call: a call

  • const: call with property const

  • exit: exit

  • indirect_jump: an indirect jump

  • jump: jump

  • leave: leave

  • loop: loop

  • noeffect: call with property noeffect

  • nothrow: call with property nothrow

  • pure: call with property pure

  • read: read

  • read_write: read/write

  • throw: throw

  • unevaluated: an unevaluated expression

  • volatile: reference to a volatile

  • write: write

Rule B.OVRDFINL

Summary

Override of virtual methods should use override or final keyword.

Configuration

See generic service options.

Rule B.PREPCMNT

Summary

Preprocessor directives ifdef, ifndef and if should be closed with an endif that is commented by the guard.

Configuration

See generic service options.

Rule B.PRSRDGNS

Summary

Code shall not generate a clang diagnostic message.

Description

Reports parser diagnostic messages that yield show according to the the diagnostics service configuration.

Note that, for this service, the report category is the diagnostic identifier.

Configuration

See generic service options.

Option diagnostics
diagnostics
-config=B.PRSRDGNS,diagnostics={TAGS, DIAG_TAG},...

Assigns report tags to the parser diagnostics.

The configuration’s content is a list of clauses specifying the diagnostics and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DIAG_TAG:

a -name_selector identifier or a matcher expression used to select the diagnostics. Accepted forms are:

  • ^REGEX$: the name matches ^REGEX$

  • !NAME_MATCHER: the name does not match NAME_MATCHER

  • TEXT: the name is TEXT

Rule B.PTRDECL

Summary

Do not declare entities using pointer types.

Description

An entity is reported if either:

  • it has a type involving pointers; or

  • it is a function whose return type involves pointers.

Configuration

See generic service options.

Option declarations
declarations
-config=B.PTRDECL,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule B.PTRUSE

Summary

Do not refer to entities having a type that uses pointer types.

Description

An expression is reported if it refers to an entity whose type involves pointers.

Configuration

See generic service options.

Option declarations
declarations
-config=B.PTRUSE,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule B.RECUMACR

Summary

A program should not contain recursive macro invocations.

Configuration

See generic service options.

Rule B.REDCAST

Summary

A program should not contain redundant casts.

Description

Reports any use of redundant casts. A redundant cast is a superfluous cast, where the source and destination types are the same.

Configuration

See generic service options.

Option casts
casts
-config=B.REDCAST,casts={TAGS, MATCHER},...

Specifies the report tags for casts.

The configuration’s content is a list of clauses specifying the casts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MATCHER:

comma-separated sequence of cast conditions. Accepted forms are:

  • [+]AND_MATCHER: the node matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||CAST_MATCHER: either the cast matches AND_MATCHER or it matches CAST_MATCHER

  • -AND_MATCHER||CAST_MATCHER: the cast does not match AND_MATCHER but does match CAST_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the cast matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the cast matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CAST_MATCHER): the cast matches CAST_MATCHER

  • !BASIC_MATCHER: the cast does not match BASIC_MATCHER

  • any(): any cast matches

  • none(): no cast matches

  • class(CAST_CLASS): the cast class is CAST_CLASS

  • context(CONTEXT_MATCHER): the cast is in a context matching CONTEXT_MATCHER (see the -context_selector global configuration)

  • from(FROM_MATCHER): the cast whose source expression matches FROM_MATCHER

  • syntactic(FROM_MATCHER)): the cast whose syntactic source expression (i.e., after removing all non-syntactic wrappers from the source) matches FROM_MATCHER

  • kind(CAST_KIND[||CAST_KIND]*): the cast kind is one of the CAST_KIND

  • language(LANGUAGE): the language is LANGUAGE

  • to(type(TYPE_MATCHER)): the cast whose destination type is matching TYPE_MATCHER (see the -type_selector global configuration)

  • relation(RELATION[||RELATION]*): the cast satisfies one of RELATION

CAST_KIND

accepted forms are:

  • no_op: no_op

  • address_space_conversion: address_space_conversion

  • array_to_pointer_decay: array_to_pointer_decay

  • atomic_to_non_atomic: atomic_to_non_atomic

  • base_to_derived: base_to_derived

  • base_to_derived_member_pointer: base_to_derived_member_pointer

  • bitcast: bitcast

  • boolean_to_signed_integral: boolean_to_signed_integral

  • builtin_function_to_pointer_decay: builtin_function_to_pointer_decay

  • constructor_conversion: constructor_conversion

  • dependent: dependent

  • derived_to_base: derived_to_base

  • derived_to_base_member_pointer: derived_to_base_member_pointer

  • dynamic: dynamic

  • floating_cast: floating_cast

  • floating_complex_cast: floating_complex_cast

  • floating_complex_to_boolean: floating_complex_to_boolean

  • floating_complex_to_integral_complex: floating_complex_to_integral_complex

  • floating_complex_to_real: floating_complex_to_real

  • floating_real_to_complex: floating_real_to_complex

  • floating_to_boolean: floating_to_boolean

  • floating_to_integral: floating_to_integral

  • function_to_pointer_decay: function_to_pointer_decay

  • integral_cast: integral_cast

  • integral_complex_cast: integral_complex_cast

  • integral_complex_to_boolean: integral_complex_to_boolean

  • integral_complex_to_floating_complex: integral_complex_to_floating_complex

  • integral_complex_to_real: integral_complex_to_real

  • integral_real_to_complex: integral_real_to_complex

  • integral_to_boolean: integral_to_boolean

  • integral_to_floating: integral_to_floating

  • integral_to_pointer: integral_to_pointer

  • lvalue_bitcast: lvalue_bitcast

  • lvalue_to_rvalue: lvalue_to_rvalue

  • member_pointer_to_boolean: member_pointer_to_boolean

  • non_atomic_to_atomic: non_atomic_to_atomic

  • null_to_member_pointer: null_to_member_pointer

  • null_to_pointer: null_to_pointer

  • pointer_to_boolean: pointer_to_boolean

  • pointer_to_integral: pointer_to_integral

  • reinterpret_member_pointer: reinterpret_member_pointer

  • to_union: to_union

  • to_void: to_void

  • unchecked_derived_to_base: unchecked_derived_to_base

  • user_defined_conversion: user_defined_conversion

  • vector_splat: vector_splat

CAST_CLASS

accepted forms are:

  • implicit: the cast is implicit

  • explicit: the cast is explicit

  • c_style: the cast is c_style

  • functional: the cast is functional

  • const: the cast is a const named cast

  • dynamic: the cast is a dynamic named cast

  • reinterpret: the cast is a reinterpret named cast

  • static: the cast is a static named cast

RELATION

accepted forms are:

  • : bigger_sizea cast to a bigger type

  • : bigger_size_pointeea cast from a pointer to another pointer with a bigger pointee

  • cast_away_const: a cast from a pointer to a const type to a pointer without the qualifier

  • cast_away_volatile: a cast from a pointer to a volatile type to a pointer without the qualifier

  • compatible_deep_unqualified: a cast from a type to a type that has the same pointee depth and where the innermost types without qualifiers are compatible

  • definitely_changes_value: a cast that definitely does change the source expression’s value

  • definitely_in_range: a cast whose cast value is definitely in the range of its type

  • definitely_out_range: a cast whose cast value is definitely out of range of its type

  • definitely_preserves_value: a cast that definitely does not change the source expression’s value

  • derived_to_virtual_base: a cast from a pointer to a class to a pointer to a virtual base class

  • enum_constant: a cast whose source expression is an enumeration constant and whose destination type is the same as the enumerator type

  • forget_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const or is void or Boolean

  • forget_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile or is void or Boolean

  • incompatible_unqualified_pointee: a cast from a pointer to a pointer with an incompatible unqualified pointee type

  • more_aligned_pointee: a cast from a pointer to a pointer with a more aligned pointee type

  • polymorphic_base_to_derived: a cast from a pointer to a base class with polymorphic type to a pointer to a derived class

  • qualification: a cast from a pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_from_void_pointee: a cast from a void pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_to_void_pointee: a cast from a pointer to void pointer where the destination pointee has all the qualifiers in the source pointee

  • same_type: a cast that does not change the type

  • same_unqualified_pointee: a cast from a pointer to a pointer with the same pointee type, ignoring any qualifications

  • signed_to_unsigned: a cast from a signed integral type to an unsigned integral type

  • unqualify_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const

  • unqualify_pointee: a cast from a pointer with a pointee type qualifier to another pointer whose pointee type does not have that qualifier

  • unqualify_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile

  • unqualify_atomic_pointee: a cast from a pointer with an _Atomic pointee type to another pointer whose pointee is not _Atomic

  • unsigned_to_signed: a cast from an unsigned integral type to a signed integral type

  • virtual_base_to_derived: a cast from a pointer to a virtual base class to a pointer to a derived class

FROM_MATCHER

accepted forms are:

  • type(TYPE_MATCHER): the type of the source expression matches TYPE_MATCHER (see the -type_selector global configuration)

  • expr(STMT_MATCHER): the source expression matches STMT_MATCHER (see the -stmt_selector global configuration)

LANGUAGE

accepted forms are:

  • c: C

  • cpp: C++

Rule B.REQMAN

Summary

Reports traceability of defined requirements.

Description

Here we just describe the main features of ECLAIR’s support for this service. For more information about how this may be integrated into a complete requirements management system see ECLAIR Requirements Management.

The service relies on a number of configuration parameters that define the project’s requirements and how code constructs relate (by means of special comments) to these requirements.

A requirement is a functionality of the software and its coverages are those aspects that directly relate to the code constructs and therefore are amenable to automatic checking.

The requirements are specified using the -requirements global configuration; this associates a requirement set identifier with a set of named requirements and a set of coverages. The coverages are specified using the -requirement_coverages global configuration that associates each coverage with a coverage tag and a (possibly empty) set of constraints.

The actual sets of requirements and coverages that are of interest to (a subset of) the project are specified by the -coverage_target service configuration.

A requirement comment is a comment that contains a coverage tag followed by a requirement identifier (extracted from the source code using the replacer specified by the -requirement_replacer service configuration).

A code construct is any declaration, statement or macro that matches a declaration, statement or macro matcher, specified by the -covering_construct service configuration. It can be associated to a requirement specification by means of one or more preceding comments (i.e., any comment before the code line with no intervening code or preprocessor lines).

ECLAIR will report a violation when a mismatch or an unexpected association is found between the configuration, comments and code constructs. For instance, when:

  • a selected code construct has no preceding comment;

  • a requirement comment does not precede a selected code construct;

  • a selected code construct has no associated requirement comment;

  • a requirement comment has unexpected text between requirement tags (i.e., something that is not a defined requirement identifier);

  • a requirement comment contains a duplicate requirement identifier;

  • the requirement coverage matcher from the -covering_construct service configuration used to select the construct does not match the requirement identifier and coverage tag in the associated requirement comment;

  • there is an inconsistency between requirements associated to selected code constructs for the same entity (e.g. the declaration(s) and the definition of a function).

Information reports are output for each valid requirement comment and its associated code construct.

Example:

The following configuration for -requirements associates the requirement set identifier impl_req to requirements {REQX, REQY} with coverage {IMPLEMENT} and the set identifier test_req to the requirement {REQZ} with coverages {IMPLEMENT, TEST}:

-requirements+={impl_req, {REQX, REQY}, {IMPLEMENT}}
-requirements+={test_req, {REQZ}, {IMPLEMENT, TEST}}

The following configuration for -requirement_coverages global configuration associates each coverage IMPLEMENT to the tag implements and TEST to the tag tests (note that, in both cases, the set of constraints is empty):

-requirement_coverages+={IMPLEMENT, "implements", {}}
-requirement_coverages+={TEST, "tests", {}}

The following configuration for -coverage_target service configuration indicates that code in all source files whose main source file is main.c must cover all the requirements in the requirement set impl_req for coverage IMPLEMENT:

-config=B.REQMAN,coverage_target={"main(^main\\.c$)", "set(impl_req)&&cov(IMPLEMENT)"}

The following configuration for the -covering_construct service configuration indicates that each function declaration (except for main()) should have a preceding comment that contains a requirement identifier in the set impl_req with coverage IMPLEMENT (and hence tag @implements or \implements):

-config=B.REQMAN,covering_construct={decl,
   "-^main(.*)$||kind(function)", "set(impl_req)&&cov(IMPLEMENT)"}

The acceptable forms of the requirement comment and how the requirements are extracted is specified using the -requirement_replacer service configuration. While it is possible to customize the extraction process, two templates called doxygen_comment and doxygen_line_comment that support the use of the coverage tags implements, tests and satisfies are available at REQMAN.ecl see (Coverages). The following configuration lines will support the use of this replacer:

-eval_file=REQMAN.ecl
-config=B.REQMAN,requirement_replacer+=doxygen_comment

Then assuming the project contains the file main.c:

/**
 * @implements REQX, REQY
 */
int f() {...}

this replacer will extract the tag implements and requirements REQX and REQY. Then ECLAIR, using all the example’s configuration lines shown above, will deduce that the coverage IMPLEMENT for the requirements REQX and REQY is covered by the function f().

Configuration

See generic service options.

Option coverage_target
coverage_target
-config=B.REQMAN,coverage_target={FRAME_MATCHER, REQCOV_MATCHER},...

Specify the analysis frames and the associated requirement coverage matchers that define the requirements and coverages that need to be fulfilled by the matched frames.

The configuration’s content is a frame matcher with requirement coverage matcher.

FRAME_MATCHER:

a frame matcher. Accepted forms are:

  • [+]AND_MATCHER: the frame matches AND_MATCHER

  • -AND_MATCHER: the frame does not match AND_MATCHER

  • [+]AND_MATCHER||FRAME_MATCHER: either the frame matches AND_MATCHER or it matches FRAME_MATCHER

  • -AND_MATCHER||FRAME_MATCHER: the frame does not match AND_MATCHER but does match FRAME_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the frame matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the frame matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (FRAME_MATCHER): the frame matches FRAME_MATCHER

  • !BASIC_MATCHER: the frame does not match BASIC_MATCHER

  • any(): any frame matches

  • none(): no frame matches

  • target(FILE_MATCHER): the target file matches FILE_MATCHER (see the -file_tag global configuration)

  • main(FILE_MATCHER): the main file matches FILE_MATCHER (see the -file_tag global configuration)

  • kind(FRAME_KIND[||FRAME_KIND]*): the frame has one of the kind FRAME_KINDs

  • std(STD_MATCHER): the unit frame has a standard that matches STD_MATCHER (see the -stds global configuration)

FRAME_KIND

accepted forms are:

  • unit: unit analysis frame

  • program: program analysis frame

  • project: project analysis frame

  • object: object analysis frame

  • command: command frame

REQCOV_MATCHER:

a requirement-coverage matcher. Accepted forms are:

  • [+]AND_MATCHER: the requirement-coverage matches AND_MATCHER

  • -AND_MATCHER: the requirement-coverage does not match AND_MATCHER

  • [+]AND_MATCHER||REQCOV_MATCHER: either the requirement-coverage matches AND_MATCHER or it matches REQCOV_MATCHER

  • -AND_MATCHER||REQCOV_MATCHER: the requirement-coverage does not match AND_MATCHER but does match REQCOV_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the requirement-coverage matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the requirement-coverage matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (REQCOV_MATCHER): the requirement-coverage matches REQCOV_MATCHER

  • !BASIC_MATCHER: the requirement-coverage does not match BASIC_MATCHER

  • any(): any requirement-coverage matches

  • none(): no requirement-coverage matches

  • set(SET[||SET]*): the requirement set matches one of SET

  • req(REQ[||REQ]*): the requirement matches one of REQ

  • cov(COV[||COV]*): the requirement coverage matches one of COV

  • regex: a regex matching SET/REQ/COV, where SET is a regular expression matching requirement sets (see the -requirements global configuration), REQ is a regular expression matching requirement identifiers and COV is a regular expression matching coverage identifiers (see the -requirement_coverages global configuration)

REGEX

accepted forms are:

Default:

-config=B.REQMAN,coverage_target={"any()", "any()"}
Option requirement_replacer
requirement_replacer
-config=B.REQMAN,requirement_replacer=ID,...

Specify the replacer that will extract a requirement tag and a requirement identifier from a comment (this extracted pair is referred to here as a tagged requirement).

The configuration’s content is a set of replacers to extract tagged requirements.

ID:

a replacer that matches the entire comment string (allowing for any whitespace characters) and extracts the tagged requirements; to save the tags for checking, use save(@0,A) where A specifies an extracted tagged requirement.

Default:

-config=B.REQMAN,requirement_replacer={}
Option covering_construct
covering_construct
-config=B.REQMAN,covering_construct={KIND, NODE_MATCHER, REQCOV_MATCHER},...

Specify the constructs that should have a comment tagged with a requirement identifier.

The configuration’s content is a list of matcher kinds with a matcher to select constructs that should have comments with tagged requirements.

KIND:

matcher kind. Accepted values are:

  • decl: constructs are declarations and the MATCHER is a -decl_selector identifier or a matcher expression used to select the declarations;

  • stmt: constructs are statements and the MATCHER is a -stmt_selector identifier or a matcher expression used to select the statements or the expressions;

  • macro: constructs are macros and the MATCHER is a -macro_selector identifier or a matcher expression used to select the macro;

NODE_MATCHER:

a declaration, statement or macro matcher expression used to select the matching constructs (see the -decl_selector, the -stmt_selector and the -macro_selector global configurations).

REQCOV_MATCHER:

a requirement-coverage matcher. Accepted forms are:

  • [+]AND_MATCHER: the requirement-coverage matches AND_MATCHER

  • -AND_MATCHER: the requirement-coverage does not match AND_MATCHER

  • [+]AND_MATCHER||REQCOV_MATCHER: either the requirement-coverage matches AND_MATCHER or it matches REQCOV_MATCHER

  • -AND_MATCHER||REQCOV_MATCHER: the requirement-coverage does not match AND_MATCHER but does match REQCOV_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the requirement-coverage matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the requirement-coverage matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (REQCOV_MATCHER): the requirement-coverage matches REQCOV_MATCHER

  • !BASIC_MATCHER: the requirement-coverage does not match BASIC_MATCHER

  • any(): any requirement-coverage matches

  • none(): no requirement-coverage matches

  • set(SET[||SET]*): the requirement set matches one of SET

  • req(REQ[||REQ]*): the requirement matches one of REQ

  • cov(COV[||COV]*): the requirement coverage matches one of COV

  • regex: a regex matching SET/REQ/COV, where SET is a regular expression matching requirement sets (see the -requirements global configuration), REQ is a regular expression matching requirement identifiers and COV is a regular expression matching coverage identifiers (see the -requirement_coverages global configuration)

REGEX

accepted forms are:

Default:

-config=B.REQMAN,covering_construct={decl, "!visibility(local)", "any()"}, {macro, "any()", "any()"}
Option comments
comments
-config=B.REQMAN,comments={TAGS, COMMENT_MATCHER},...

Specifies the report tags for comments.

The configuration’s content is a list of clauses specifying the comments and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

COMMENT_MATCHER:

a -comment_selector identifier or a matcher expression used to select the comments.

Option ignored_comments
ignored_comments
-config=B.REQMAN,ignored_comments=COMMENT_MATCHER,...

Specify the comments that should be ignored.

The configuration’s content is a list of comment matchers.

COMMENT_MATCHER:

a -comment_selector identifier or a matcher expression used to select the comments.

Rule B.SOURCE_RANGE

Summary

Source range pseudo-checker.

Configuration

See generic service options.

Rule B.STATINIT

Summary

Static storage declarations should have a complete initializer.

Configuration

See generic service options.

Option declarations
declarations
-config=B.STATINIT,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option zero_init
zero_init
-config=B.STATINIT,zero_init=COND,...

Special conditions for zero initialization.

{COND,…}:

conditions for zero initialization, if set is empty, then there are no conditions for zero-initialization. Accepted members are:

  • top_level: zero initialization must be at the top-level;

  • explicit_init: zero initialization must be explicit;

  • no_cast: zero initialization must be without cast;

  • null_to_pointer: zero initialization may have a null_to_pointer cast;

Default:

-config=B.STATINIT,zero_init={}

Rule B.STRNVCBL

Summary

The vocabulary used in string literals should be precisely defined in a way that is amenable to automatic checking.

Description

Reports if string literals use vocabulary not in the dictionaries. See vocabulary for more information about the vocabulary dictionaries and their use

Configuration

See generic service options.

Option good_words_file
good_words_file
-config=B.STRNVCBL,good_words_file=GOOD_WORDS

A file containing a list of words, one per line, all in lowercase, that can be used in the project (see string interpolation clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

GOOD_WORDS:

good words filename.

Default:

-config=B.STRNVCBL,good_words_file=""
Option bad_words_file
bad_words_file
-config=B.STRNVCBL,bad_words_file=BAD_WORDS

A file containing a list of words, one per line, all in lowercase, that cannot be used in the project (see string interpolatn clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

BAD_WORDS:

bad words filename.

Default:

-config=B.STRNVCBL,bad_words_file=""
Option good_items_file
good_items_file
-config=B.STRNVCBL,good_items_file=GOOD_ITEMS

A file containing a list of lexical items, one per line, that can be used in the project (see string interpolation clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

GOOD_ITEMS:

good items filename.

Default:

-config=B.STRNVCBL,good_items_file=""
Option bad_items_file
bad_items_file
-config=B.STRNVCBL,bad_items_file=BAD_ITEMS

A file containing a list of lexical items, one per line, that cannot be used in the project (see string interpolation clause for how to specify the file). For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

BAD_ITEMS:

bad items filename.

Default:

-config=B.STRNVCBL,bad_items_file=""
Option good_item_regexs
good_item_regexs
-config=B.STRNVCBL,good_item_regexs=GOOD_REGEX,...

A list of regular expressions matching good identifiers. For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

{GOOD_REGEX,…}:

regular expressions matching good identifiers. Accepted members are:

Default:

-config=B.STRNVCBL,good_item_regexs={}
Option bad_item_regexs
bad_item_regexs
-config=B.STRNVCBL,bad_item_regexs=BAD_REGEX,...

A list of regular expressions matching bad identifiers. For a detailed description see the dedicated entry in Section The Project Vocabulary Components.

{BAD_REGEX,…}:

regular expressions matching bad identifiers. Accepted members are:

Default:

-config=B.STRNVCBL,bad_item_regexs={}
Option project_dictionary
project_dictionary
-config=B.STRNVCBL,project_dictionary=PROJECT_DICT

The dictionary contains a list of words in lowercase that can be used in the project along with their frequencies (see string interpolation clause for how to specify the file).

PROJECT_DICT:

project dictionary filename.

Default:

-config=B.STRNVCBL,project_dictionary=""
Option context_dictionary
context_dictionary
-config=B.STRNVCBL,context_dictionary=CONTEXT_DICT

The dictionary contains a list of words in lowercase along with their frequencies (see string interpolation clause for how to specify the file). Note that the words and their frequencies are only used to assist the segmentation process.

CONTEXT_DICT:

context dictionary filename.

Default:

-config=B.STRNVCBL,context_dictionary=""
Option splitter_regexs
splitter_regexs
-config=B.STRNVCBL,splitter_regexs=SPLITTER,...

A list of regular expressions defining custom splitters.

{SPLITTER,…}:

set of regular expressions defining custom splitters. Accepted members are:

Default:

-config=B.STRNVCBL,splitter_regexs={}
Option segmentation_stops_after
segmentation_stops_after
-config=B.STRNVCBL,segmentation_stops_after=SAMURAI

Last step of the Samurai segmentation algorithm to be executed.

SAMURAI:

last step of the Samurai segmentation algorithm to be executed. Accepted values are:

  • none: no segmentation even on non-alpha characters;

  • underscore: segment on underscore characters;

  • non_alpha: segment on non-alpha characters;

  • lower_to_upper: segment on non-alpha and a change from lowercase to uppercase;

  • camel_case: segment on non-alpha, a change from lowercase to uppercase, and camel case;

  • no_case: segment on non-alpha, a change from lowercase to uppercase, camel case, and a score-based heuristics that is independent of any case consideration unless the word length exceeds the max-no-case-length value;

Default:

-config=B.STRNVCBL,segmentation_stops_after=camel_case
Option max_no_case_length
max_no_case_length
-config=B.STRNVCBL,max_no_case_length=MAX_LEN

The maximum length of a string upon which the “no case” step of the Samurai segmentation algorithm is applied.

MAX_LEN:

maximum string length for “no case” segmentation. It must be an integer greater than or equal to 2.

Default:

-config=B.STRNVCBL,max_no_case_length=16
Option string_splitter
string_splitter
-config=B.STRNVCBL,string_splitter=SPLITTER,...

A list of regular expressions defining string literal splitters.

{SPLITTER,…}:

set of regular expressions defining custom splitters. Accepted members are:

Option contexts
contexts
-config=B.STRNVCBL,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Rule B.SYSTEM_REFERENCE

Summary

System code referenced by user is shown.

Configuration

See generic service options.

Rule B.TIE

Summary

Sample rule for service combining.

Configuration

See generic service options.

Option services
services
-config=B.TIE,services={TAG, SERVICE_MATCHER},...

Specifies the services to be suppressed.

The configuration’s content is a short-circuit sequence clause for suppressing services.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

SERVICE_MATCHER:

an ancillary service matching SERVICE_MATCHER (see the -service_selector global configuration).

Rule B.TROJANSOURCE

Summary

Source code shall not contain underhanded UTF-8 characters.

Description

Reports underhanded UTF-8 characters in source code.

Configuration

See generic service options.

Rule B.UNEVALEFF

Summary

The operand of the sizeof, alignof and typeof operators shall not contain any expression which has potential side effects.

Configuration

See generic service options.

Option effects
effects
-config=B.UNEVALEFF,effects={TAGS, CONDS},...

Specifies the report tags for effects.

The configuration’s content is a list of report tags with a set of conditions on the effects found within the context specified by the guideline.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONDS:

the effects found in the expression and its context must match CONDS. Accepted forms are:

  • [+]AND_MATCHER: the effects matches AND_MATCHER

  • -AND_MATCHER: the effects does not match AND_MATCHER

  • [+]AND_MATCHER||CONDS: either the effects match AND_MATCHER or match EFFECT_MATCHER

  • -AND_MATCHER||CONDS: the effects do not match AND_MATCHER but do match CONDS

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the effects match BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the effects match BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CONDS): the effects match CONDS

  • !BASIC_MATCHER: the effects do not match BASIC_MATCHER

  • any(): any effects match

  • none(): no effects match

  • count(RANGE,EFFECT_MATCHER): the context’s effects must satisfy RANGE and EFFECT_MATCHER

  • empty stringEFFECT_KIND: one of the expression’s effects must match EFFECT_KIND

EFFECT_MATCHER

accepted forms are:

  • EFFECT_MATCHER[&&EFFECT_MATCHER]*): the constraint is one of the EFFECT_MATCHER

RANGE

accepted forms are:

  • all: there can be any number of effects

  • any: there must be at least one effect

  • MIN_MAX: the number of effects must be in the range MIN_MAX

EFFECT_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the effects matches AND_MATCHER

  • -AND_MATCHER: the effects does not match AND_MATCHER

  • [+]AND_MATCHER||EFFECT_MATCHER: either the effects match AND_MATCHER or match EFFECT_MATCHER

  • -AND_MATCHER||EFFECT_MATCHER: the effects do not match AND_MATCHER but do match EFFECT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the effects match BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the effects match BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (EFFECT_MATCHER): the effects match EFFECT_MATCHER

  • !BASIC_MATCHER: the effects do not match BASIC_MATCHER

  • any(): any effects match

  • none(): no effects match

  • EFFECT_KIND: an effect matches EFFECT_KIND

EFFECT_KIND

accepted forms are:

  • asm: an asm

  • call: a call

  • const: call with property const

  • exit: exit

  • indirect_jump: an indirect jump

  • jump: jump

  • leave: leave

  • loop: loop

  • noeffect: call with property noeffect

  • nothrow: call with property nothrow

  • pure: call with property pure

  • read: read

  • read_write: read/write

  • throw: throw

  • unevaluated: an unevaluated expression

  • volatile: reference to a volatile

  • write: write

Rule B.UNUSED

Summary

Pseudo-checker for unuslocl and unusproj servants.

Configuration

See generic service options.

Option declarations
declarations
-config=B.UNUSED,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option all_decls
all_decls
-config=B.UNUSED,all_decls=BOOL

Specify whether to show all or just a single representative declaration for each reported entity.

BOOL:

boolean indicating whether to show one or all declarations. Accepted values are:

  • true: show all declarations for each reported entity;

  • false: show a representative declaration for each reported entity;

Rule B.UNUSLABL

Summary

Each label statement must be used either in a direct goto statement or its address must be taken and there is an indirect goto statement.

Configuration

See generic service options.

Option statements
statements
-config=B.UNUSLABL,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

The BUGSENG Tools

Tool B.CALLGRPH_DOT

Summary

Export callgrph edges to a representation that can be rendered with graphviz.

Description

Export callgrph edges to a representation that can be rendered with graphviz.

Configuration

See generic service options.

Option output_dot
output_dot
-config=B.CALLGRPH_DOT,output_dot=OUTPUT

The output file: for outputting the generated graph in dot format.

OUTPUT:

output file name.

Default:

-config=B.CALLGRPH_DOT,output_dot=/dev/stdout
Option ignored_edges
ignored_edges
-config=B.CALLGRPH_DOT,ignored_edges=EDGE_MATCHER

Specifies which call edges should be ignored to determine the reachability of entities.

EDGE_MATCHER:

matcher that defines the call edges that are ignored to delimit the reachability perimeter. Accepted forms are:

  • [+]AND_MATCHER: the edge matches AND_MATCHER

  • -AND_MATCHER: the edge does not match AND_MATCHER

  • [+]AND_MATCHER||EDGE_MATCHER: either the node matches AND_MATCHER or it matches EDGE_MATCHER

  • -AND_MATCHER||EDGE_MATCHER: the node does not match AND_MATCHER but does match EDGE_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the node matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the node matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (EDGE_MATCHER): the node matches EDGE_MATCHER

  • !BASIC_MATCHER: the node does not match BASIC_MATCHER

  • from(ENTITY_MATCHER): a -entity_selector identifier or a matcher expression used to select the caller entity in the call edge

  • from_top: the node is reachable from a program entrypoint

  • from_type(^REGEX$): the caller is type that matches ^REGEX$

  • to(ENTITY_MATCHER): a -entity_selector identifier or a matcher expression used to select the callee entity in the call edge

  • to_type(^REGEX$): the callee is type that matches ^REGEX$

  • node(loc(LOC_MATCHER)): an edge whose callee location matches the -loc_selector

  • when(EDGE_WHEN[||EDGE_WHEN]*): an edge that is traversed on a control flow path specified by EDGE_WHEN

  • etime(EDGE_ETIME[||EDGE_ETIME]*): an edge that is executed at a time specified by EDGE_ETIME

EDGE_WHEN

accepted forms are:

  • normal: normal control flow execution

  • lifetime_end: control flow executed when the lifetime of the object ends

  • exception: control flow executed on exceptional paths

EDGE_ETIME

accepted forms are:

  • run: edge traversed at runtime

  • compile: edge traversed at compile time

Tool B.CBT

Summary

Tag reports using ECLAIR style comments.

Description

ECLAIR comment-based reports tagger.

Configuration

See generic service options.

Option remap
remap
-config=B.CBT,remap={FROM, TO},...

Specifies the remapping between comment content and ECLAIR services for suppression comments.

The configuration’s content is a list of pairs for remaps to be done.

FROM:

the content to be hidden as written in the comment.

TO:

a -service_selector identifier or a matcher expression used to select services whose report should be suppressed.

Default:

-config=B.CBT,remap={}

Tool B.CERTRAN

Summary

Collect build data for the automatic generation of compiler validation configurations.

Description

Note

This service is part of the cerTran product, which is separately licensed.

Configuration

See generic service options.

Option sort_options
sort_options
-config=B.CERTRAN,sort_options=sort_options

Whether options can be reordered.

sort_options:

whether options can be reordered. Accepted values are:

  • true: true;

  • false: false;

Default:

-config=B.CERTRAN,sort_options=true
Option ignored_options
ignored_options
-config=B.CERTRAN,ignored_options=OPTION_MATCHER,...

Specify the options that should be ignored.

The configuration’s content is a list of options matchers.

OPTION_MATCHER:

a -option_selector identifier or a matcher expression used to select the options.

Option output_csv
output_csv
-config=B.CERTRAN,output_csv=FILE

The CSV output file.

FILE:

output CSV file.

Option output_json
output_json
-config=B.CERTRAN,output_json=FILE

The JSON output file.

FILE:

output JSON file.

Option output_txt
output_txt
-config=B.CERTRAN,output_txt=FILE

The text output file.

FILE:

output text file.

Option output_xml
output_xml
-config=B.CERTRAN,output_xml=FILE

The XML output file.

FILE:

output XML file.

Option output_yaml
output_yaml
-config=B.CERTRAN,output_yaml=FILE

The YAML output file.

FILE:

output YAML file.

Tool B.DECLFIND

Summary

Report declarations matching arbitrary conditions.

Description

Pseudo checker for checking decl matchers.

Configuration

See generic service options.

Option declarations
declarations
-config=B.DECLFIND,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option decl_select
decl_select
-config=B.DECLFIND,decl_select={TAG, FIXME, {EVID,...}, FMT},...

Specify declarations with formats to be reported.

TAG:

a report tag. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • error: show as error report if it matches the associated conditions;

  • caution: show as a caution report if it matches the associated conditions;

  • information: show as an information report if it matches the associated conditionsbugs will be reported as information;

  • violation: show as violation report if it matches the associated conditions;

FIXME:

a -decl_selector identifier or a matcher expression used to select the declarations.

{EVID,…}

Accepted members are:

  • redeclared: any redeclaration is included as evidence;

FMT:

format (see the -fmt global configuration content, template declslct__default_fmt).

Default:

-config=B.DECLFIND,decl_select={}
Option extra_declarations
extra_declarations
-config=B.DECLFIND,extra_declarations={FIXME, {EVID,...}},...

Specify which declarations, in addition to the non-compliant ones, must be reported for information purposes.

FIXME:

a -decl_selector identifier or a matcher expression used to select the declarations.

{EVID,…}

Accepted members are:

  • redeclared: any redeclaration is included as evidence;

Default:

-config=B.DECLFIND,extra_declarations={}

Tool B.ECL

Summary

Reports unused ECL configurations.

Configuration

See generic service options.

Option configs
configs
-config=B.ECL,configs={CONFIG, ROW},...

Specify configuration explanations to be shown.

The configuration’s content is a set of configuration rows to be shown.

CONFIG:

config matcher. Accepted forms are:

  • [+]AND_MATCHER: the config matches AND_MATCHER

  • -AND_MATCHER: the config does not match AND_MATCHER

  • [+]AND_MATCHER||CONFIG_MATCHER: either the config matches AND_MATCHER or it matches CONFIG_MATCHER

  • -AND_MATCHER||CONFIG_MATCHER: the config does not match AND_MATCHER but does match CONFIG_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the config matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the config matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CONFIG_MATCHER): the config matches CONFIG_MATCHER

  • !BASIC_MATCHER: the config does not match BASIC_MATCHER

  • any(): any config matches

  • none(): no config matches

  • ^REGEX$: the config name matches ^REGEX$

  • any_row(ROW_MATCHER): the config has a row that matches ROW_MATCHER

  • all_row(ROW_MATCHER): all the config rows match ROW_MATCHER

  • kind(ID): the config kind is ID

  • service(SERVICE_MATCHER): the config whose service is matching SERVICE_MATCHER (see the -service_selector global configuration)

  • tracked(): the config is tracked

REGEX

accepted forms are:

ROW:

config row matches. Accepted forms are:

  • [+]AND_MATCHER: the config row matches AND_MATCHER

  • -AND_MATCHER: the config row does not match AND_MATCHER

  • [+]AND_MATCHER||ROW_MATCHER: either the config row matches AND_MATCHER or it matches ROW_MATCHER

  • -AND_MATCHER||ROW_MATCHER: the config row does not match AND_MATCHER but does match ROW_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the config row matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the config matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (ROW_MATCHER): the config row matches ROW_MATCHER

  • !BASIC_MATCHER: the config does not match BASIC_MATCHER

  • any(): any config row matches

  • none(): no config row matches

  • ^REGEX$: the config name matches ^REGEX$

  • user(): the config row is a user row

  • used(): the config row is used

REGEX

accepted forms are:

Default:

-config=B.ECL,configs={"tracked()", "!used()&&user()"}

Tool B.EXPLAIN

Summary

Explain user configuration.

Configuration

See generic service options.

Option ecl
ecl
-config=B.EXPLAIN,ecl=TAG

Specify if ECL commands should be shown.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

Default:

-config=B.EXPLAIN,ecl=show
Option configs
configs
-config=B.EXPLAIN,configs={CONFIG, ROW},...

Specify configuration explanations to be shown.

The configuration’s content is a set of configuration rows to be shown.

CONFIG:

config matcher. Accepted forms are:

  • [+]AND_MATCHER: the config matches AND_MATCHER

  • -AND_MATCHER: the config does not match AND_MATCHER

  • [+]AND_MATCHER||CONFIG_MATCHER: either the config matches AND_MATCHER or it matches CONFIG_MATCHER

  • -AND_MATCHER||CONFIG_MATCHER: the config does not match AND_MATCHER but does match CONFIG_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the config matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the config matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CONFIG_MATCHER): the config matches CONFIG_MATCHER

  • !BASIC_MATCHER: the config does not match BASIC_MATCHER

  • any(): any config matches

  • none(): no config matches

  • ^REGEX$: the config name matches ^REGEX$

  • any_row(ROW_MATCHER): the config has a row that matches ROW_MATCHER

  • all_row(ROW_MATCHER): all the config rows match ROW_MATCHER

  • kind(ID): the config kind is ID

  • service(SERVICE_MATCHER): the config whose service is matching SERVICE_MATCHER (see the -service_selector global configuration)

  • tracked(): the config is tracked

REGEX

accepted forms are:

ROW:

config row matches. Accepted forms are:

  • [+]AND_MATCHER: the config row matches AND_MATCHER

  • -AND_MATCHER: the config row does not match AND_MATCHER

  • [+]AND_MATCHER||ROW_MATCHER: either the config row matches AND_MATCHER or it matches ROW_MATCHER

  • -AND_MATCHER||ROW_MATCHER: the config row does not match AND_MATCHER but does match ROW_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the config row matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the config matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (ROW_MATCHER): the config row matches ROW_MATCHER

  • !BASIC_MATCHER: the config does not match BASIC_MATCHER

  • any(): any config row matches

  • none(): no config row matches

  • ^REGEX$: the config name matches ^REGEX$

  • user(): the config row is a user row

  • used(): the config row is used

REGEX

accepted forms are:

Default:

-config=B.EXPLAIN,configs={"any()", "user()"}

Tool B.EXPLAIN_ECL

Summary

Report explained configuration attached to related ECL commands.

Configuration

See generic service options.

Option configs
configs
-config=B.EXPLAIN_ECL,configs={CONFIG, ROW},...

Specify configuration explanations to be shown.

The configuration’s content is a set of configuration rows to be shown.

CONFIG:

config matcher. Accepted forms are:

  • [+]AND_MATCHER: the config matches AND_MATCHER

  • -AND_MATCHER: the config does not match AND_MATCHER

  • [+]AND_MATCHER||CONFIG_MATCHER: either the config matches AND_MATCHER or it matches CONFIG_MATCHER

  • -AND_MATCHER||CONFIG_MATCHER: the config does not match AND_MATCHER but does match CONFIG_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the config matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the config matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CONFIG_MATCHER): the config matches CONFIG_MATCHER

  • !BASIC_MATCHER: the config does not match BASIC_MATCHER

  • any(): any config matches

  • none(): no config matches

  • ^REGEX$: the config name matches ^REGEX$

  • any_row(ROW_MATCHER): the config has a row that matches ROW_MATCHER

  • all_row(ROW_MATCHER): all the config rows match ROW_MATCHER

  • kind(ID): the config kind is ID

  • service(SERVICE_MATCHER): the config whose service is matching SERVICE_MATCHER (see the -service_selector global configuration)

  • tracked(): the config is tracked

REGEX

accepted forms are:

ROW:

config row matches. Accepted forms are:

  • [+]AND_MATCHER: the config row matches AND_MATCHER

  • -AND_MATCHER: the config row does not match AND_MATCHER

  • [+]AND_MATCHER||ROW_MATCHER: either the config row matches AND_MATCHER or it matches ROW_MATCHER

  • -AND_MATCHER||ROW_MATCHER: the config row does not match AND_MATCHER but does match ROW_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the config row matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the config matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (ROW_MATCHER): the config row matches ROW_MATCHER

  • !BASIC_MATCHER: the config does not match BASIC_MATCHER

  • any(): any config row matches

  • none(): no config row matches

  • ^REGEX$: the config name matches ^REGEX$

  • user(): the config row is a user row

  • used(): the config row is used

REGEX

accepted forms are:

Default:

-config=B.EXPLAIN_ECL,configs={"kind(ordered)&&(any_row(user())||tracked()&&any_row(used()))", "any()"}, {"tracked()", "used()||user()"}, {"service(enabled)||service(none())", "any()"}, {"any()", "user()"}

Tool B.EXPLAIN_FULL

Summary

Explain used configuration.

Configuration

See generic service options.

Option ecl
ecl
-config=B.EXPLAIN_FULL,ecl=TAG

Specify if ECL commands should be shown.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

Default:

-config=B.EXPLAIN_FULL,ecl=show
Option configs
configs
-config=B.EXPLAIN_FULL,configs={CONFIG, ROW},...

Specify configuration explanations to be shown.

The configuration’s content is a set of configuration rows to be shown.

CONFIG:

config matcher. Accepted forms are:

  • [+]AND_MATCHER: the config matches AND_MATCHER

  • -AND_MATCHER: the config does not match AND_MATCHER

  • [+]AND_MATCHER||CONFIG_MATCHER: either the config matches AND_MATCHER or it matches CONFIG_MATCHER

  • -AND_MATCHER||CONFIG_MATCHER: the config does not match AND_MATCHER but does match CONFIG_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the config matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the config matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CONFIG_MATCHER): the config matches CONFIG_MATCHER

  • !BASIC_MATCHER: the config does not match BASIC_MATCHER

  • any(): any config matches

  • none(): no config matches

  • ^REGEX$: the config name matches ^REGEX$

  • any_row(ROW_MATCHER): the config has a row that matches ROW_MATCHER

  • all_row(ROW_MATCHER): all the config rows match ROW_MATCHER

  • kind(ID): the config kind is ID

  • service(SERVICE_MATCHER): the config whose service is matching SERVICE_MATCHER (see the -service_selector global configuration)

  • tracked(): the config is tracked

REGEX

accepted forms are:

ROW:

config row matches. Accepted forms are:

  • [+]AND_MATCHER: the config row matches AND_MATCHER

  • -AND_MATCHER: the config row does not match AND_MATCHER

  • [+]AND_MATCHER||ROW_MATCHER: either the config row matches AND_MATCHER or it matches ROW_MATCHER

  • -AND_MATCHER||ROW_MATCHER: the config row does not match AND_MATCHER but does match ROW_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the config row matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the config matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (ROW_MATCHER): the config row matches ROW_MATCHER

  • !BASIC_MATCHER: the config does not match BASIC_MATCHER

  • any(): any config row matches

  • none(): no config row matches

  • ^REGEX$: the config name matches ^REGEX$

  • user(): the config row is a user row

  • used(): the config row is used

REGEX

accepted forms are:

Default:

-config=B.EXPLAIN_FULL,configs={"kind(ordered)&&(any_row(user())||tracked()&&any_row(used()))", "any()"}, {"tracked()", "used()||user()"}, {"service(enabled)||service(none())", "any()"}, {"any()", "user()"}

Tool B.FRAMES

Summary

Report analysis frames matching specific criteria.

Description

Given the expected command of a frame as a regex reports inconsistencies with the actual command given.

Configuration

See generic service options.

Option frame_select
frame_select
-config=B.FRAMES,frame_select={TAG, MATCHER, FMT},...

Specify frames to be shown using a short-circuit sequence.

The configuration’s content is a list of frame matchers with formats.

TAG:

a report tag. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • error: show as error report if it matches the associated conditions;

  • caution: show as a caution report if it matches the associated conditions;

  • information: show as an information report if it matches the associated conditionsbugs will be reported as information;

  • violation: show as violation report if it matches the associated conditions;

MATCHER:

a -frame_selector identifier or a matcher expression used to select the frames.

FMT:

format (see the -fmt global configuration content, template frameslct__default_fmt).

Tool B.LINTCBT

Summary

Hide reports using lint style suppression comments.

Description

Interprets lint comment-based suppressions.

Configuration

See generic service options.

Option remap
remap
-config=B.LINTCBT,remap={FROM, TO},...

Specifies the remapping between comment content and ECLAIR services for suppression comments.

The configuration’s content is a list of pairs for remaps to be done.

FROM:

the content to be hidden as written in the comment.

TO:

a -service_selector identifier or a matcher expression used to select services whose report should be suppressed.

Default:

-config=B.LINTCBT,remap={}

Tool B.MACROS

Summary

Project level summary of macro expansions is shown.

Description

Each selected macro definition is shown if:

  • it is unused;

  • it expands to a sequence of tokens starting and ending on edges of AST nodes (any declarations, expressions, statements or types), with the expanded text;

  • it expands to a sequence of tokens in a preprocessor condition, with the expanded text;

Notes:

  • by default, all macros are checked and, for each expansion text, one sample is shown;

  • the macros and the maximum number of samples to be shown for any code resulting from the expansion of a selected macro can be specified using the macro_expansion service configuration;

  • the preferred samples that are shown can be changed using the sample_reports service configuration.

For example, the following configure line indicates that only function-like macros should be reported and that one sample for each expanded value should be shown:

-doc="Show only function like macros with one sample for each identical expansion."
-config=B.MACROS,macro_expansion={"function_like()", 1}

Configuration

See generic service options.

Option macro_expansion
macro_expansion
-config=B.MACROS,macro_expansion={MACRO, MAX},...

Specify macro selectors with sample size for expansions that have the same text.

The configuration’s content is macro selectors with sample size for expansions that have the same text.

MACRO:

a -macro_selector identifier or a matcher expression used to select the macros.

MAX:

unlimited or the maximum number of samples to be shown.

Option sample_reports
sample_reports
-config=B.MACROS,sample_reports={TAG, REPORT_MATCHER},...

Specifies the sample reports that should be shown/counted.

The configuration’s content is a short-circuit sequence specifying the reports to be chosen as samples.

TAG:

a short-circuit sequence for sample reports. Accepted values are:

  • hide: discard if it matches the associated conditions;

  • hate: avoid when possible if it matches the associated conditions;

  • kill: ignore if it matches the associated conditions;

  • show: show if it matches the associated conditions;

REPORT_MATCHER:

a -report_selector identifier or a matcher expression used to select the reports.

Option output_csv
output_csv
-config=B.MACROS,output_csv=FILE

The CSV output file.

FILE:

output CSV file.

Option output_json
output_json
-config=B.MACROS,output_json=FILE

The JSON output file.

FILE:

output JSON file.

Option output_txt
output_txt
-config=B.MACROS,output_txt=FILE

The text output file.

FILE:

output text file.

Option output_xml
output_xml
-config=B.MACROS,output_xml=FILE

The XML output file.

FILE:

output XML file.

Option output_yaml
output_yaml
-config=B.MACROS,output_yaml=FILE

The YAML output file.

FILE:

output YAML file.

Tool B.OBJCMP

Summary

Built object files should not differ from the reference ones.

Description

Built object files that differ from the reference ones are shown

It is crucial to realize the importance of this tool, especially in connection with the coding rules that many perceive it as simply cosmetic.

Consider, for instance, a rule insisting on the presence of parentheses.

Without B.OBJCOMP it is true that making an existing project compliant might introduce bugs; so, in that case, accepting non-compliance might be the wisest choice.

The situation is completely reversed when B.OBJCOMP is used to monitor the work done to bring the project into compliance.

Say we add a pair of parentheses; there are two cases:

  1. B.OBJCOMP reports nothing: we are sure we did not introduce a bug and we increased readability, something that will pay off in the future;

  2. B.OBJCOMP reports object code changes; looking carefully at what we did, we will discover either:

    • we added parentheses in the wrong positions: no problem, we move them to the right positions;

    • we added parentheses in the right positions; that is, we discovered a genuine bug in our project and we can now fix it.

Implementation

The build is tracked and complete information about the produced object files is saved into NEW_DIR (see the new_dir service configuration).

If OLD_DIR (see the old_dir service configuration) exists and contains information about a certain object file that is different from the newly generated information, then the compilation producing that object is shown.

A new reference point can be created by the user at any time by copying or renaming NEW_DIR to OLD_DIR (e.g., by rd /s /q OLD_DIR followed by xcopy NEW_DIR OLD_DIR /s or rename NEW_DIR OLD_DIR, on Windows; by rm -rf NEW_DIR followed by cp -R OLD_DIR NEW_DIR or mv OLD_DIR NEW_DIR, on Linux and macOS).

Configuration

See generic service options.

Option old_dir
old_dir
-config=B.OBJCMP,old_dir=OLD_DIR

Specify where the information on old objects is stored.

OLD_DIR:

pathname of the directory containing old objects.

Default:

-config=B.OBJCMP,old_dir=/tmp/old
Option new_dir
new_dir
-config=B.OBJCMP,new_dir=NEW_DIR

Specify where to store information on the new objects.

NEW_DIR:

pathname of the directory where to store new objects.

Default:

-config=B.OBJCMP,new_dir=/tmp/new

Tool B.OBJTOUCH

Summary

Objects produced by the build are touched.

Description

Each object file produced by the tracked build is touched, i.e., its access and modification times are set to the current time.

Configuration

See generic service options.

Tool B.PRQACBT

Summary

Hide reports using PRQA style suppression comments.

Description

Interprets PRQA comment-based suppressions.

Configuration

See generic service options.

Option remap
remap
-config=B.PRQACBT,remap={FROM, TO},...

Specifies the remapping between comment content and ECLAIR services for suppression comments.

The configuration’s content is a list of pairs for remaps to be done.

FROM:

the content to be hidden as written in the comment.

TO:

a -service_selector identifier or a matcher expression used to select services whose report should be suppressed.

Default:

-config=B.PRQACBT,remap={}

Tool B.PSOFTCBT

Summary

Hide reports using parasoft style suppression comments.

Description

Interprets parasoft comment-based suppressions.

Configuration

See generic service options.

Option remap
remap
-config=B.PSOFTCBT,remap={FROM, TO},...

Specifies the remapping between comment content and ECLAIR services for suppression comments.

The configuration’s content is a list of pairs for remaps to be done.

FROM:

the content to be hidden as written in the comment.

TO:

a -service_selector identifier or a matcher expression used to select services whose report should be suppressed.

Default:

-config=B.PSOFTCBT,remap={}

Tool B.SCOUT

Summary

All callable entities that are possibly reachable from program entry points are shown.

Description

For general information about this tool and some illustrative examples, see ECLAIR Code Scout.

Configuration

See generic service options.

Option declarations
declarations
-config=B.SCOUT,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option ignored_edges
ignored_edges
-config=B.SCOUT,ignored_edges=EDGE_MATCHER

Specifies which call edges should be ignored to determine the reachability of entities.

EDGE_MATCHER:

matcher that defines the call edges that are ignored to delimit the reachability perimeter. Accepted forms are:

  • [+]AND_MATCHER: the edge matches AND_MATCHER

  • -AND_MATCHER: the edge does not match AND_MATCHER

  • [+]AND_MATCHER||EDGE_MATCHER: either the node matches AND_MATCHER or it matches EDGE_MATCHER

  • -AND_MATCHER||EDGE_MATCHER: the node does not match AND_MATCHER but does match EDGE_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the node matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the node matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (EDGE_MATCHER): the node matches EDGE_MATCHER

  • !BASIC_MATCHER: the node does not match BASIC_MATCHER

  • from(ENTITY_MATCHER): a -entity_selector identifier or a matcher expression used to select the caller entity in the call edge

  • from_top: the node is reachable from a program entrypoint

  • from_type(^REGEX$): the caller is type that matches ^REGEX$

  • to(ENTITY_MATCHER): a -entity_selector identifier or a matcher expression used to select the callee entity in the call edge

  • to_type(^REGEX$): the callee is type that matches ^REGEX$

  • node(loc(LOC_MATCHER)): an edge whose callee location matches the -loc_selector

  • when(EDGE_WHEN[||EDGE_WHEN]*): an edge that is traversed on a control flow path specified by EDGE_WHEN

  • etime(EDGE_ETIME[||EDGE_ETIME]*): an edge that is executed at a time specified by EDGE_ETIME

EDGE_WHEN

accepted forms are:

  • normal: normal control flow execution

  • lifetime_end: control flow executed when the lifetime of the object ends

  • exception: control flow executed on exceptional paths

EDGE_ETIME

accepted forms are:

  • run: edge traversed at runtime

  • compile: edge traversed at compile time

Option output_ecl
output_ecl
-config=B.SCOUT,output_ecl=FILE

Output ECL file.

FILE:

output ECL file.

Default:

-config=B.SCOUT,output_ecl=""
Option ecl_selector
ecl_selector
-config=B.SCOUT,ecl_selector=SELECTOR_NAME

Entity selector identifier.

SELECTOR_NAME:

name of the entity selector written to FILE.

Default:

-config=B.SCOUT,ecl_selector=reachable
Option output_csv
output_csv
-config=B.SCOUT,output_csv=FILE

The CSV output file.

FILE:

output CSV file.

Option output_json
output_json
-config=B.SCOUT,output_json=FILE

The JSON output file.

FILE:

output JSON file.

Option output_txt
output_txt
-config=B.SCOUT,output_txt=FILE

The text output file.

FILE:

output text file.

Option output_xml
output_xml
-config=B.SCOUT,output_xml=FILE

The XML output file.

FILE:

output XML file.

Option output_yaml
output_yaml
-config=B.SCOUT,output_yaml=FILE

The YAML output file.

FILE:

output YAML file.

Tool B.STMTFIND

Summary

Report expression and statements matching arbitrary conditions.

Description

Pseudo checker for checking stmt selectors.

Configuration

See generic service options.

Option stmt_select
stmt_select
-config=B.STMTFIND,stmt_select={TAG, STMT_CONTEXT_SELECTOR, {{Id, Loc_Kind, FMT},...}},...

Specify statements or expressions and their contexts with formats to be reported.

The configuration’s content is a list of statement context matchers with formats.

TAG:

a report tag. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • error: show as error report if it matches the associated conditions;

  • caution: show as a caution report if it matches the associated conditions;

  • information: show as an information report if it matches the associated conditionsbugs will be reported as information;

  • violation: show as violation report if it matches the associated conditions;

STMT_CONTEXT_SELECTOR:

an expression defining the matching node with its context, where node refers to a statement or expression and context refers to a its chain of ancestors in the AST. Accepted forms are:

  • OR_MATCHER: the node and context matches OR_MATCHER

OR_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the node and context matches AND_MATCHER

  • -AND_MATCHER: the node and context does not match AND_MATCHER

  • [+]AND_MATCHER||SPEC_CTXT_MATCHER: either the node and context matches AND_MATCHER or it matches SPEC_CTXT_MATCHER

  • -AND_MATCHER||SPEC_CTXT_MATCHER: the node and context does not match AND_MATCHER but does match SPEC_CTXT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the the node and context matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the node and context matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (SPEC_CTXT_MATCHER): the node and context matches SPEC_CTXT_MATCHER

  • !BASIC_MATCHER: node and context does not match BASIC_MATCHER

  • any(): matches any node and context

  • none(): matches no node and context

  • context(CTXT_MATCHER): context matches CTXT_MATCHER (see the -context_selector global configuration)

  • SPEC_MATCHER: node matches an AST node selector depending on the node selector specification

SPEC_MATCHER

accepted forms are:

  • STMT_MATCHER: node is a statement or expression that matches STMT_MATCHER (see the -stmt_selector global configuration)

Id:

identifier saved by node matcher or the empty string.

Loc_Kind:

if non-empty, the node is shown using Loc_Kind otherwise a default is used. Accepted forms are:

  • any: an appropriate part of the node’s range

  • range: the complete node range

  • begin: the first part of the node

  • name: the name of the node if it exists, otherwise the range

  • operator: the node operator if it exists, otherwise the range

FMT:

format (see the -fmt global configuration content, template stmtslct__default_fmt).

Default:

-config=B.STMTFIND,stmt_select={}
Option extra_statements
extra_statements
-config=B.STMTFIND,extra_statements={STMT_CONTEXT_SELECTOR},...

Specify which statements or expressions, in addition to the non-compliant ones, must be reported for information purposes.

STMT_CONTEXT_SELECTOR:

an expression defining the matching node with its context, where node refers to a statement or expression and context refers to a its chain of ancestors in the AST. Accepted forms are:

  • OR_MATCHER: the node and context matches OR_MATCHER

OR_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the node and context matches AND_MATCHER

  • -AND_MATCHER: the node and context does not match AND_MATCHER

  • [+]AND_MATCHER||SPEC_CTXT_MATCHER: either the node and context matches AND_MATCHER or it matches SPEC_CTXT_MATCHER

  • -AND_MATCHER||SPEC_CTXT_MATCHER: the node and context does not match AND_MATCHER but does match SPEC_CTXT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the the node and context matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the node and context matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (SPEC_CTXT_MATCHER): the node and context matches SPEC_CTXT_MATCHER

  • !BASIC_MATCHER: node and context does not match BASIC_MATCHER

  • any(): matches any node and context

  • none(): matches no node and context

  • context(CTXT_MATCHER): context matches CTXT_MATCHER (see the -context_selector global configuration)

  • SPEC_MATCHER: node matches an AST node selector depending on the node selector specification

SPEC_MATCHER

accepted forms are:

  • STMT_MATCHER: node is a statement or expression that matches STMT_MATCHER (see the -stmt_selector global configuration)

Default:

-config=B.STMTFIND,extra_statements={}
Option statements
statements
-config=B.STMTFIND,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Option contexts
contexts
-config=B.STMTFIND,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Tool B.TEXTFIND

Summary

Show the source text matching the specified regular expressions.

Description

The source text matching the specified matcher will be shown

Configuration

See generic service options.

Option text_matcher
text_matcher
-config=B.TEXTFIND,text_matcher={ID, REGEX, ACTIONS},...

Associate a text matcher identifier to a regular expression with the reporting actions for each matched text.

The configuration’s content is a collection of named text matchers, a regular expression and reporting actions.

ID:

a text matcher identifier.

REGEX:

a regular expression; captured groups can be referred in the actions using the groups’ indices.

ACTIONS:

a sequence of actions to be applied to the matched texts. Accepted forms are:

  • MATCHER_ACTION[;MATCHER_ACTION]*: perform the sequence of actions MATCHER_ACTION;... to the matched texts

MATCHER_ACTION

accepted forms are:

  • if(COND_MATCHER,ACTION1[,ACTION2]): if the condition specified by COND_MATCHER holds, then do action ACTION1 else do action ACTION2

  • shift(ID): change the text matcher to ID

  • REPORT_KIND(AREA[,AREA]*): create a report of kind REPORT_KIND with the specified areas

  • ID(REGEX_GROUP): secondary text matcher ID to be applied to the text selected by the captured group REGEX_GROUP

COND_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the condition matches AND_MATCHER

  • -AND_MATCHER: the condition does not match AND_MATCHER

  • [+]AND_MATCHER||COND_MATCHER: either the conditions matches AND_MATCHER or it matches COND_MATCHER

  • -AND_MATCHER||COND_MATCHER: the type does not match AND_MATCHER but does match COND_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the condition matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the condition matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (COND_MATCHER): the condition matches COND_MATCHER

  • !BASIC_MATCHER: the condition does not match BASIC_MATCHER

  • [REGEX_GROUP]REGEX: the condition holds if the text selected by captured group REGEX_GROUP is matched by REGEX

AREA

accepted forms are:

  • AREA_KIND(REGEX_GROUP,FMT): report area of kind AREA_KIND located at the text selected by the captured group REGEX_GROUP with message formatted by FMT (see the -fmt global configuration content, template textfind__default_fmt) with fields:

group0

the whole matched expression;

groupN

the N-th matched group of the regular expression, where N must be less than or equal to 10.

AREA_KIND

accepted forms are:

  • culprit: culprit area

  • evidence: evidence area

  • context: context area

REPORT_KIND

accepted forms are:

  • violation: violation report

  • caution: caution report

  • information: information report

REGEX_GROUP

accepted forms are:

  • NUM: matched group number

REGEX

accepted forms are:

Default:

-config=B.TEXTFIND,text_matcher={eol_whitespace, "[ \\t]+(?=[\\r\\n\\f])", "violation(culprit(0,eol_whitespace_fmt))"}, {non_ascii, "[^\\f\\n\\r\\t -~]", "violation(culprit(0,non_ascii_fmt))"}
Option match
match
-config=B.TEXTFIND,match=ID,...

List of matchers to be applied to source files.

The configuration’s content is a list of text matchers to apply.

ID:

a text matcher identifier (see the text_matcher service configuration.

Tool B.TGEN

Summary

Automatic unit-test generator.

Configuration

See generic service options.

Coverage Criteria

Parameters in this section allow the specification of the coverage criteria to be used for testcase generation. Code coverage criteria specify which program entities, such as statements, branches and decisions, should be exercised. Operator coverage criteria specify cases (usually associated to some anomalous behavior) associated to specific semantic operators; for instance, the generation of testcases resulting into an integer divide by zero can be requested.

Option code_coverage
code_coverage
-config=B.TGEN,code_coverage=COVER

Specify the code coverage criterion for testcase generation.

COVER:

choose the code coverage criterion. Accepted values are:

  • none: no code coverage;

  • statement: statement coverage;

  • branch: branch coverage;

Default:

-config=B.TGEN,code_coverage=none
Option operator_coverage
operator_coverage
-config=B.TGEN,operator_coverage={TAG, OP_SET},...

Specifies the operator coverage criterion for testcase generation.

The configuration’s content is a short-circuit sequence with operator special case set names.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

OP_SET:

a FIXME.

Default:

-config=B.TGEN,operator_coverage={}
Option operator_special
operator_special
-config=B.TGEN,operator_special={NAMED, {{{OP_SET,...}, CASE, DESC},...}},...

Specifies named operator special case sets to be used in the definition of the operator coverage criterion.

The configuration’s content is a FIXME.

NAMED:

a FIXME.

{OP_SET,…}:

a set of operators. Accepted members are:

  • add_floating: floating-point add;

  • add_signed: signed integer add;

  • add_unsigned: unsigned integer add;

  • and_signed: signed bitwise and;

  • div_floating: floating-point div;

  • div_signed: signed integer div;

  • div_unsigned: unsigned integer div;

  • floating_cast: a FIXME;

  • unsafe_floating_cast: a FIXME;

  • floating_to_signed: a FIXME;

  • floating_to_unsigned: a FIXME;

  • signed_to_floating: a FIXME;

  • unsigned_to_floating: a FIXME;

  • minus_signed: signed integer unary minus;

  • minus_unsigned: unsigned integer unary minus;

  • mul_floating: floating-point mul;

  • mul_signed: signed integer mul;

  • mul_unsigned: unsigned integer mul;

  • not_signed: a FIXME;

  • or_signed: a FIXME;

  • rem_signed: a FIXME;

  • rem_unsigned: a FIXME;

  • shl_signed: signed shift left;

  • shl_unsigned: unsigned shift left;

  • shr_signed: signed shift right;

  • signed_to_larger_unsigned: a FIXME;

  • signed_to_same_unsigned: a FIXME;

  • signed_to_shift_rhs: a FIXME;

  • signed_to_smaller_signed: a FIXME;

  • signed_to_smaller_unsigned: a FIXME;

  • sub_floating: a FIXME;

  • sub_signed: a FIXME;

  • sub_unsigned: a FIXME;

  • to_bitfield_signed: a FIXME;

  • to_bitfield_unsigned: a FIXME;

  • unsigned_to_same_signed: a FIXME;

  • unsigned_to_shift_rhs: a FIXME;

  • unsigned_to_smaller_signed: a FIXME;

  • unsigned_to_smaller_unsigned: a FIXME;

  • xor_signed: signed bitwise xor;

  • libm_floating: libm floating-point functions;

CASE:

a case in the definition of the semantics of an operator. Accepted values are:

  • normal: a FIXME;

  • bitwise_on_neg: a FIXME;

  • by_zero: a FIXME;

  • inexact: a FIXME;

  • min_by_minus_one: a FIXME;

  • neq_floored_div: a FIXME;

  • neg_lhs: a FIXME;

  • neg_overflow: a FIXME;

  • pos_overflow: a FIXME;

  • finite_to_minf: a FIXME;

  • finite_to_pinf: a FIXME;

  • num_to_nan: a FIXME;

  • bad_gamma_argument: a FIXME;

  • illcond_trig_argument: a FIXME;

DESC:

a FIXME.

Option prove
prove
-config=B.TGEN,prove=CONDS

Specifies whether proof of the #ECLAIR_prove conditions should be attempted (by attempting coverage of their negations).

CONDS:

a FIXME. Accepted values are:

  • false: a FIXME;

  • true: a FIXME;

Default:

-config=B.TGEN,prove=false
Unfolding and Unrolling

Parameters in this section provide ways to control the unfolding of function calls and unrolling of program loops. Note: These parameters reflect some limitations in the current implementation of the tool and should be considered as experimental.

Option loop_iterations
loop_iterations
-config=B.TGEN,loop_iterations=LOOP_IT

Maximum number of loop iterations to be followed.

LOOP_IT:

a FIXME. It must be an integer greater than or equal to 1.

Default:

-config=B.TGEN,loop_iterations=1
Program Semantics

Parameters in this section allow a very fine-grain control of the semantics of the program. The semantics of each semantic operator can be selected from a number of alternatives; for instance, signed integer division can be truncated (as mandated by C99) or floored (as allowed by C90). The semantics of accesses to undefined variables can also be selected as well as all the aspects involved in the use of floating-point quantities.

Option operator_semantics
operator_semantics
-config=B.TGEN,operator_semantics={{OP_SET,...}, CASE, BEHAVIOR},...

FIXME.

The configuration’s content is a FIXME.

{OP_SET,…}:

a set of operators. Accepted members are:

  • add_floating: floating-point add;

  • add_signed: signed integer add;

  • add_unsigned: unsigned integer add;

  • and_signed: signed bitwise and;

  • div_floating: floating-point div;

  • div_signed: signed integer div;

  • div_unsigned: unsigned integer div;

  • floating_cast: a FIXME;

  • unsafe_floating_cast: a FIXME;

  • floating_to_signed: a FIXME;

  • floating_to_unsigned: a FIXME;

  • signed_to_floating: a FIXME;

  • unsigned_to_floating: a FIXME;

  • minus_signed: signed integer unary minus;

  • minus_unsigned: unsigned integer unary minus;

  • mul_floating: floating-point mul;

  • mul_signed: signed integer mul;

  • mul_unsigned: unsigned integer mul;

  • not_signed: a FIXME;

  • or_signed: a FIXME;

  • rem_signed: a FIXME;

  • rem_unsigned: a FIXME;

  • shl_signed: signed shift left;

  • shl_unsigned: unsigned shift left;

  • shr_signed: signed shift right;

  • signed_to_larger_unsigned: a FIXME;

  • signed_to_same_unsigned: a FIXME;

  • signed_to_shift_rhs: a FIXME;

  • signed_to_smaller_signed: a FIXME;

  • signed_to_smaller_unsigned: a FIXME;

  • sub_floating: a FIXME;

  • sub_signed: a FIXME;

  • sub_unsigned: a FIXME;

  • to_bitfield_signed: a FIXME;

  • to_bitfield_unsigned: a FIXME;

  • unsigned_to_same_signed: a FIXME;

  • unsigned_to_shift_rhs: a FIXME;

  • unsigned_to_smaller_signed: a FIXME;

  • unsigned_to_smaller_unsigned: a FIXME;

  • xor_signed: signed bitwise xor;

  • libm_floating: libm floating-point functions;

CASE:

a case in the definition of the semantics of an operator. Accepted values are:

  • normal: a FIXME;

  • bitwise_on_neg: a FIXME;

  • by_zero: a FIXME;

  • inexact: a FIXME;

  • min_by_minus_one: a FIXME;

  • neq_floored_div: a FIXME;

  • neg_lhs: a FIXME;

  • neg_overflow: a FIXME;

  • pos_overflow: a FIXME;

  • finite_to_minf: a FIXME;

  • finite_to_pinf: a FIXME;

  • num_to_nan: a FIXME;

  • bad_gamma_argument: a FIXME;

  • illcond_trig_argument: a FIXME;

BEHAVIOR:

a behavior in the definition of the semantics of an operator. Accepted values are:

  • arith: a FIXME;

  • ieee754: a FIXME;

  • logical: a FIXME;

  • floored: a FIXME;

  • round_current: a FIXME;

  • round_down: a FIXME;

  • round_near: a FIXME;

  • round_up: a FIXME;

  • round_zero: a FIXME;

  • trimmed: a FIXME;

  • unspecified: a FIXME;

  • wrapping: a FIXME;

Default:

-config=B.TGEN,operator_semantics={}
Option uninitialized_behavior
uninitialized_behavior
-config=B.TGEN,uninitialized_behavior=VSEM

Specifies the semantics to be applied to uninitialized variables.

VSEM:

a FIXME. Accepted values are:

  • trimmed: a FIXME;

  • unspecified: a FIXME;

Default:

-config=B.TGEN,uninitialized_behavior=trimmed
Option default_rounding
default_rounding
-config=B.TGEN,default_rounding=RMODE

Specifies the default rounding mode for floating-point operations.

RMODE:

a FIXME. Accepted values are:

  • near: a FIXME;

  • up: a FIXME;

  • down: a FIXME;

  • zero: a FIXME;

Default:

-config=B.TGEN,default_rounding=near
Option nan_in_floats
nan_in_floats
-config=B.TGEN,nan_in_floats=NAN

Specifies whether NaNs are allowed in floating-point quantities.

NAN:

a FIXME. Accepted values are:

  • false: a FIXME;

  • true: a FIXME;

Default:

-config=B.TGEN,nan_in_floats=true
Option minf_in_floats
minf_in_floats
-config=B.TGEN,minf_in_floats=NINF

Specifies whether -inf is allowed in floating-point quantities.

NINF:

a FIXME. Accepted values are:

  • false: a FIXME;

  • true: a FIXME;

Default:

-config=B.TGEN,minf_in_floats=true
Option pinf_in_floats
pinf_in_floats
-config=B.TGEN,pinf_in_floats=PINF

Specifies whether +inf is allowed in floating-point quantities.

PINF:

a FIXME. Accepted values are:

  • false: a FIXME;

  • true: a FIXME;

Default:

-config=B.TGEN,pinf_in_floats=true
Option sub_in_floats
sub_in_floats
-config=B.TGEN,sub_in_floats=PINF

Specifies whether subnormals are allowed in floating-point quantities.

PINF:

a FIXME. Accepted values are:

  • false: a FIXME;

  • true: a FIXME;

Default:

-config=B.TGEN,sub_in_floats=true
Limits to Constraint Resolution

Parameters in this section allow controlling the constraint resolution process in order to limit the amount of resources it is allowed to consume.

Option labeling_limit
labeling_limit
-config=B.TGEN,labeling_limit=LAB_LIMIT

An integer encoding a limit to be applied to the labeling phase of constraint resolution: the higher the value the higher the running time, the lower the chances of getting a “don’t know”.

LAB_LIMIT:

a FIXME. It must be an integer greater than or equal to 1.

Default:

-config=B.TGEN,labeling_limit=100
Option propagation_limit
propagation_limit
-config=B.TGEN,propagation_limit=PROP_LIMIT

An integer encoding a limit to be applied to the propagation phase of constraint resolution: the higher the value the higher the running time, the lower the chances of getting a “don’t know”.

PROP_LIMIT:

a FIXME. It must be an integer greater than or equal to 1.

Default:

-config=B.TGEN,propagation_limit=100
Option dlr_limit
dlr_limit
-config=B.TGEN,dlr_limit=DLR_LIMIT

An integer encoding a limit to be applied to the dynamic linear relaxation phase of constraint resolution: the higher the value the higher the running time, the lower the chances of getting a “don’t know”.

DLR_LIMIT:

a FIXME. It must be an integer greater than or equal to 1.

Default:

-config=B.TGEN,dlr_limit=1000000000
Debugging and Self-Testing

Parameters in this section are related to debugging and self-testing of the testcase generator. They are only relevant to developers and to those who want to assess the capabilities of the tool.

Option trace
trace
-config=B.TGEN,trace=TBEHAVIOR

Specifies the tracing behavior of the servant.

TBEHAVIOR:

a FIXME. Accepted values are:

  • none: a FIXME;

  • novalues: a FIXME;

  • values: a FIXME;

Default:

-config=B.TGEN,trace=values
Option test_program_file
test_program_file
-config=B.TGEN,test_program_file=FNAME

An output file where the self-test program is written.

FNAME:

a FIXME.

Default:

-config=B.TGEN,test_program_file=""

Tool B.TOOLCHAIN

Summary

ECLAIR shall be able to retrieve toolchain information from the toolchain itself.

Description

Reports any failure to retrieve toolchain information from the toolchain itself. If this cannot be achieved (e.g., because the toolchain is missing or is not working with the given command-line options), ECLAIR skips the corresponding analysis, which may result into incorrect and/or incomplete analysis results

Configuration

See generic service options.

Tool B.UMACROS

Summary

Output macro expansions done at unit level.

Configuration

See generic service options.

Option macros
macros
-config=B.UMACROS,macros={TAGS, MACRO_MATCHER},...

Specifies the report tags for macros.

The configuration’s content is a list of clauses specifying the macros and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Option output_csv
output_csv
-config=B.UMACROS,output_csv=FILE

The CSV output file.

FILE:

output CSV file.

Option output_json
output_json
-config=B.UMACROS,output_json=FILE

The JSON output file.

FILE:

output JSON file.

Option output_txt
output_txt
-config=B.UMACROS,output_txt=FILE

The text output file.

FILE:

output text file.

Option output_xml
output_xml
-config=B.UMACROS,output_xml=FILE

The XML output file.

FILE:

output XML file.

Option output_yaml
output_yaml
-config=B.UMACROS,output_yaml=FILE

The YAML output file.

FILE:

output YAML file.

Tool B.UNREACH

Summary

Unreachable functions in a program, given a set of entry points, are shown.

Description

Checker for definitely unreachable functions given a set of entry points

Configuration

See generic service options.

Option declarations
declarations
-config=B.UNREACH,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option ignored_edges
ignored_edges
-config=B.UNREACH,ignored_edges=EDGE_MATCHER

Specifies which call edges should be ignored to determine the reachability of entities.

EDGE_MATCHER:

matcher that defines the call edges that are ignored to delimit the reachability perimeter. Accepted forms are:

  • [+]AND_MATCHER: the edge matches AND_MATCHER

  • -AND_MATCHER: the edge does not match AND_MATCHER

  • [+]AND_MATCHER||EDGE_MATCHER: either the node matches AND_MATCHER or it matches EDGE_MATCHER

  • -AND_MATCHER||EDGE_MATCHER: the node does not match AND_MATCHER but does match EDGE_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the node matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the node matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (EDGE_MATCHER): the node matches EDGE_MATCHER

  • !BASIC_MATCHER: the node does not match BASIC_MATCHER

  • from(ENTITY_MATCHER): a -entity_selector identifier or a matcher expression used to select the caller entity in the call edge

  • from_top: the node is reachable from a program entrypoint

  • from_type(^REGEX$): the caller is type that matches ^REGEX$

  • to(ENTITY_MATCHER): a -entity_selector identifier or a matcher expression used to select the callee entity in the call edge

  • to_type(^REGEX$): the callee is type that matches ^REGEX$

  • node(loc(LOC_MATCHER)): an edge whose callee location matches the -loc_selector

  • when(EDGE_WHEN[||EDGE_WHEN]*): an edge that is traversed on a control flow path specified by EDGE_WHEN

  • etime(EDGE_ETIME[||EDGE_ETIME]*): an edge that is executed at a time specified by EDGE_ETIME

EDGE_WHEN

accepted forms are:

  • normal: normal control flow execution

  • lifetime_end: control flow executed when the lifetime of the object ends

  • exception: control flow executed on exceptional paths

EDGE_ETIME

accepted forms are:

  • run: edge traversed at runtime

  • compile: edge traversed at compile time

The CERT C Secure Coding Standard rules, second edition

For the CERT-C-2014 coding standard [22], each of the supported guidelines, the identifier for the corresponding ECLAIR service is obtained by adding the prefix CC2, thereby obtaining, for example: CC2.ARR36, CC2.DCL30, CC2.EXP39, …

Note that the page numbers included in the references to [22] in the ECLAIR service summaries are for the PDF version of [22] ☞.

Rule CC2.ARR36

Summary

Do not subtract or compare two pointers that do not refer to the same array. (See page 217 of CERT-C-2014 [22] ☞.)

Description

If one pointer is subtracted from or compared with another pointer, then both the pointers must point to elements in the same array.

Configuration

See generic service options.

Rule CC2.ARR37

Summary

Do not add or subtract an integer to a pointer to a non-array object. (See page 229 of CERT-C-2014 [22] ☞.)

Description

If an integer is added to or subtracted from a pointer, then that pointer must point to an array or an array element.

Configuration

See generic service options.

Rule CC2.DCL30

Summary

Declare objects with appropriate storage durations. (See page 57 of CERT-C-2014 [22] ☞.)

Description

An object with automatic storage must not have its address:

  • assigned to another automatic object of larger scope; or

  • assigned to a static object; or

  • returned by a function.

Note that only objects with automatic storage duration are checked; that is, there is no checking of objects with thread or allocated storage duration.

Configuration

See generic service options.

Rule CC2.DCL31

Summary

Declare identifiers before using them. (See page 61 of CERT-C-2014 [22] ☞.)

Description

Checks that:

  • a function declaration or definition has a function prototype;

  • a function is declared with a prototype declaration or definition before any reference to it;

  • the type of any parameter or object declaration is explicitly stated;

  • the type of the return value of any function declaration or definition must be explicitly stated;

  • the type of any typedef declaration is explicitly stated.

Configuration

See generic service options.

Option declarations
declarations
-config=CC2.DCL31,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option statements
statements
-config=CC2.DCL31,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Option contexts
contexts
-config=CC2.DCL31,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Rule CC2.DCL36

Summary

Do not declare an identifier with conflicting linkage classifications. (See page 65 of CERT-C-2014 [22] ☞.)

Description

Any variable or function declaration or definition with internal linkage must include the storage class specifier static.

Configuration

See generic service options.

Option declarations
declarations
-config=CC2.DCL36,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CC2.DCL37

Summary

Do not declare or define a reserved identifier. (See page 68 of CERT-C-2014 [22] ☞.)

Description

No #define or #undef directive may be used on a reserved identifier, macro or function in the standard library.

The reserved identifiers are defined to include all the following:

  • identifiers that are reserved by the C11 standard [35];

  • identifiers that are reserved by the standard used by the translation unit;

  • identifiers reserved for future library directions.

Configuration

See generic service options.

Option declarations
declarations
-config=CC2.DCL37,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option reserved_standard
reserved_standard
-config=CC2.DCL37,reserved_standard=DOM,...

Specify the reserve domains.

The configuration’s content is a set of reserved name domains.

DOM:

domain expression. Accepted forms are:

  • min(STD): the oldest standard between the STD and the unit standard if the languages are the same, otherwise, it is STD

  • max(STD): the newest standard between the STD and the unit standard if the languages are the same, otherwise, it is STD

  • std(): the unit standard

  • STD: the named standard

STD

accepted forms are:

  • c90: the C90 standard [28]

  • c95: the C95 standard [29]

  • c99: the C99 standard [31]

  • c11: the C11 standard [35]

  • c18: the C18 standard [39]

  • c++98: the C++98 standard [30]

  • c++03: the C++03 standard [32]

  • c++11: the C++11 standard [34]

  • c++14: the C++14 standard [36]

  • c++17: the C++17 standard [38]

  • c++20: the C++20 standard [40]

Default:

-config=CC2.DCL37,reserved_standard="std()"
Option macros
macros
-config=CC2.DCL37,macros={TAGS, MACRO_MATCHER},...

Specifies the report tags for macros.

The configuration’s content is a list of clauses specifying the macros and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Rule CC2.DCL38

Summary

Use the correct syntax when declaring flexible array members. (See page 74 of CERT-C-2014 [22] ☞.)

Description

A struct whose last field has an array type with 0 or 1 elements is reported.

Configuration

See generic service options.

Option declarations
declarations
-config=CC2.DCL38,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CC2.DCL39

Summary

Avoid information leakage in structure padding. (See page 77 of CERT-C-2014 [22] ☞.)

Description

Local storage variable must not have a type that is a padding struct, union or class.

Configuration

See generic service options.

Rule CC2.DCL40

Summary

Do not create incompatible declarations of the same function or object. (See page 82 of CERT-C-2014 [22] ☞.)

Description

Checks that:

  • if a variable is declared more than once, the types are compatible;

  • if a function has more than one prototype declaration or definition, the corresponding parameter types or return types are compatible.

External identifiers (including macro names) differ in their first 31 characters both before and after any macro expansion.

Notes:

  • selected entities can be ignored using the ignored_decls service configuration;

  • since this service checks for name clashes between multiple entities, the configuration parameters that exclude selected entities or portions of code should be used with care since a name clash between an excluded entity and another will not be reported.

Configuration

See generic service options.

Option identifier_length
identifier_length
-config=CC2.DCL40,identifier_length={SEL, CASE, LEN},...

Specify significant length and case significance for identifiers for selected entities.

The configuration’s content is a list of entity matchers with significant length and case significance.

SEL:

a -entity_selector identifier or a matcher expression used to select the entities.

CASE:

indicate if case is significant. Accepted values are:

  • case_insensitive: case is not significant;

  • case_sensitive: case is significant;

LEN:

length of significant leading part of identifier; 0 indicates that there is no limit. It must be an integer greater than or equal to 0.

Default:

-config=CC2.DCL40,identifier_length={external_identifiers, case_sensitive, 31}
Option declarations
declarations
-config=CC2.DCL40,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option ignored_decls
ignored_decls
-config=CC2.DCL40,ignored_decls=DECL_MATCHER,...

Specify the declarations that should be ignored.

The configuration’s content is a list of declaration matchers.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Default:

-config=CC2.DCL40,ignored_decls={}

Rule CC2.DCL41

Summary

Do not declare variables inside a switch statement before the first case label. (See page 88 of CERT-C-2014 [22] ☞.)

Description

A switch statement body must begin with a case or default label.

Configuration

See generic service options.

Option terminals
terminals
-config=CC2.DCL41,terminals={TAGS, STMT_MATCHER},...

Specifies the report tags for terminal statements.

The configuration’s content is a list of clauses specifying the terminals and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select terminal statements.

Option switch_clauses
switch_clauses
-config=CC2.DCL41,switch_clauses={TAGS, SWITCH_CLAUSES},...

Specify the report tags for switch statements, selected by the number of clauses and labels.

The configuration’s content is a set of pairs that associates a report tag to a constraint based on the number of the clauses and labels in a switch statement.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

SWITCH_CLAUSES:

a conjunction of switch statement constraints. Accepted forms are:

  • CONSTRAINT[&&CONSTRAINT]*: the switch statement clause matches every CONSTRAINT

CONSTRAINT

accepted forms are:

  • switch(MIN_MAX): the number of switch clauses must be in the range MIN_MAX

  • case(MIN_MAX): the number of case labels must be in the range MIN_MAX

  • default(MIN_MAX): the number of default labels must be in the range MIN_MAX

MIN_MAX

accepted forms are:

  • NUM_MINRANGE_SEPNUM_MAX: range is from NUM_MIN to NUM_MAX

  • RANGE_SEPNUM: range is all values equal or less than NUM

  • NUMRANGE_SEP: range is all values equal or more than NUM

  • NUM: range is the single value NUM

RANGE_SEP

accepted forms are:

  • ..: range separator

  • ...: range separator

Option ignored_comments
ignored_comments
-config=CC2.DCL41,ignored_comments=COMMENT_MATCHER,...

Specify the comments that should be ignored.

The configuration’s content is a list of comment matchers.

COMMENT_MATCHER:

a -comment_selector identifier or a matcher expression used to select the comments.

Rule CC2.ENV33

Summary

Do not call system(). (See page 364 of CERT-C-2014 [22] ☞.)

Description

There must be no use of the standard library function system provided by stdlib.h.

Configuration

See generic service options.

Option declarations
declarations
-config=CC2.ENV33,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CC2.EXP30

Summary

Do not depend on order of evaluation for side-effects. (See page 93 of CERT-C-2014 [22] ☞.)

Description

An expression is non-compliant if it has two unordered actions where:

  • both write to the same area of memory;

  • one action reads from and the other action writes to the same area of memory.

Notes:

  • It is assumed that unless a function is declared as const, pure or noeffect, any call to it may result in a change to the value of one of its arguments or to the value of a global variable.

  • The -call_properties global configuration can be used to specify the call property const, pure or noeffect.

For example, with the configuration line:

-call_properties+={"decl(name(pure_fun))", {pure}}

the function named pure_fun has the property pure and is assumed to have no side effects and will not change the value of one of its arguments or any global variable.

Imprecision

Cautions are reported when it has not been determined whether two accessed objects overlap.

Configuration

See generic service options.

Rule CC2.EXP32

Summary

Do not access a volatile object through a non-volatile reference. (See page 99 of CERT-C-2014 [22] ☞.)

Description

A volatile object must not be accessed through a non-volatile object.

Configuration

See generic service options.

Option casts
casts
-config=CC2.EXP32,casts={TAGS, MATCHER},...

Specifies the report tags for casts.

The configuration’s content is a list of clauses specifying the casts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MATCHER:

comma-separated sequence of cast conditions. Accepted forms are:

  • [+]AND_MATCHER: the node matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||CAST_MATCHER: either the cast matches AND_MATCHER or it matches CAST_MATCHER

  • -AND_MATCHER||CAST_MATCHER: the cast does not match AND_MATCHER but does match CAST_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the cast matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the cast matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CAST_MATCHER): the cast matches CAST_MATCHER

  • !BASIC_MATCHER: the cast does not match BASIC_MATCHER

  • any(): any cast matches

  • none(): no cast matches

  • class(CAST_CLASS): the cast class is CAST_CLASS

  • context(CONTEXT_MATCHER): the cast is in a context matching CONTEXT_MATCHER (see the -context_selector global configuration)

  • from(FROM_MATCHER): the cast whose source expression matches FROM_MATCHER

  • syntactic(FROM_MATCHER)): the cast whose syntactic source expression (i.e., after removing all non-syntactic wrappers from the source) matches FROM_MATCHER

  • kind(CAST_KIND[||CAST_KIND]*): the cast kind is one of the CAST_KIND

  • language(LANGUAGE): the language is LANGUAGE

  • to(type(TYPE_MATCHER)): the cast whose destination type is matching TYPE_MATCHER (see the -type_selector global configuration)

  • relation(RELATION[||RELATION]*): the cast satisfies one of RELATION

CAST_KIND

accepted forms are:

  • no_op: no_op

  • address_space_conversion: address_space_conversion

  • array_to_pointer_decay: array_to_pointer_decay

  • atomic_to_non_atomic: atomic_to_non_atomic

  • base_to_derived: base_to_derived

  • base_to_derived_member_pointer: base_to_derived_member_pointer

  • bitcast: bitcast

  • boolean_to_signed_integral: boolean_to_signed_integral

  • builtin_function_to_pointer_decay: builtin_function_to_pointer_decay

  • constructor_conversion: constructor_conversion

  • dependent: dependent

  • derived_to_base: derived_to_base

  • derived_to_base_member_pointer: derived_to_base_member_pointer

  • dynamic: dynamic

  • floating_cast: floating_cast

  • floating_complex_cast: floating_complex_cast

  • floating_complex_to_boolean: floating_complex_to_boolean

  • floating_complex_to_integral_complex: floating_complex_to_integral_complex

  • floating_complex_to_real: floating_complex_to_real

  • floating_real_to_complex: floating_real_to_complex

  • floating_to_boolean: floating_to_boolean

  • floating_to_integral: floating_to_integral

  • function_to_pointer_decay: function_to_pointer_decay

  • integral_cast: integral_cast

  • integral_complex_cast: integral_complex_cast

  • integral_complex_to_boolean: integral_complex_to_boolean

  • integral_complex_to_floating_complex: integral_complex_to_floating_complex

  • integral_complex_to_real: integral_complex_to_real

  • integral_real_to_complex: integral_real_to_complex

  • integral_to_boolean: integral_to_boolean

  • integral_to_floating: integral_to_floating

  • integral_to_pointer: integral_to_pointer

  • lvalue_bitcast: lvalue_bitcast

  • lvalue_to_rvalue: lvalue_to_rvalue

  • member_pointer_to_boolean: member_pointer_to_boolean

  • non_atomic_to_atomic: non_atomic_to_atomic

  • null_to_member_pointer: null_to_member_pointer

  • null_to_pointer: null_to_pointer

  • pointer_to_boolean: pointer_to_boolean

  • pointer_to_integral: pointer_to_integral

  • reinterpret_member_pointer: reinterpret_member_pointer

  • to_union: to_union

  • to_void: to_void

  • unchecked_derived_to_base: unchecked_derived_to_base

  • user_defined_conversion: user_defined_conversion

  • vector_splat: vector_splat

CAST_CLASS

accepted forms are:

  • implicit: the cast is implicit

  • explicit: the cast is explicit

  • c_style: the cast is c_style

  • functional: the cast is functional

  • const: the cast is a const named cast

  • dynamic: the cast is a dynamic named cast

  • reinterpret: the cast is a reinterpret named cast

  • static: the cast is a static named cast

RELATION

accepted forms are:

  • : bigger_sizea cast to a bigger type

  • : bigger_size_pointeea cast from a pointer to another pointer with a bigger pointee

  • cast_away_const: a cast from a pointer to a const type to a pointer without the qualifier

  • cast_away_volatile: a cast from a pointer to a volatile type to a pointer without the qualifier

  • compatible_deep_unqualified: a cast from a type to a type that has the same pointee depth and where the innermost types without qualifiers are compatible

  • definitely_changes_value: a cast that definitely does change the source expression’s value

  • definitely_in_range: a cast whose cast value is definitely in the range of its type

  • definitely_out_range: a cast whose cast value is definitely out of range of its type

  • definitely_preserves_value: a cast that definitely does not change the source expression’s value

  • derived_to_virtual_base: a cast from a pointer to a class to a pointer to a virtual base class

  • enum_constant: a cast whose source expression is an enumeration constant and whose destination type is the same as the enumerator type

  • forget_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const or is void or Boolean

  • forget_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile or is void or Boolean

  • incompatible_unqualified_pointee: a cast from a pointer to a pointer with an incompatible unqualified pointee type

  • more_aligned_pointee: a cast from a pointer to a pointer with a more aligned pointee type

  • polymorphic_base_to_derived: a cast from a pointer to a base class with polymorphic type to a pointer to a derived class

  • qualification: a cast from a pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_from_void_pointee: a cast from a void pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_to_void_pointee: a cast from a pointer to void pointer where the destination pointee has all the qualifiers in the source pointee

  • same_type: a cast that does not change the type

  • same_unqualified_pointee: a cast from a pointer to a pointer with the same pointee type, ignoring any qualifications

  • signed_to_unsigned: a cast from a signed integral type to an unsigned integral type

  • unqualify_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const

  • unqualify_pointee: a cast from a pointer with a pointee type qualifier to another pointer whose pointee type does not have that qualifier

  • unqualify_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile

  • unqualify_atomic_pointee: a cast from a pointer with an _Atomic pointee type to another pointer whose pointee is not _Atomic

  • unsigned_to_signed: a cast from an unsigned integral type to a signed integral type

  • virtual_base_to_derived: a cast from a pointer to a virtual base class to a pointer to a derived class

FROM_MATCHER

accepted forms are:

  • type(TYPE_MATCHER): the type of the source expression matches TYPE_MATCHER (see the -type_selector global configuration)

  • expr(STMT_MATCHER): the source expression matches STMT_MATCHER (see the -stmt_selector global configuration)

LANGUAGE

accepted forms are:

  • c: C

  • cpp: C++

Rule CC2.EXP33

Summary

Do not read uninitialized memory. (See page 101 of CERT-C-2014 [22] ☞.)

Description

All automatic variables must have a value written to them before being read.

Note that this does not necessarily require initialization at the declaration.

Note also that initializing any one member of a union is not considered as (proper) initialization of the other members.

Implementation

Reports if an automatic variable may be used without initialization.

Imprecision

Cautions are reported when the analyzer cannot determine the necessary execution order.

Cautions may be caused by bad style coding such as in the following example:

int f() {
  int a;
  int b = 1;
  if (b) a = 3;
  return a;
}

Since realloc can change the size of an object, any use of the standard library functions that return an uninitialized heap is reported as a caution.

Configuration

See generic service options.

Option member_areas
member_areas
-config=CC2.EXP33,member_areas=MAX

Specify the maximum number of uninitialized members to be shown as evidence when reporting a (possibly) uninitialized struct or a class.

MAX:

maximum number of areas in a report showing uninstantiated class or struct members. It must be an integer greater than or equal to 0.

Option declarations
declarations
-config=CC2.EXP33,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CC2.EXP34

Summary

Do not dereference null pointers. (See page 110 of CERT-C-2014 [22] ☞.)

Description

Null pointers must not be de-referenced.

Configuration

See generic service options.

Rule CC2.EXP35

Summary

Do not modify objects with temporary lifetime. (See page 115 of CERT-C-2014 [22] ☞.)

Description

A dot member expression must be an lvalue.

Configuration

See generic service options.

Option statements
statements
-config=CC2.EXP35,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Option contexts
contexts
-config=CC2.EXP35,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Rule CC2.EXP36

Summary

Do not cast pointers into more strictly aligned pointer types. (See page 118 of CERT-C-2014 [22] ☞.)

Description

A pointer type must not be cast to a more strictly aligned pointer type.

Configuration

See generic service options.

Option casts
casts
-config=CC2.EXP36,casts={TAGS, MATCHER},...

Specifies the report tags for casts.

The configuration’s content is a list of clauses specifying the casts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MATCHER:

comma-separated sequence of cast conditions. Accepted forms are:

  • [+]AND_MATCHER: the node matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||CAST_MATCHER: either the cast matches AND_MATCHER or it matches CAST_MATCHER

  • -AND_MATCHER||CAST_MATCHER: the cast does not match AND_MATCHER but does match CAST_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the cast matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the cast matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CAST_MATCHER): the cast matches CAST_MATCHER

  • !BASIC_MATCHER: the cast does not match BASIC_MATCHER

  • any(): any cast matches

  • none(): no cast matches

  • class(CAST_CLASS): the cast class is CAST_CLASS

  • context(CONTEXT_MATCHER): the cast is in a context matching CONTEXT_MATCHER (see the -context_selector global configuration)

  • from(FROM_MATCHER): the cast whose source expression matches FROM_MATCHER

  • syntactic(FROM_MATCHER)): the cast whose syntactic source expression (i.e., after removing all non-syntactic wrappers from the source) matches FROM_MATCHER

  • kind(CAST_KIND[||CAST_KIND]*): the cast kind is one of the CAST_KIND

  • language(LANGUAGE): the language is LANGUAGE

  • to(type(TYPE_MATCHER)): the cast whose destination type is matching TYPE_MATCHER (see the -type_selector global configuration)

  • relation(RELATION[||RELATION]*): the cast satisfies one of RELATION

CAST_KIND

accepted forms are:

  • no_op: no_op

  • address_space_conversion: address_space_conversion

  • array_to_pointer_decay: array_to_pointer_decay

  • atomic_to_non_atomic: atomic_to_non_atomic

  • base_to_derived: base_to_derived

  • base_to_derived_member_pointer: base_to_derived_member_pointer

  • bitcast: bitcast

  • boolean_to_signed_integral: boolean_to_signed_integral

  • builtin_function_to_pointer_decay: builtin_function_to_pointer_decay

  • constructor_conversion: constructor_conversion

  • dependent: dependent

  • derived_to_base: derived_to_base

  • derived_to_base_member_pointer: derived_to_base_member_pointer

  • dynamic: dynamic

  • floating_cast: floating_cast

  • floating_complex_cast: floating_complex_cast

  • floating_complex_to_boolean: floating_complex_to_boolean

  • floating_complex_to_integral_complex: floating_complex_to_integral_complex

  • floating_complex_to_real: floating_complex_to_real

  • floating_real_to_complex: floating_real_to_complex

  • floating_to_boolean: floating_to_boolean

  • floating_to_integral: floating_to_integral

  • function_to_pointer_decay: function_to_pointer_decay

  • integral_cast: integral_cast

  • integral_complex_cast: integral_complex_cast

  • integral_complex_to_boolean: integral_complex_to_boolean

  • integral_complex_to_floating_complex: integral_complex_to_floating_complex

  • integral_complex_to_real: integral_complex_to_real

  • integral_real_to_complex: integral_real_to_complex

  • integral_to_boolean: integral_to_boolean

  • integral_to_floating: integral_to_floating

  • integral_to_pointer: integral_to_pointer

  • lvalue_bitcast: lvalue_bitcast

  • lvalue_to_rvalue: lvalue_to_rvalue

  • member_pointer_to_boolean: member_pointer_to_boolean

  • non_atomic_to_atomic: non_atomic_to_atomic

  • null_to_member_pointer: null_to_member_pointer

  • null_to_pointer: null_to_pointer

  • pointer_to_boolean: pointer_to_boolean

  • pointer_to_integral: pointer_to_integral

  • reinterpret_member_pointer: reinterpret_member_pointer

  • to_union: to_union

  • to_void: to_void

  • unchecked_derived_to_base: unchecked_derived_to_base

  • user_defined_conversion: user_defined_conversion

  • vector_splat: vector_splat

CAST_CLASS

accepted forms are:

  • implicit: the cast is implicit

  • explicit: the cast is explicit

  • c_style: the cast is c_style

  • functional: the cast is functional

  • const: the cast is a const named cast

  • dynamic: the cast is a dynamic named cast

  • reinterpret: the cast is a reinterpret named cast

  • static: the cast is a static named cast

RELATION

accepted forms are:

  • : bigger_sizea cast to a bigger type

  • : bigger_size_pointeea cast from a pointer to another pointer with a bigger pointee

  • cast_away_const: a cast from a pointer to a const type to a pointer without the qualifier

  • cast_away_volatile: a cast from a pointer to a volatile type to a pointer without the qualifier

  • compatible_deep_unqualified: a cast from a type to a type that has the same pointee depth and where the innermost types without qualifiers are compatible

  • definitely_changes_value: a cast that definitely does change the source expression’s value

  • definitely_in_range: a cast whose cast value is definitely in the range of its type

  • definitely_out_range: a cast whose cast value is definitely out of range of its type

  • definitely_preserves_value: a cast that definitely does not change the source expression’s value

  • derived_to_virtual_base: a cast from a pointer to a class to a pointer to a virtual base class

  • enum_constant: a cast whose source expression is an enumeration constant and whose destination type is the same as the enumerator type

  • forget_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const or is void or Boolean

  • forget_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile or is void or Boolean

  • incompatible_unqualified_pointee: a cast from a pointer to a pointer with an incompatible unqualified pointee type

  • more_aligned_pointee: a cast from a pointer to a pointer with a more aligned pointee type

  • polymorphic_base_to_derived: a cast from a pointer to a base class with polymorphic type to a pointer to a derived class

  • qualification: a cast from a pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_from_void_pointee: a cast from a void pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_to_void_pointee: a cast from a pointer to void pointer where the destination pointee has all the qualifiers in the source pointee

  • same_type: a cast that does not change the type

  • same_unqualified_pointee: a cast from a pointer to a pointer with the same pointee type, ignoring any qualifications

  • signed_to_unsigned: a cast from a signed integral type to an unsigned integral type

  • unqualify_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const

  • unqualify_pointee: a cast from a pointer with a pointee type qualifier to another pointer whose pointee type does not have that qualifier

  • unqualify_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile

  • unqualify_atomic_pointee: a cast from a pointer with an _Atomic pointee type to another pointer whose pointee is not _Atomic

  • unsigned_to_signed: a cast from an unsigned integral type to a signed integral type

  • virtual_base_to_derived: a cast from a pointer to a virtual base class to a pointer to a derived class

FROM_MATCHER

accepted forms are:

  • type(TYPE_MATCHER): the type of the source expression matches TYPE_MATCHER (see the -type_selector global configuration)

  • expr(STMT_MATCHER): the source expression matches STMT_MATCHER (see the -stmt_selector global configuration)

LANGUAGE

accepted forms are:

  • c: C

  • cpp: C++

Rule CC2.EXP37

Summary

Call functions with the correct number and type of arguments. (See page 122 of CERT-C-2014 [22] ☞.)

Description

Checks that:

  • any call to a function has an explicit protoype declaration;

  • the number of arguments passed to the function match the number of parameters;

  • the type of each argument is compatible with the declared type of the parameter;

  • if the parameter type is a pointer, then the pointee type of the argument is compatible with the pointee type of the parameter;

  • calls to type-generic functions in <math.h> that expect real values do not have complex-valued arguments.

Configuration

See generic service options.

Option calls
calls
-config=CC2.EXP37,calls={TAGS, CALL_MATCHER},...

Specifies the report tags for calls.

The configuration’s content is a list of clauses specifying the calls and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CALL_MATCHER:

a -call_selector identifier or a matcher expression used to select the calls.

Option declarations
declarations
-config=CC2.EXP37,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option casts
casts
-config=CC2.EXP37,casts={TAGS, MATCHER},...

Specifies the report tags for casts.

The configuration’s content is a list of clauses specifying the casts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MATCHER:

comma-separated sequence of cast conditions. Accepted forms are:

  • [+]AND_MATCHER: the node matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||CAST_MATCHER: either the cast matches AND_MATCHER or it matches CAST_MATCHER

  • -AND_MATCHER||CAST_MATCHER: the cast does not match AND_MATCHER but does match CAST_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the cast matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the cast matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CAST_MATCHER): the cast matches CAST_MATCHER

  • !BASIC_MATCHER: the cast does not match BASIC_MATCHER

  • any(): any cast matches

  • none(): no cast matches

  • class(CAST_CLASS): the cast class is CAST_CLASS

  • context(CONTEXT_MATCHER): the cast is in a context matching CONTEXT_MATCHER (see the -context_selector global configuration)

  • from(FROM_MATCHER): the cast whose source expression matches FROM_MATCHER

  • syntactic(FROM_MATCHER)): the cast whose syntactic source expression (i.e., after removing all non-syntactic wrappers from the source) matches FROM_MATCHER

  • kind(CAST_KIND[||CAST_KIND]*): the cast kind is one of the CAST_KIND

  • language(LANGUAGE): the language is LANGUAGE

  • to(type(TYPE_MATCHER)): the cast whose destination type is matching TYPE_MATCHER (see the -type_selector global configuration)

  • relation(RELATION[||RELATION]*): the cast satisfies one of RELATION

CAST_KIND

accepted forms are:

  • no_op: no_op

  • address_space_conversion: address_space_conversion

  • array_to_pointer_decay: array_to_pointer_decay

  • atomic_to_non_atomic: atomic_to_non_atomic

  • base_to_derived: base_to_derived

  • base_to_derived_member_pointer: base_to_derived_member_pointer

  • bitcast: bitcast

  • boolean_to_signed_integral: boolean_to_signed_integral

  • builtin_function_to_pointer_decay: builtin_function_to_pointer_decay

  • constructor_conversion: constructor_conversion

  • dependent: dependent

  • derived_to_base: derived_to_base

  • derived_to_base_member_pointer: derived_to_base_member_pointer

  • dynamic: dynamic

  • floating_cast: floating_cast

  • floating_complex_cast: floating_complex_cast

  • floating_complex_to_boolean: floating_complex_to_boolean

  • floating_complex_to_integral_complex: floating_complex_to_integral_complex

  • floating_complex_to_real: floating_complex_to_real

  • floating_real_to_complex: floating_real_to_complex

  • floating_to_boolean: floating_to_boolean

  • floating_to_integral: floating_to_integral

  • function_to_pointer_decay: function_to_pointer_decay

  • integral_cast: integral_cast

  • integral_complex_cast: integral_complex_cast

  • integral_complex_to_boolean: integral_complex_to_boolean

  • integral_complex_to_floating_complex: integral_complex_to_floating_complex

  • integral_complex_to_real: integral_complex_to_real

  • integral_real_to_complex: integral_real_to_complex

  • integral_to_boolean: integral_to_boolean

  • integral_to_floating: integral_to_floating

  • integral_to_pointer: integral_to_pointer

  • lvalue_bitcast: lvalue_bitcast

  • lvalue_to_rvalue: lvalue_to_rvalue

  • member_pointer_to_boolean: member_pointer_to_boolean

  • non_atomic_to_atomic: non_atomic_to_atomic

  • null_to_member_pointer: null_to_member_pointer

  • null_to_pointer: null_to_pointer

  • pointer_to_boolean: pointer_to_boolean

  • pointer_to_integral: pointer_to_integral

  • reinterpret_member_pointer: reinterpret_member_pointer

  • to_union: to_union

  • to_void: to_void

  • unchecked_derived_to_base: unchecked_derived_to_base

  • user_defined_conversion: user_defined_conversion

  • vector_splat: vector_splat

CAST_CLASS

accepted forms are:

  • implicit: the cast is implicit

  • explicit: the cast is explicit

  • c_style: the cast is c_style

  • functional: the cast is functional

  • const: the cast is a const named cast

  • dynamic: the cast is a dynamic named cast

  • reinterpret: the cast is a reinterpret named cast

  • static: the cast is a static named cast

RELATION

accepted forms are:

  • : bigger_sizea cast to a bigger type

  • : bigger_size_pointeea cast from a pointer to another pointer with a bigger pointee

  • cast_away_const: a cast from a pointer to a const type to a pointer without the qualifier

  • cast_away_volatile: a cast from a pointer to a volatile type to a pointer without the qualifier

  • compatible_deep_unqualified: a cast from a type to a type that has the same pointee depth and where the innermost types without qualifiers are compatible

  • definitely_changes_value: a cast that definitely does change the source expression’s value

  • definitely_in_range: a cast whose cast value is definitely in the range of its type

  • definitely_out_range: a cast whose cast value is definitely out of range of its type

  • definitely_preserves_value: a cast that definitely does not change the source expression’s value

  • derived_to_virtual_base: a cast from a pointer to a class to a pointer to a virtual base class

  • enum_constant: a cast whose source expression is an enumeration constant and whose destination type is the same as the enumerator type

  • forget_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const or is void or Boolean

  • forget_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile or is void or Boolean

  • incompatible_unqualified_pointee: a cast from a pointer to a pointer with an incompatible unqualified pointee type

  • more_aligned_pointee: a cast from a pointer to a pointer with a more aligned pointee type

  • polymorphic_base_to_derived: a cast from a pointer to a base class with polymorphic type to a pointer to a derived class

  • qualification: a cast from a pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_from_void_pointee: a cast from a void pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_to_void_pointee: a cast from a pointer to void pointer where the destination pointee has all the qualifiers in the source pointee

  • same_type: a cast that does not change the type

  • same_unqualified_pointee: a cast from a pointer to a pointer with the same pointee type, ignoring any qualifications

  • signed_to_unsigned: a cast from a signed integral type to an unsigned integral type

  • unqualify_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const

  • unqualify_pointee: a cast from a pointer with a pointee type qualifier to another pointer whose pointee type does not have that qualifier

  • unqualify_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile

  • unqualify_atomic_pointee: a cast from a pointer with an _Atomic pointee type to another pointer whose pointee is not _Atomic

  • unsigned_to_signed: a cast from an unsigned integral type to a signed integral type

  • virtual_base_to_derived: a cast from a pointer to a virtual base class to a pointer to a derived class

FROM_MATCHER

accepted forms are:

  • type(TYPE_MATCHER): the type of the source expression matches TYPE_MATCHER (see the -type_selector global configuration)

  • expr(STMT_MATCHER): the source expression matches STMT_MATCHER (see the -stmt_selector global configuration)

LANGUAGE

accepted forms are:

  • c: C

  • cpp: C++

Option contexts
contexts
-config=CC2.EXP37,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Rule CC2.EXP39

Summary

Do not access a variable through a pointer of an incompatible type. (See page 128 of CERT-C-2014 [22] ☞.)

Description

A pointer should not be cast to a different type (excluding qualifiers).

Any such casts, implicit or explicit, will be reported as a caution.

Configuration

See generic service options.

Option casts
casts
-config=CC2.EXP39,casts={TAGS, MATCHER},...

Specifies the report tags for casts.

The configuration’s content is a list of clauses specifying the casts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MATCHER:

comma-separated sequence of cast conditions. Accepted forms are:

  • [+]AND_MATCHER: the node matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||CAST_MATCHER: either the cast matches AND_MATCHER or it matches CAST_MATCHER

  • -AND_MATCHER||CAST_MATCHER: the cast does not match AND_MATCHER but does match CAST_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the cast matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the cast matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CAST_MATCHER): the cast matches CAST_MATCHER

  • !BASIC_MATCHER: the cast does not match BASIC_MATCHER

  • any(): any cast matches

  • none(): no cast matches

  • class(CAST_CLASS): the cast class is CAST_CLASS

  • context(CONTEXT_MATCHER): the cast is in a context matching CONTEXT_MATCHER (see the -context_selector global configuration)

  • from(FROM_MATCHER): the cast whose source expression matches FROM_MATCHER

  • syntactic(FROM_MATCHER)): the cast whose syntactic source expression (i.e., after removing all non-syntactic wrappers from the source) matches FROM_MATCHER

  • kind(CAST_KIND[||CAST_KIND]*): the cast kind is one of the CAST_KIND

  • language(LANGUAGE): the language is LANGUAGE

  • to(type(TYPE_MATCHER)): the cast whose destination type is matching TYPE_MATCHER (see the -type_selector global configuration)

  • relation(RELATION[||RELATION]*): the cast satisfies one of RELATION

CAST_KIND

accepted forms are:

  • no_op: no_op

  • address_space_conversion: address_space_conversion

  • array_to_pointer_decay: array_to_pointer_decay

  • atomic_to_non_atomic: atomic_to_non_atomic

  • base_to_derived: base_to_derived

  • base_to_derived_member_pointer: base_to_derived_member_pointer

  • bitcast: bitcast

  • boolean_to_signed_integral: boolean_to_signed_integral

  • builtin_function_to_pointer_decay: builtin_function_to_pointer_decay

  • constructor_conversion: constructor_conversion

  • dependent: dependent

  • derived_to_base: derived_to_base

  • derived_to_base_member_pointer: derived_to_base_member_pointer

  • dynamic: dynamic

  • floating_cast: floating_cast

  • floating_complex_cast: floating_complex_cast

  • floating_complex_to_boolean: floating_complex_to_boolean

  • floating_complex_to_integral_complex: floating_complex_to_integral_complex

  • floating_complex_to_real: floating_complex_to_real

  • floating_real_to_complex: floating_real_to_complex

  • floating_to_boolean: floating_to_boolean

  • floating_to_integral: floating_to_integral

  • function_to_pointer_decay: function_to_pointer_decay

  • integral_cast: integral_cast

  • integral_complex_cast: integral_complex_cast

  • integral_complex_to_boolean: integral_complex_to_boolean

  • integral_complex_to_floating_complex: integral_complex_to_floating_complex

  • integral_complex_to_real: integral_complex_to_real

  • integral_real_to_complex: integral_real_to_complex

  • integral_to_boolean: integral_to_boolean

  • integral_to_floating: integral_to_floating

  • integral_to_pointer: integral_to_pointer

  • lvalue_bitcast: lvalue_bitcast

  • lvalue_to_rvalue: lvalue_to_rvalue

  • member_pointer_to_boolean: member_pointer_to_boolean

  • non_atomic_to_atomic: non_atomic_to_atomic

  • null_to_member_pointer: null_to_member_pointer

  • null_to_pointer: null_to_pointer

  • pointer_to_boolean: pointer_to_boolean

  • pointer_to_integral: pointer_to_integral

  • reinterpret_member_pointer: reinterpret_member_pointer

  • to_union: to_union

  • to_void: to_void

  • unchecked_derived_to_base: unchecked_derived_to_base

  • user_defined_conversion: user_defined_conversion

  • vector_splat: vector_splat

CAST_CLASS

accepted forms are:

  • implicit: the cast is implicit

  • explicit: the cast is explicit

  • c_style: the cast is c_style

  • functional: the cast is functional

  • const: the cast is a const named cast

  • dynamic: the cast is a dynamic named cast

  • reinterpret: the cast is a reinterpret named cast

  • static: the cast is a static named cast

RELATION

accepted forms are:

  • : bigger_sizea cast to a bigger type

  • : bigger_size_pointeea cast from a pointer to another pointer with a bigger pointee

  • cast_away_const: a cast from a pointer to a const type to a pointer without the qualifier

  • cast_away_volatile: a cast from a pointer to a volatile type to a pointer without the qualifier

  • compatible_deep_unqualified: a cast from a type to a type that has the same pointee depth and where the innermost types without qualifiers are compatible

  • definitely_changes_value: a cast that definitely does change the source expression’s value

  • definitely_in_range: a cast whose cast value is definitely in the range of its type

  • definitely_out_range: a cast whose cast value is definitely out of range of its type

  • definitely_preserves_value: a cast that definitely does not change the source expression’s value

  • derived_to_virtual_base: a cast from a pointer to a class to a pointer to a virtual base class

  • enum_constant: a cast whose source expression is an enumeration constant and whose destination type is the same as the enumerator type

  • forget_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const or is void or Boolean

  • forget_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile or is void or Boolean

  • incompatible_unqualified_pointee: a cast from a pointer to a pointer with an incompatible unqualified pointee type

  • more_aligned_pointee: a cast from a pointer to a pointer with a more aligned pointee type

  • polymorphic_base_to_derived: a cast from a pointer to a base class with polymorphic type to a pointer to a derived class

  • qualification: a cast from a pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_from_void_pointee: a cast from a void pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_to_void_pointee: a cast from a pointer to void pointer where the destination pointee has all the qualifiers in the source pointee

  • same_type: a cast that does not change the type

  • same_unqualified_pointee: a cast from a pointer to a pointer with the same pointee type, ignoring any qualifications

  • signed_to_unsigned: a cast from a signed integral type to an unsigned integral type

  • unqualify_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const

  • unqualify_pointee: a cast from a pointer with a pointee type qualifier to another pointer whose pointee type does not have that qualifier

  • unqualify_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile

  • unqualify_atomic_pointee: a cast from a pointer with an _Atomic pointee type to another pointer whose pointee is not _Atomic

  • unsigned_to_signed: a cast from an unsigned integral type to a signed integral type

  • virtual_base_to_derived: a cast from a pointer to a virtual base class to a pointer to a derived class

FROM_MATCHER

accepted forms are:

  • type(TYPE_MATCHER): the type of the source expression matches TYPE_MATCHER (see the -type_selector global configuration)

  • expr(STMT_MATCHER): the source expression matches STMT_MATCHER (see the -stmt_selector global configuration)

LANGUAGE

accepted forms are:

  • c: C

  • cpp: C++

Rule CC2.EXP40

Summary

Do not modify constant values. (See page 134 of CERT-C-2014 [22] ☞.)

Description

A pointer to a type with a const qualifier should not be cast to a pointer to a type without the qualifier.

Any such casts, implicit or explicit, will be reported as a caution.

Configuration

See generic service options.

Option casts
casts
-config=CC2.EXP40,casts={TAGS, MATCHER},...

Specifies the report tags for casts.

The configuration’s content is a list of clauses specifying the casts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MATCHER:

comma-separated sequence of cast conditions. Accepted forms are:

  • [+]AND_MATCHER: the node matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||CAST_MATCHER: either the cast matches AND_MATCHER or it matches CAST_MATCHER

  • -AND_MATCHER||CAST_MATCHER: the cast does not match AND_MATCHER but does match CAST_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the cast matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the cast matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CAST_MATCHER): the cast matches CAST_MATCHER

  • !BASIC_MATCHER: the cast does not match BASIC_MATCHER

  • any(): any cast matches

  • none(): no cast matches

  • class(CAST_CLASS): the cast class is CAST_CLASS

  • context(CONTEXT_MATCHER): the cast is in a context matching CONTEXT_MATCHER (see the -context_selector global configuration)

  • from(FROM_MATCHER): the cast whose source expression matches FROM_MATCHER

  • syntactic(FROM_MATCHER)): the cast whose syntactic source expression (i.e., after removing all non-syntactic wrappers from the source) matches FROM_MATCHER

  • kind(CAST_KIND[||CAST_KIND]*): the cast kind is one of the CAST_KIND

  • language(LANGUAGE): the language is LANGUAGE

  • to(type(TYPE_MATCHER)): the cast whose destination type is matching TYPE_MATCHER (see the -type_selector global configuration)

  • relation(RELATION[||RELATION]*): the cast satisfies one of RELATION

CAST_KIND

accepted forms are:

  • no_op: no_op

  • address_space_conversion: address_space_conversion

  • array_to_pointer_decay: array_to_pointer_decay

  • atomic_to_non_atomic: atomic_to_non_atomic

  • base_to_derived: base_to_derived

  • base_to_derived_member_pointer: base_to_derived_member_pointer

  • bitcast: bitcast

  • boolean_to_signed_integral: boolean_to_signed_integral

  • builtin_function_to_pointer_decay: builtin_function_to_pointer_decay

  • constructor_conversion: constructor_conversion

  • dependent: dependent

  • derived_to_base: derived_to_base

  • derived_to_base_member_pointer: derived_to_base_member_pointer

  • dynamic: dynamic

  • floating_cast: floating_cast

  • floating_complex_cast: floating_complex_cast

  • floating_complex_to_boolean: floating_complex_to_boolean

  • floating_complex_to_integral_complex: floating_complex_to_integral_complex

  • floating_complex_to_real: floating_complex_to_real

  • floating_real_to_complex: floating_real_to_complex

  • floating_to_boolean: floating_to_boolean

  • floating_to_integral: floating_to_integral

  • function_to_pointer_decay: function_to_pointer_decay

  • integral_cast: integral_cast

  • integral_complex_cast: integral_complex_cast

  • integral_complex_to_boolean: integral_complex_to_boolean

  • integral_complex_to_floating_complex: integral_complex_to_floating_complex

  • integral_complex_to_real: integral_complex_to_real

  • integral_real_to_complex: integral_real_to_complex

  • integral_to_boolean: integral_to_boolean

  • integral_to_floating: integral_to_floating

  • integral_to_pointer: integral_to_pointer

  • lvalue_bitcast: lvalue_bitcast

  • lvalue_to_rvalue: lvalue_to_rvalue

  • member_pointer_to_boolean: member_pointer_to_boolean

  • non_atomic_to_atomic: non_atomic_to_atomic

  • null_to_member_pointer: null_to_member_pointer

  • null_to_pointer: null_to_pointer

  • pointer_to_boolean: pointer_to_boolean

  • pointer_to_integral: pointer_to_integral

  • reinterpret_member_pointer: reinterpret_member_pointer

  • to_union: to_union

  • to_void: to_void

  • unchecked_derived_to_base: unchecked_derived_to_base

  • user_defined_conversion: user_defined_conversion

  • vector_splat: vector_splat

CAST_CLASS

accepted forms are:

  • implicit: the cast is implicit

  • explicit: the cast is explicit

  • c_style: the cast is c_style

  • functional: the cast is functional

  • const: the cast is a const named cast

  • dynamic: the cast is a dynamic named cast

  • reinterpret: the cast is a reinterpret named cast

  • static: the cast is a static named cast

RELATION

accepted forms are:

  • : bigger_sizea cast to a bigger type

  • : bigger_size_pointeea cast from a pointer to another pointer with a bigger pointee

  • cast_away_const: a cast from a pointer to a const type to a pointer without the qualifier

  • cast_away_volatile: a cast from a pointer to a volatile type to a pointer without the qualifier

  • compatible_deep_unqualified: a cast from a type to a type that has the same pointee depth and where the innermost types without qualifiers are compatible

  • definitely_changes_value: a cast that definitely does change the source expression’s value

  • definitely_in_range: a cast whose cast value is definitely in the range of its type

  • definitely_out_range: a cast whose cast value is definitely out of range of its type

  • definitely_preserves_value: a cast that definitely does not change the source expression’s value

  • derived_to_virtual_base: a cast from a pointer to a class to a pointer to a virtual base class

  • enum_constant: a cast whose source expression is an enumeration constant and whose destination type is the same as the enumerator type

  • forget_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const or is void or Boolean

  • forget_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile or is void or Boolean

  • incompatible_unqualified_pointee: a cast from a pointer to a pointer with an incompatible unqualified pointee type

  • more_aligned_pointee: a cast from a pointer to a pointer with a more aligned pointee type

  • polymorphic_base_to_derived: a cast from a pointer to a base class with polymorphic type to a pointer to a derived class

  • qualification: a cast from a pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_from_void_pointee: a cast from a void pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_to_void_pointee: a cast from a pointer to void pointer where the destination pointee has all the qualifiers in the source pointee

  • same_type: a cast that does not change the type

  • same_unqualified_pointee: a cast from a pointer to a pointer with the same pointee type, ignoring any qualifications

  • signed_to_unsigned: a cast from a signed integral type to an unsigned integral type

  • unqualify_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const

  • unqualify_pointee: a cast from a pointer with a pointee type qualifier to another pointer whose pointee type does not have that qualifier

  • unqualify_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile

  • unqualify_atomic_pointee: a cast from a pointer with an _Atomic pointee type to another pointer whose pointee is not _Atomic

  • unsigned_to_signed: a cast from an unsigned integral type to a signed integral type

  • virtual_base_to_derived: a cast from a pointer to a virtual base class to a pointer to a derived class

FROM_MATCHER

accepted forms are:

  • type(TYPE_MATCHER): the type of the source expression matches TYPE_MATCHER (see the -type_selector global configuration)

  • expr(STMT_MATCHER): the source expression matches STMT_MATCHER (see the -stmt_selector global configuration)

LANGUAGE

accepted forms are:

  • c: C

  • cpp: C++

Rule CC2.EXP42

Summary

Do not compare padding data. (See page 136 of CERT-C-2014 [22] ☞.)

Description

There must be no calls to memcmp with arguments whose pointees are padding records.

Configuration

See generic service options.

Option calls
calls
-config=CC2.EXP42,calls={TAGS, CALL_MATCHER},...

Specifies the report tags for calls.

The configuration’s content is a list of clauses specifying the calls and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CALL_MATCHER:

a -call_selector identifier or a matcher expression used to select the calls.

Rule CC2.EXP44

Summary

Do not rely on side effects in operands to sizeof, _Alignof, or _Generic. (See page 147 of CERT-C-2014 [22] ☞.)

Description

Expressions with side effects must not be used in operands for calls to the sizeof, _Alignof, or _Generic operators.

Configuration

See generic service options.

Option effects
effects
-config=CC2.EXP44,effects={TAGS, CONDS},...

Specifies the report tags for effects.

The configuration’s content is a list of report tags with a set of conditions on the effects found within the context specified by the guideline.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONDS:

the effects found in the expression and its context must match CONDS. Accepted forms are:

  • [+]AND_MATCHER: the effects matches AND_MATCHER

  • -AND_MATCHER: the effects does not match AND_MATCHER

  • [+]AND_MATCHER||CONDS: either the effects match AND_MATCHER or match EFFECT_MATCHER

  • -AND_MATCHER||CONDS: the effects do not match AND_MATCHER but do match CONDS

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the effects match BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the effects match BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CONDS): the effects match CONDS

  • !BASIC_MATCHER: the effects do not match BASIC_MATCHER

  • any(): any effects match

  • none(): no effects match

  • count(RANGE,EFFECT_MATCHER): the context’s effects must satisfy RANGE and EFFECT_MATCHER

  • empty stringEFFECT_KIND: one of the expression’s effects must match EFFECT_KIND

EFFECT_MATCHER

accepted forms are:

  • EFFECT_MATCHER[&&EFFECT_MATCHER]*): the constraint is one of the EFFECT_MATCHER

RANGE

accepted forms are:

  • all: there can be any number of effects

  • any: there must be at least one effect

  • MIN_MAX: the number of effects must be in the range MIN_MAX

EFFECT_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the effects matches AND_MATCHER

  • -AND_MATCHER: the effects does not match AND_MATCHER

  • [+]AND_MATCHER||EFFECT_MATCHER: either the effects match AND_MATCHER or match EFFECT_MATCHER

  • -AND_MATCHER||EFFECT_MATCHER: the effects do not match AND_MATCHER but do match EFFECT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the effects match BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the effects match BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (EFFECT_MATCHER): the effects match EFFECT_MATCHER

  • !BASIC_MATCHER: the effects do not match BASIC_MATCHER

  • any(): any effects match

  • none(): no effects match

  • EFFECT_KIND: an effect matches EFFECT_KIND

EFFECT_KIND

accepted forms are:

  • asm: an asm

  • call: a call

  • const: call with property const

  • exit: exit

  • indirect_jump: an indirect jump

  • jump: jump

  • leave: leave

  • loop: loop

  • noeffect: call with property noeffect

  • nothrow: call with property nothrow

  • pure: call with property pure

  • read: read

  • read_write: read/write

  • throw: throw

  • unevaluated: an unevaluated expression

  • volatile: reference to a volatile

  • write: write

Rule CC2.EXP45

Summary

Do not perform assignments in selection statements. (See page 150 of CERT-C-2014 [22] ☞.)

Description

Any expression with a simple or compound assignment operator must not be used in one of the following ways:

  • as an operand of &&, ||;

  • in the condition part of the :? operator;

  • in the condition part of an if, do, for, or while statement;

  • as the right-hand side operand of a comma expression, when this comma expression is used in any of the other contexts.

Configuration

See generic service options.

Option statements
statements
-config=CC2.EXP45,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Option contexts
contexts
-config=CC2.EXP45,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Rule CC2.FIO41

Summary

Do not call getc(), putc(), getwc(), or putwc() with a stream argument that has side effects. (See page 329 of CERT-C-2014 [22] ☞.)

Description

Expressions with side effects must not be used in stream arguments for calls to the getc, putc, getwc, putwc input/output functions.

Configuration

See generic service options.

Option effects
effects
-config=CC2.FIO41,effects={TAGS, CONDS},...

Specifies the report tags for effects.

The configuration’s content is a list of report tags with a set of conditions on the effects found within the context specified by the guideline.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONDS:

the effects found in the expression and its context must match CONDS. Accepted forms are:

  • [+]AND_MATCHER: the effects matches AND_MATCHER

  • -AND_MATCHER: the effects does not match AND_MATCHER

  • [+]AND_MATCHER||CONDS: either the effects match AND_MATCHER or match EFFECT_MATCHER

  • -AND_MATCHER||CONDS: the effects do not match AND_MATCHER but do match CONDS

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the effects match BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the effects match BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CONDS): the effects match CONDS

  • !BASIC_MATCHER: the effects do not match BASIC_MATCHER

  • any(): any effects match

  • none(): no effects match

  • count(RANGE,EFFECT_MATCHER): the context’s effects must satisfy RANGE and EFFECT_MATCHER

  • empty stringEFFECT_KIND: one of the expression’s effects must match EFFECT_KIND

EFFECT_MATCHER

accepted forms are:

  • EFFECT_MATCHER[&&EFFECT_MATCHER]*): the constraint is one of the EFFECT_MATCHER

RANGE

accepted forms are:

  • all: there can be any number of effects

  • any: there must be at least one effect

  • MIN_MAX: the number of effects must be in the range MIN_MAX

EFFECT_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the effects matches AND_MATCHER

  • -AND_MATCHER: the effects does not match AND_MATCHER

  • [+]AND_MATCHER||EFFECT_MATCHER: either the effects match AND_MATCHER or match EFFECT_MATCHER

  • -AND_MATCHER||EFFECT_MATCHER: the effects do not match AND_MATCHER but do match EFFECT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the effects match BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the effects match BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (EFFECT_MATCHER): the effects match EFFECT_MATCHER

  • !BASIC_MATCHER: the effects do not match BASIC_MATCHER

  • any(): any effects match

  • none(): no effects match

  • EFFECT_KIND: an effect matches EFFECT_KIND

EFFECT_KIND

accepted forms are:

  • asm: an asm

  • call: a call

  • const: call with property const

  • exit: exit

  • indirect_jump: an indirect jump

  • jump: jump

  • leave: leave

  • loop: loop

  • noeffect: call with property noeffect

  • nothrow: call with property nothrow

  • pure: call with property pure

  • read: read

  • read_write: read/write

  • throw: throw

  • unevaluated: an unevaluated expression

  • volatile: reference to a volatile

  • write: write

Rule CC2.FIO47

Summary

Use valid format strings. (See page 344 of CERT-C-2014 [22] ☞.)

Description

The input/output functions must use formatting strings that are valid and compatible with the rest of the functions’ arguments.

This service depends upon the configuration of the following ancillary services: STD.fprscarg STD.fprscfmt

Configuration

See generic service options.

Option behaviors
behaviors
-config=CC2.FIO47,behaviors={TAGS, BEHAVIOR_MATCHER},...

Specifies the behaviors and ancillary services to be tagged.

The configuration’s content is associate report tags to behavior matchers.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

BEHAVIOR_MATCHER:

an expression selecting behaviors. Accepted forms are:

  • [+]AND_MATCHER: the behavior matches AND_MATCHER

  • -AND_MATCHER: the behavior does not match AND_MATCHER

  • [+]AND_MATCHER||BEHAVIOR_MATCHER: either the behavior matches AND_MATCHER or it matches BEHAVIOR_MATCHER

  • -AND_MATCHER||BEHAVIOR_MATCHER: the behavior does not match AND_MATCHER but does match BEHAVIOR_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the behavior matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the behavior matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (BEHAVIOR_MATCHER): the behavior matches BEHAVIOR_MATCHER

  • !BASIC_MATCHER: the behavior does not match BASIC_MATCHER

  • any(): any behavior matches

  • none(): no behavior matches

  • report(CLASS[||CLASS]*): the report class matches one of the classes

  • standard(CLASS[||CLASS]*): the standard class matches one of the classes

  • service(SERVICE_MATCHER): the behavior referring is for an ancillary service matching SERVICE_MATCHER (see the -service_selector global configuration)

  • category(REGEX): the behavior category matches ^REGEX$

REGEX

accepted forms are:

CLASS

accepted forms are:

  • implementation: implementation-defined

  • ill_formed: ill-formed

  • undefined: undefined

  • unspecified_critical: unspecified and critical

  • unspecified_not_critical: unspecified and not critical

  • unspecified: unspecified

  • limit: implementation limit

Rule CC2.FLP30

Summary

Do not use floating point variables as loop counters. (See page 197 of CERT-C-2014 [22] ☞.)

Configuration

See generic service options.

Option for_counter
for_counter
-config=CC2.FLP30,for_counter={TAGS, COUNTER},...

Specify report tags for the loop counters of for statements.

The configuration’s content is a set of pairs that associates report tags to the for statement loop counter that satisfies the constraints.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

COUNTER:

an expression defining the constraints on the loop counters. Accepted forms are:

  • [+]AND_MATCHER: the loop counter AND_MATCHER

  • -AND_MATCHER: the loop counter does not match AND_MATCHER

  • [+]AND_MATCHER||COUNT_MATCHER: either the loop counter matches AND_MATCHER or it matches COUNT_MATCHER

  • -AND_MATCHER||COUNT_MATCHER: the loop counter does not match AND_MATCHER but does match COUNT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the loop counter matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the loop counter matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (COUNT_MATCHER): the loop counter matches COUNT_MATCHER

  • !BASIC_MATCHER: the loop counter does not match BASIC_MATCHER

  • any(): any loop counter matches

  • none(): no loop counter matches

  • global(): the loop counter is a global variable

  • is_in_test(): the loop counter is in a relational or equality test or in a function call in the condition part of the head

  • tested_in_condition(): the loop counter is an operand of a relational or equality test or in a function call in the condition part of the head

  • tested_in_relation(): the loop counter is an operand of a relational test in the condition part of the head

  • modify_is_monotonic(): the loop counter is monotonically incremented or decremented in the after part of the head

  • taken(): the loop counter is stored or passed

  • has_body_modification(): the loop counter is modified in the body

  • variable(): the loop counter is a variable

  • single(): the loop counter is unique

  • type(TYPE_MATCHER): the loop counter has a type that matches TYPE_MATCHER (see the -type_selector global configuration)

Rule CC2.INT34

Summary

Do not shift an expression by a negative number of bits or by greater than or equal to the number of bits that exist in the operand. (See page 183 of CERT-C-2014 [22] ☞.)

Description

The value of the right-hand operand of a shift operator must lie between zero and one less than the width in bits of the underlying type of the left-hand operand.

Source code expressions and preprocessor conditional expressions are checked.

Where the values are unknown, a caution is output.

Imprecision

Cautions are reported for non-constant values on the right-hand side of a shift operator.

Configuration

See generic service options.

Option out_of_bounds
out_of_bounds
-config=CC2.INT34,out_of_bounds=CONDITIONS,...

Specify the out-of-bounds conditions.

{CONDITIONS,…}:

set of conditions. Accepted members are:

  • signed_negative_or_too_big_for_type: flag if the rhs is signed and is non-constant or has a value that is negative or greater than W - 1, where W is the width in bits of the lhs;

  • negative_or_too_big_for_type: flag if the rhs has a known constant value that is negative or greater than W - 1, where W is the width in bits of the lhs;

  • negative_or_too_big_for_essential_type: flag if the rhs has a known constant value that is negative or greater than W - 1, where W is the width in bits of the MISRA essential type of the lhs;

Default:

-config=CC2.INT34,out_of_bounds=negative_or_too_big_for_type

Rule CC2.INT36

Summary

Converting a pointer to integer or integer to pointer. (See page 190 of CERT-C-2014 [22] ☞.)

Description

A pointer type must not be cast to an integer type and an integer type must not be cast to a pointer type.

Explicit casts from integral constants to pointers are permitted to allow addressing of hardware memory mapped areas.

Configuration

See generic service options.

Option casts
casts
-config=CC2.INT36,casts={TAGS, MATCHER},...

Specifies the report tags for casts.

The configuration’s content is a list of clauses specifying the casts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MATCHER:

comma-separated sequence of cast conditions. Accepted forms are:

  • [+]AND_MATCHER: the node matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||CAST_MATCHER: either the cast matches AND_MATCHER or it matches CAST_MATCHER

  • -AND_MATCHER||CAST_MATCHER: the cast does not match AND_MATCHER but does match CAST_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the cast matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the cast matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CAST_MATCHER): the cast matches CAST_MATCHER

  • !BASIC_MATCHER: the cast does not match BASIC_MATCHER

  • any(): any cast matches

  • none(): no cast matches

  • class(CAST_CLASS): the cast class is CAST_CLASS

  • context(CONTEXT_MATCHER): the cast is in a context matching CONTEXT_MATCHER (see the -context_selector global configuration)

  • from(FROM_MATCHER): the cast whose source expression matches FROM_MATCHER

  • syntactic(FROM_MATCHER)): the cast whose syntactic source expression (i.e., after removing all non-syntactic wrappers from the source) matches FROM_MATCHER

  • kind(CAST_KIND[||CAST_KIND]*): the cast kind is one of the CAST_KIND

  • language(LANGUAGE): the language is LANGUAGE

  • to(type(TYPE_MATCHER)): the cast whose destination type is matching TYPE_MATCHER (see the -type_selector global configuration)

  • relation(RELATION[||RELATION]*): the cast satisfies one of RELATION

CAST_KIND

accepted forms are:

  • no_op: no_op

  • address_space_conversion: address_space_conversion

  • array_to_pointer_decay: array_to_pointer_decay

  • atomic_to_non_atomic: atomic_to_non_atomic

  • base_to_derived: base_to_derived

  • base_to_derived_member_pointer: base_to_derived_member_pointer

  • bitcast: bitcast

  • boolean_to_signed_integral: boolean_to_signed_integral

  • builtin_function_to_pointer_decay: builtin_function_to_pointer_decay

  • constructor_conversion: constructor_conversion

  • dependent: dependent

  • derived_to_base: derived_to_base

  • derived_to_base_member_pointer: derived_to_base_member_pointer

  • dynamic: dynamic

  • floating_cast: floating_cast

  • floating_complex_cast: floating_complex_cast

  • floating_complex_to_boolean: floating_complex_to_boolean

  • floating_complex_to_integral_complex: floating_complex_to_integral_complex

  • floating_complex_to_real: floating_complex_to_real

  • floating_real_to_complex: floating_real_to_complex

  • floating_to_boolean: floating_to_boolean

  • floating_to_integral: floating_to_integral

  • function_to_pointer_decay: function_to_pointer_decay

  • integral_cast: integral_cast

  • integral_complex_cast: integral_complex_cast

  • integral_complex_to_boolean: integral_complex_to_boolean

  • integral_complex_to_floating_complex: integral_complex_to_floating_complex

  • integral_complex_to_real: integral_complex_to_real

  • integral_real_to_complex: integral_real_to_complex

  • integral_to_boolean: integral_to_boolean

  • integral_to_floating: integral_to_floating

  • integral_to_pointer: integral_to_pointer

  • lvalue_bitcast: lvalue_bitcast

  • lvalue_to_rvalue: lvalue_to_rvalue

  • member_pointer_to_boolean: member_pointer_to_boolean

  • non_atomic_to_atomic: non_atomic_to_atomic

  • null_to_member_pointer: null_to_member_pointer

  • null_to_pointer: null_to_pointer

  • pointer_to_boolean: pointer_to_boolean

  • pointer_to_integral: pointer_to_integral

  • reinterpret_member_pointer: reinterpret_member_pointer

  • to_union: to_union

  • to_void: to_void

  • unchecked_derived_to_base: unchecked_derived_to_base

  • user_defined_conversion: user_defined_conversion

  • vector_splat: vector_splat

CAST_CLASS

accepted forms are:

  • implicit: the cast is implicit

  • explicit: the cast is explicit

  • c_style: the cast is c_style

  • functional: the cast is functional

  • const: the cast is a const named cast

  • dynamic: the cast is a dynamic named cast

  • reinterpret: the cast is a reinterpret named cast

  • static: the cast is a static named cast

RELATION

accepted forms are:

  • : bigger_sizea cast to a bigger type

  • : bigger_size_pointeea cast from a pointer to another pointer with a bigger pointee

  • cast_away_const: a cast from a pointer to a const type to a pointer without the qualifier

  • cast_away_volatile: a cast from a pointer to a volatile type to a pointer without the qualifier

  • compatible_deep_unqualified: a cast from a type to a type that has the same pointee depth and where the innermost types without qualifiers are compatible

  • definitely_changes_value: a cast that definitely does change the source expression’s value

  • definitely_in_range: a cast whose cast value is definitely in the range of its type

  • definitely_out_range: a cast whose cast value is definitely out of range of its type

  • definitely_preserves_value: a cast that definitely does not change the source expression’s value

  • derived_to_virtual_base: a cast from a pointer to a class to a pointer to a virtual base class

  • enum_constant: a cast whose source expression is an enumeration constant and whose destination type is the same as the enumerator type

  • forget_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const or is void or Boolean

  • forget_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile or is void or Boolean

  • incompatible_unqualified_pointee: a cast from a pointer to a pointer with an incompatible unqualified pointee type

  • more_aligned_pointee: a cast from a pointer to a pointer with a more aligned pointee type

  • polymorphic_base_to_derived: a cast from a pointer to a base class with polymorphic type to a pointer to a derived class

  • qualification: a cast from a pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_from_void_pointee: a cast from a void pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_to_void_pointee: a cast from a pointer to void pointer where the destination pointee has all the qualifiers in the source pointee

  • same_type: a cast that does not change the type

  • same_unqualified_pointee: a cast from a pointer to a pointer with the same pointee type, ignoring any qualifications

  • signed_to_unsigned: a cast from a signed integral type to an unsigned integral type

  • unqualify_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const

  • unqualify_pointee: a cast from a pointer with a pointee type qualifier to another pointer whose pointee type does not have that qualifier

  • unqualify_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile

  • unqualify_atomic_pointee: a cast from a pointer with an _Atomic pointee type to another pointer whose pointee is not _Atomic

  • unsigned_to_signed: a cast from an unsigned integral type to a signed integral type

  • virtual_base_to_derived: a cast from a pointer to a virtual base class to a pointer to a derived class

FROM_MATCHER

accepted forms are:

  • type(TYPE_MATCHER): the type of the source expression matches TYPE_MATCHER (see the -type_selector global configuration)

  • expr(STMT_MATCHER): the source expression matches STMT_MATCHER (see the -stmt_selector global configuration)

LANGUAGE

accepted forms are:

  • c: C

  • cpp: C++

Rule CC2.MSC30

Summary

Do not use the rand() function for generating pseudorandom numbers. (See page 481 of CERT-C-2014 [22] ☞.)

Description

There must be no use of the standard library function rand.

Configuration

See generic service options.

Option declarations
declarations
-config=CC2.MSC30,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CC2.MSC37

Summary

Ensure that control never reaches the end of a non-void function. (See page 491 of CERT-C-2014 [22] ☞.)

Configuration

See generic service options.

Option statements
statements
-config=CC2.MSC37,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Option contexts
contexts
-config=CC2.MSC37,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Option ignored_stmts
ignored_stmts
-config=CC2.MSC37,ignored_stmts={STMT_CONTEXT_SELECTOR},...

Specify the stmts that should be ignored.

The configuration’s content is a list of clauses specifying the stmts.

STMT_CONTEXT_SELECTOR:

an expression defining the matching node with its context, where node refers to a statement or expression and context refers to a its chain of ancestors in the AST. Accepted forms are:

  • OR_MATCHER: the node and context matches OR_MATCHER

OR_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the node and context matches AND_MATCHER

  • -AND_MATCHER: the node and context does not match AND_MATCHER

  • [+]AND_MATCHER||SPEC_CTXT_MATCHER: either the node and context matches AND_MATCHER or it matches SPEC_CTXT_MATCHER

  • -AND_MATCHER||SPEC_CTXT_MATCHER: the node and context does not match AND_MATCHER but does match SPEC_CTXT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the the node and context matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the node and context matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (SPEC_CTXT_MATCHER): the node and context matches SPEC_CTXT_MATCHER

  • !BASIC_MATCHER: node and context does not match BASIC_MATCHER

  • any(): matches any node and context

  • none(): matches no node and context

  • context(CTXT_MATCHER): context matches CTXT_MATCHER (see the -context_selector global configuration)

  • SPEC_MATCHER: node matches an AST node selector depending on the node selector specification

SPEC_MATCHER

accepted forms are:

  • STMT_MATCHER: node is a statement or expression that matches STMT_MATCHER (see the -stmt_selector global configuration)

Rule CC2.PRE30

Summary

Do not create a universal character name through concatenation. (See page 47 of CERT-C-2014 [22] ☞.)

Description

A universal character name must not be created by means of concatenation.

Configuration

See generic service options.

Option diagnostics
diagnostics
-config=CC2.PRE30,diagnostics={TAGS, DIAG_TAG},...

Assigns report tags to the parser diagnostics.

The configuration’s content is a list of clauses specifying the diagnostics and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DIAG_TAG:

a -name_selector identifier or a matcher expression used to select the diagnostics. Accepted forms are:

  • ^REGEX$: the name matches ^REGEX$

  • !NAME_MATCHER: the name does not match NAME_MATCHER

  • TEXT: the name is TEXT

Rule CC2.PRE31

Summary

Avoid side-effects in arguments to unsafe macros. (See page 48 of CERT-C-2014 [22] ☞.)

Description

Checks that:

  • if an argument in an invocation of a function-like macro expands to an expression that contains a side effect, then the corresponding parameter occurs no more than once in the macro body;

  • if an (unexpanded) argument in an invocation of a function-like macro has an assignment, increment or decrement operator, then the corresponding parameter occurs at least once in the macro body.

Configuration

See generic service options.

Option macro_argument_context
macro_argument_context
-config=CC2.PRE31,macro_argument_context=CONTEXT_MATCHER,...

Specifies contexts of macro arguments that should be ignored.

The configuration’s content is a list of clauses specifying contexts for macro argument.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select contexts of macro arguments.

Default:

-config=CC2.PRE31,macro_argument_context={}
Option macros
macros
-config=CC2.PRE31,macros={TAGS, MACRO_MATCHER},...

Specifies the report tags for macros.

The configuration’s content is a list of clauses specifying the macros and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Rule CC2.PRE32

Summary

Do not use preprocessor directives in invocations of function-like macros. (See page 53 of CERT-C-2014 [22] ☞.)

Description

Function-like macros must not include preprocessor directives.

Configuration

See generic service options.

Option macro_argument_context
macro_argument_context
-config=CC2.PRE32,macro_argument_context=CONTEXT_MATCHER,...

Specifies contexts of macro arguments that should be ignored.

The configuration’s content is a list of clauses specifying contexts for macro argument.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select contexts of macro arguments.

Default:

-config=CC2.PRE32,macro_argument_context={}
Option macros
macros
-config=CC2.PRE32,macros={TAGS, MACRO_MATCHER},...

Specifies the report tags for macros.

The configuration’s content is a list of clauses specifying the macros and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Rule CC2.STR30

Summary

Do not attempt to modify string literals. (See page 247 of CERT-C-2014 [22] ☞.)

Description

String literals must not be modified.

Configuration

See generic service options.

Rule CC2.STR34

Summary

Cast characters to unsigned char before converting to larger integer sizes. (See page 268 of CERT-C-2014 [22] ☞.)

Description

Signed character data (and plain character data where plain char is defined to have the same representation as signed char) must be converted to unsigned char before being assigned or converted to a larger signed type.

Configuration

See generic service options.

Rule CC2.STR37

Summary

Arguments to character-handling functions must be representable as an unsigned char. (See page 272 of CERT-C-2014 [22] ☞.)

Description

If the plain char type is defined to have the same representation as signed char, then the arguments to character handling functions must be representable as an unsigned char.

Configuration

See generic service options.

Option calls
calls
-config=CC2.STR37,calls={TAGS, CALL_MATCHER},...

Specifies the report tags for calls.

The configuration’s content is a list of clauses specifying the calls and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CALL_MATCHER:

a -call_selector identifier or a matcher expression used to select the calls.

Option macro_argument_context
macro_argument_context
-config=CC2.STR37,macro_argument_context=CONTEXT_MATCHER,...

Specifies contexts of macro arguments that should be ignored.

The configuration’s content is a list of clauses specifying contexts for macro argument.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select contexts of macro arguments.

Default:

-config=CC2.STR37,macro_argument_context={}
Option macros
macros
-config=CC2.STR37,macros={TAGS, MACRO_MATCHER},...

Specifies the report tags for macros.

The configuration’s content is a list of clauses specifying the macros and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Rule CC2.STR38

Summary

Do not confuse narrow and wide character strings and functions. (See page 274 of CERT-C-2014 [22] ☞.)

Description

Narrow string arguments must not be passed to wide string functions and wide string arguments must not be passed to narrow string functions.

Configuration

See generic service options.

Option diagnostics
diagnostics
-config=CC2.STR38,diagnostics={TAGS, DIAG_TAG},...

Assigns report tags to the parser diagnostics.

The configuration’s content is a list of clauses specifying the diagnostics and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DIAG_TAG:

a -name_selector identifier or a matcher expression used to select the diagnostics. Accepted forms are:

  • ^REGEX$: the name matches ^REGEX$

  • !NAME_MATCHER: the name does not match NAME_MATCHER

  • TEXT: the name is TEXT

The CERT C Secure Coding Standard recommendations

Rule CCR.API08

Summary

Protect header prototypes from misinterpretation. (See https://www.securecoding.cert.org/confluence/display/seccode/API08-C.+Protect+header+prototypes+from+misinterpretation ☞.)

Configuration

See generic service options.

Option declarations
declarations
-config=CCR.API08,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CCR.ARR02

Summary

Explicitly specify array bounds, even if implicitly defined by an initializer. (See https://www.securecoding.cert.org/confluence/display/seccode/ARR02-C.+Explicitly+specify+array+bounds%2C+even+if++implicitly+defined+by+an+initializer ☞.)

Configuration

See generic service options.

Option declarations
declarations
-config=CCR.ARR02,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CCR.DCL00

Summary

Const-qualify immutable objects. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL00-C.+Const-qualify+immutable+objects ☞.)

Description

In the declarations of variables, use const wherever possible.

Configuration

See generic service options.

Option show_declarations
show_declarations
-config=CCR.DCL00,show_declarations=WHAT

Specify what declarations should be shown.

WHAT:

indicate which declarations should be shown. Accepted values are:

  • all: all the declarations are shown;

  • none: only the definition is shown;

  • param: declarations will only be shown if they do not need to have their constness changed just to ensure compilation;

  • non_param: declarations will be shown if, to ensure compilation, they must have their constness changed to be congruent to the definition (or for parameters the corresponding parameters in the function definition);

Default:

-config=CCR.DCL00,show_declarations=all
Option single_assign
single_assign
-config=CCR.DCL00,single_assign=BOOL

Specify if an uninitialized local variable declaration with a single assignment may be considered for converting the constness to const.

BOOL:

boolean. Accepted values are:

  • true: an uninitialized local variable declaration with a single assignment will be considered for converting the constness to const;

  • false: an uninitialized local variable declaration with a single assignment will not be considered for converting the constness to const;

Default:

-config=CCR.DCL00,single_assign=true
Option declarations
declarations
-config=CCR.DCL00,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option all_decls
all_decls
-config=CCR.DCL00,all_decls=BOOL

Specify whether to show all or just a single representative declaration for each reported entity.

BOOL:

boolean indicating whether to show one or all declarations. Accepted values are:

  • true: show all declarations for each reported entity;

  • false: show a representative declaration for each reported entity;

Rule CCR.DCL01

Summary

Do not reuse variable names in subscopes. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL01-C.+Do+not+reuse+variable+names+in+subscopes ☞.)

Configuration

See generic service options.

Rule CCR.DCL02

Summary

Use visually distinct identifiers. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL02-C.+Use+visually+distinct+identifiers ☞.)

Description

The first 31 characters of any identifier (including macro and macro parameter names) must be unique (compared to all other identifiers visible in its scope) after applying the following ordered list of replacements:

  • replace 0 by O,

  • replace D by O,

  • replace 1 by I,

  • replace l by I,

  • replace 5 by S,

  • replace 2 by Z,

  • replace 8 by B,

  • replace rn by m,

  • replace h by n.

Notes:

  • selected entities and macros can be ignored using the ignored_decls and ignored_macros service configurations;

  • since this service checks for name clashes between multiple entities, the configuration parameters that exclude selected entities or portions of code should be used with care since a name clash between an excluded entity and another will not be reported.

Configuration

See generic service options.

Option similar_map
similar_map
-config=CCR.DCL02,similar_map={MATCH_ID, MAPPING},...

Specify mappings of identifiers to their canonical form.

The configuration’s content is a list of identifier mappings.

MATCH_ID:

the identifier for the selected entities.

MAPPING:

. Accepted forms are:

  • std(REGEX): matches a service

  • min(NUMBER,CASE): the identifier prefix of length NUMBER, (after convertion to upper-case, if CASE is case_insensitive), is the canonical form

  • REPLACER[||REPLACER]*): a list of alternative REPLACERs (see the -replacer global configuration) defining the replacements that map the identifier to its canonical forms

CASE

accepted forms are:

  • case_sensitive: the identifier is case-sensitive

  • case_insensitive: the identifier is case-insensitive and the canonical form has all letters converted to upper-case

Default:

-config=CCR.DCL02,similar_map={all_identifiers, "substr(0,31)|replace('rn','m')|tr('0D1l528h','OOIISZBn')"}
Option identifier_length
identifier_length
-config=CCR.DCL02,identifier_length={SEL, CASE, LEN},...

Specify significant length and case significance for identifiers for selected entities.

The configuration’s content is a list of entity matchers with significant length and case significance.

SEL:

a -entity_selector identifier or a matcher expression used to select the entities.

CASE:

indicate if case is significant. Accepted values are:

  • case_insensitive: case is not significant;

  • case_sensitive: case is significant;

LEN:

length of significant leading part of identifier; 0 indicates that there is no limit. It must be an integer greater than or equal to 0.

Option ignored_decls
ignored_decls
-config=CCR.DCL02,ignored_decls=DECL_MATCHER,...

Specify the declarations that should be ignored.

The configuration’s content is a list of declaration matchers.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Default:

-config=CCR.DCL02,ignored_decls={}
Option ignored_macros
ignored_macros
-config=CCR.DCL02,ignored_macros=MACRO_MATCHER,...

Specify the macros that should be ignored.

The configuration’s content is a list of macro matchers.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Default:

-config=CCR.DCL02,ignored_macros={}

Rule CCR.DCL03

Summary

Use a static assertion to test the value of a constant expression. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL03-C.+Use+a+static+assertion+to+test+the+value+of+a+constant+expression ☞.)

Configuration

See generic service options.

Option macro_argument_context
macro_argument_context
-config=CCR.DCL03,macro_argument_context=CONTEXT_MATCHER,...

Specifies contexts of macro arguments that should be ignored.

The configuration’s content is a list of clauses specifying contexts for macro argument.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select contexts of macro arguments.

Default:

-config=CCR.DCL03,macro_argument_context={}
Option macros
macros
-config=CCR.DCL03,macros={TAGS, MACRO_MATCHER},...

Specifies the report tags for macros.

The configuration’s content is a list of clauses specifying the macros and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Rule CCR.DCL04

Summary

Do not declare more than one variable per declaration. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL04-C.+Do+not+declare+more+than+one+variable+per+declaration ☞.)

Description

Each variable declarator must be on a separate line have its own personal declaration.

Configuration

See generic service options.

Option contexts
contexts
-config=CCR.DCL04,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Rule CCR.DCL06

Summary

Use meaningful symbolic constants to represent literal values. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL06-C.+Use+meaningful+symbolic+constants+to+represent+literal+values ☞.)

Configuration

See generic service options.

Option literal_matches
literal_matches
-config=CCR.DCL06,literal_matches={TAG, {LIT_COND,...}},...

Specify what is a magic constant.

TAG:

a tag with values hide and show. Accepted values are:

  • hide: hide if it matches the associated conditions;

  • show: show if it matches the associated conditions;

LIT_COND:

literal condition. Accepted alternatives are:

  • {ancestors, CTXT}: .

    CTXT:

    a -context_selector identifier or a matcher expression used to select the contexts.

  • {text, TEXT_RE}: regular expression to match literal.

    TEXT_RE:

    constant text matcher.

  • {character_literal}: character literal.

  • {wide_char_literal}: wide char literal.

  • {utf16_char_literal}: utf16 char literal.

  • {utf32_char_literal}: utf32 char literal.

  • {floating_literal}: floating literal.

  • {integer_literal}: integer literal.

  • {string_literal}: string literal.

  • {wide_string_literal}: wide string literal.

  • {utf8_string_literal}: utf8 string literal.

  • {utf16_string_literal}: utf16 string literal.

  • {utf32_string_literal}: utf32 string literal.

Default:

-config=CCR.DCL06,literal_matches={hide, {{integer_literal}, {text, "^(0|1|2)[LUlu]*$"}}}, {hide, {{ancestors, "skip(parent(__non_syntactic_or_paren_contexts||node(named_cast_expr||c_style_cast_expr)),is(init)&&parent(decl(__init_var_decls&&type(__const_top_level_types))))"}}}, {hide, {{ancestors, "skip(class(expr),is(init)&&parent(node(enum_constant_decl)))"}}}
Option literal_kinds
literal_kinds
-config=CCR.DCL06,literal_kinds=LIT,...

Specify the kinds of literals to be checked.

{LIT,…}:

the literal families to be checked. Accepted members are:

  • floating_literal: floating literal;

  • integer_literal: integer literal;

  • character_literal: character literal;

  • string_literal: string literal;

  • ordinary: ordinary character or string literal;

  • wide: wide character or string literal;

  • utf16: utf16 character or string literal;

  • utf32: utf32 char literal;

  • utf8: utf8 string literal;

Default:

-config=CCR.DCL06,literal_kinds=character_literal, integer_literal, floating_literal, string_literal
Option statements
statements
-config=CCR.DCL06,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Rule CCR.DCL07

Summary

Include the appropriate type information in function declarators. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL07-C.+Include+the+appropriate+type+information+in+function+declarators ☞.)

Description

Checks that:

  • the type of any parameter or object declaration is explicitly stated;

  • the type of the return value of any function declaration or definition is explicitly stated;

  • there are no K&R function declarations.

Configuration

See generic service options.

Option declarations
declarations
-config=CCR.DCL07,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CCR.DCL11

Summary

Understand the type issues associated with variadic functions. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL11-C.+Understand+the+type+issues+associated+with+variadic+functions ☞.)

Description

The input/output functions must use formatting strings that are valid and compatible with the rest of the functions’ arguments.

This service depends upon the configuration of the following ancillary services: STD.fprscarg STD.fprscfmt

Configuration

See generic service options.

Option behaviors
behaviors
-config=CCR.DCL11,behaviors={TAGS, BEHAVIOR_MATCHER},...

Specifies the behaviors and ancillary services to be tagged.

The configuration’s content is associate report tags to behavior matchers.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

BEHAVIOR_MATCHER:

an expression selecting behaviors. Accepted forms are:

  • [+]AND_MATCHER: the behavior matches AND_MATCHER

  • -AND_MATCHER: the behavior does not match AND_MATCHER

  • [+]AND_MATCHER||BEHAVIOR_MATCHER: either the behavior matches AND_MATCHER or it matches BEHAVIOR_MATCHER

  • -AND_MATCHER||BEHAVIOR_MATCHER: the behavior does not match AND_MATCHER but does match BEHAVIOR_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the behavior matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the behavior matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (BEHAVIOR_MATCHER): the behavior matches BEHAVIOR_MATCHER

  • !BASIC_MATCHER: the behavior does not match BASIC_MATCHER

  • any(): any behavior matches

  • none(): no behavior matches

  • report(CLASS[||CLASS]*): the report class matches one of the classes

  • standard(CLASS[||CLASS]*): the standard class matches one of the classes

  • service(SERVICE_MATCHER): the behavior referring is for an ancillary service matching SERVICE_MATCHER (see the -service_selector global configuration)

  • category(REGEX): the behavior category matches ^REGEX$

REGEX

accepted forms are:

CLASS

accepted forms are:

  • implementation: implementation-defined

  • ill_formed: ill-formed

  • undefined: undefined

  • unspecified_critical: unspecified and critical

  • unspecified_not_critical: unspecified and not critical

  • unspecified: unspecified

  • limit: implementation limit

Rule CCR.DCL13

Summary

Declare function parameters that are pointers to values not changed by the function as const. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL13-C.+Declare+function+parameters+that+are+pointers+to+values+not+changed+by+the+function+as+const ☞.)

Configuration

See generic service options.

Option show_declarations
show_declarations
-config=CCR.DCL13,show_declarations=WHAT

Specify what declarations should be shown.

WHAT:

indicate which declarations should be shown. Accepted values are:

  • all: all the declarations are shown;

  • none: only the definition is shown;

  • param: declarations will only be shown if they do not need to have their constness changed just to ensure compilation;

  • non_param: declarations will be shown if, to ensure compilation, they must have their constness changed to be congruent to the definition (or for parameters the corresponding parameters in the function definition);

Default:

-config=CCR.DCL13,show_declarations=all
Option declarations
declarations
-config=CCR.DCL13,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option all_decls
all_decls
-config=CCR.DCL13,all_decls=BOOL

Specify whether to show all or just a single representative declaration for each reported entity.

BOOL:

boolean indicating whether to show one or all declarations. Accepted values are:

  • true: show all declarations for each reported entity;

  • false: show a representative declaration for each reported entity;

Rule CCR.DCL15

Summary

Declare file-scope objects or functions that do not need external linkage as static. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL15-C.+Declare+file-scope+objects+or+functions+that+do+not+need+external+linkage+as+static ☞.)

Description

A function or variable will be reported if all the following hold:

  • it has linkage;

  • it is referenced;

  • either all references to it are in the same function or, if it is a variable with external linkage, then all references are in the same unit;

  • it is not explicitly declared static.

Configuration

See generic service options.

Option definition_in_same_unit
definition_in_same_unit
-config=CCR.DCL15,definition_in_same_unit=BOOL

Specify if the definition must be in the same translation unit as the references.

BOOL

Accepted values are:

  • true: the definition must be in the same translation unit as the references;

  • false: the definition does not have to be in the same translation unit as the references;

Default:

-config=CCR.DCL15,definition_in_same_unit=true
Option declarations
declarations
-config=CCR.DCL15,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CCR.DCL16

Summary

Use ‘L’, not ‘l’, to indicate a long value. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL16-C.+Use+%27L%27%2C+not+%27l%27%2C+to+indicate+a+long+value ☞.)

Configuration

See generic service options.

Option statements
statements
-config=CCR.DCL16,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Rule CCR.DCL19

Summary

Minimize the scope of variables and functions. (See https://www.securecoding.cert.org/confluence/display/seccode/DCL19-C.+Minimize+the+scope+of+variables+and+functions ☞.)

Description

Reports any variable for which one of the following holds:

  • it can be declared in a smaller block;

  • it is used in a single function but does not have function scope;

  • it is used in a single file but declared in a different file.

Configuration

See generic service options.

Option declarations
declarations
-config=CCR.DCL19,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option all_decls
all_decls
-config=CCR.DCL19,all_decls=BOOL

Specify whether to show all or just a single representative declaration for each reported entity.

BOOL:

boolean indicating whether to show one or all declarations. Accepted values are:

  • true: show all declarations for each reported entity;

  • false: show a representative declaration for each reported entity;

Rule CCR.ERR01

Summary

Use ferror() rather than errno to check for FILE stream errors. (See https://www.securecoding.cert.org/confluence/display/seccode/ERR01-C.+Use+ferror%28%29+rather+than+errno+to+check+for+FILE+stream+errors ☞.)

Configuration

See generic service options.

Option macros
macros
-config=CCR.ERR01,macros={TAGS, MACRO_MATCHER},...

Specifies the report tags for macros.

The configuration’s content is a list of clauses specifying the macros and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MACRO_MATCHER:

a -macro_selector identifier or a matcher expression used to select the macros.

Option declarations
declarations
-config=CCR.ERR01,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CCR.EXP00

Summary

Use parentheses for precedence of operation. (See https://www.securecoding.cert.org/confluence/display/seccode/EXP00-C.+Use+parentheses+for+precedence+of+operation ☞.)

Configuration

See generic service options.

Option trusted_pairs
trusted_pairs
-config=CCR.EXP00,trusted_pairs={TAGS, PAIRS},...

Specify the tags for trusted pairs of main and child operators.

The configuration’s content is a set of tagged main and child operator pairs.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

PAIRS:

the main and child operator trusted pair. Accepted forms are:

  • OP_PAIR[||OP_PAIR]*: main and child operator pairs

OP_PAIR

accepted forms are:

  • OPERATOR_TAG1:OPERATOR_TAG2: main and child operator pair

OPERATOR_TAG

accepted forms are:

  • arrow: -> member designation operator

  • dot: . member designation operator

  • arrow_star: ->* pointer to member operator

  • dot_star: .* pointer to member operator

  • addrof: & address-of operator

  • co_await: co_await operator

  • deref: * indirection operator

  • imag: imaginary part operator

  • real: real part operator

  • plus: + unary plus operator

  • minus: - unary minus operator

  • not: ~ one’s complement operator

  • lnot: ! logical negation operator

  • post_dec: -- postfix decrement operator

  • post_inc: ++ postfix increment operator

  • pre_dec: -- prefix decrement operator

  • pre_inc: ++ prefix increment operator

  • sizeof_expr: sizeof operator

  • sizeof_type: sizeof operator

  • alignof_expr: alignof operator

  • alignof_type: alignof operator

  • vec_step_expr: vec_step operator

  • vec_step_type: vec_step operator

  • extension: extension operator

  • div: / division operator

  • mul: * multiplication operator

  • rem: % remainder operator

  • add: + addition operator

  • sub: - subtraction operator

  • shl: << left shift operator

  • shr: >> right shift operator

  • ge: >= greater-than or equal operator

  • gt: > greater-than operator

  • le: <= less-than or equal operator

  • lt: < less-than operator

  • eq: == equality operator

  • ne: != inequality operator

  • and: & bitwise AND operator

  • or: | bitwise OR operator

  • xor: ^ bitwise XOR operator

  • land: && logical AND operator

  • lor: || logical OR operator

  • conditional: ?: conditional operator

  • binary_conditional: ?: binary conditional operator

  • assign: = assignment operator

  • add_assign: += addition assignment operator

  • and_assign: &= bitwise AND assignment operator

  • div_assign: /= division assignment operator

  • mul_assign: *= multiplication assignment operator

  • or_assign: |= bitwise OR assignment operator

  • rem_assign: %= remainder assignment operator

  • shl_assign: <<= left shift assignment operator

  • shr_assign: >>= right shift assignment operator

  • sub_assign: -= subtraction assignment operator

  • xor_assign: ^= bitwise XOR assignment operator

  • throw: throw operator

  • comma: , comma operator

  • OP_COLLECTION: operator collections

OP_COLLECTION

accepted forms are:

  • multiplicative: *, / or % operator

  • additive: + or - operator

  • equality: == or != operator

  • relational: <, <=, > or >= operator

  • bitwise: ^, & or | operator

  • binary_logical: || or &&

  • logical: ||, && or ! operator

  • arithmetic: +, -, *, /, %, real or imag operator

  • assignment: =, +=, &=, /=, *=, <<=, >>=, -= or ^= operator

Rule CCR.EXP05

Summary

Do not cast away a const qualification. (See https://www.securecoding.cert.org/confluence/display/seccode/EXP05-C.+Do+not+cast+away+a+const+qualification ☞.)

Configuration

See generic service options.

Option casts
casts
-config=CCR.EXP05,casts={TAGS, MATCHER},...

Specifies the report tags for casts.

The configuration’s content is a list of clauses specifying the casts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

MATCHER:

comma-separated sequence of cast conditions. Accepted forms are:

  • [+]AND_MATCHER: the node matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||CAST_MATCHER: either the cast matches AND_MATCHER or it matches CAST_MATCHER

  • -AND_MATCHER||CAST_MATCHER: the cast does not match AND_MATCHER but does match CAST_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the cast matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the cast matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CAST_MATCHER): the cast matches CAST_MATCHER

  • !BASIC_MATCHER: the cast does not match BASIC_MATCHER

  • any(): any cast matches

  • none(): no cast matches

  • class(CAST_CLASS): the cast class is CAST_CLASS

  • context(CONTEXT_MATCHER): the cast is in a context matching CONTEXT_MATCHER (see the -context_selector global configuration)

  • from(FROM_MATCHER): the cast whose source expression matches FROM_MATCHER

  • syntactic(FROM_MATCHER)): the cast whose syntactic source expression (i.e., after removing all non-syntactic wrappers from the source) matches FROM_MATCHER

  • kind(CAST_KIND[||CAST_KIND]*): the cast kind is one of the CAST_KIND

  • language(LANGUAGE): the language is LANGUAGE

  • to(type(TYPE_MATCHER)): the cast whose destination type is matching TYPE_MATCHER (see the -type_selector global configuration)

  • relation(RELATION[||RELATION]*): the cast satisfies one of RELATION

CAST_KIND

accepted forms are:

  • no_op: no_op

  • address_space_conversion: address_space_conversion

  • array_to_pointer_decay: array_to_pointer_decay

  • atomic_to_non_atomic: atomic_to_non_atomic

  • base_to_derived: base_to_derived

  • base_to_derived_member_pointer: base_to_derived_member_pointer

  • bitcast: bitcast

  • boolean_to_signed_integral: boolean_to_signed_integral

  • builtin_function_to_pointer_decay: builtin_function_to_pointer_decay

  • constructor_conversion: constructor_conversion

  • dependent: dependent

  • derived_to_base: derived_to_base

  • derived_to_base_member_pointer: derived_to_base_member_pointer

  • dynamic: dynamic

  • floating_cast: floating_cast

  • floating_complex_cast: floating_complex_cast

  • floating_complex_to_boolean: floating_complex_to_boolean

  • floating_complex_to_integral_complex: floating_complex_to_integral_complex

  • floating_complex_to_real: floating_complex_to_real

  • floating_real_to_complex: floating_real_to_complex

  • floating_to_boolean: floating_to_boolean

  • floating_to_integral: floating_to_integral

  • function_to_pointer_decay: function_to_pointer_decay

  • integral_cast: integral_cast

  • integral_complex_cast: integral_complex_cast

  • integral_complex_to_boolean: integral_complex_to_boolean

  • integral_complex_to_floating_complex: integral_complex_to_floating_complex

  • integral_complex_to_real: integral_complex_to_real

  • integral_real_to_complex: integral_real_to_complex

  • integral_to_boolean: integral_to_boolean

  • integral_to_floating: integral_to_floating

  • integral_to_pointer: integral_to_pointer

  • lvalue_bitcast: lvalue_bitcast

  • lvalue_to_rvalue: lvalue_to_rvalue

  • member_pointer_to_boolean: member_pointer_to_boolean

  • non_atomic_to_atomic: non_atomic_to_atomic

  • null_to_member_pointer: null_to_member_pointer

  • null_to_pointer: null_to_pointer

  • pointer_to_boolean: pointer_to_boolean

  • pointer_to_integral: pointer_to_integral

  • reinterpret_member_pointer: reinterpret_member_pointer

  • to_union: to_union

  • to_void: to_void

  • unchecked_derived_to_base: unchecked_derived_to_base

  • user_defined_conversion: user_defined_conversion

  • vector_splat: vector_splat

CAST_CLASS

accepted forms are:

  • implicit: the cast is implicit

  • explicit: the cast is explicit

  • c_style: the cast is c_style

  • functional: the cast is functional

  • const: the cast is a const named cast

  • dynamic: the cast is a dynamic named cast

  • reinterpret: the cast is a reinterpret named cast

  • static: the cast is a static named cast

RELATION

accepted forms are:

  • : bigger_sizea cast to a bigger type

  • : bigger_size_pointeea cast from a pointer to another pointer with a bigger pointee

  • cast_away_const: a cast from a pointer to a const type to a pointer without the qualifier

  • cast_away_volatile: a cast from a pointer to a volatile type to a pointer without the qualifier

  • compatible_deep_unqualified: a cast from a type to a type that has the same pointee depth and where the innermost types without qualifiers are compatible

  • definitely_changes_value: a cast that definitely does change the source expression’s value

  • definitely_in_range: a cast whose cast value is definitely in the range of its type

  • definitely_out_range: a cast whose cast value is definitely out of range of its type

  • definitely_preserves_value: a cast that definitely does not change the source expression’s value

  • derived_to_virtual_base: a cast from a pointer to a class to a pointer to a virtual base class

  • enum_constant: a cast whose source expression is an enumeration constant and whose destination type is the same as the enumerator type

  • forget_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const or is void or Boolean

  • forget_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile or is void or Boolean

  • incompatible_unqualified_pointee: a cast from a pointer to a pointer with an incompatible unqualified pointee type

  • more_aligned_pointee: a cast from a pointer to a pointer with a more aligned pointee type

  • polymorphic_base_to_derived: a cast from a pointer to a base class with polymorphic type to a pointer to a derived class

  • qualification: a cast from a pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_from_void_pointee: a cast from a void pointer to another pointer where the destination pointee has all the qualifiers in the source pointee

  • qualification_to_void_pointee: a cast from a pointer to void pointer where the destination pointee has all the qualifiers in the source pointee

  • same_type: a cast that does not change the type

  • same_unqualified_pointee: a cast from a pointer to a pointer with the same pointee type, ignoring any qualifications

  • signed_to_unsigned: a cast from a signed integral type to an unsigned integral type

  • unqualify_const_pointee: a cast from a pointer with a const pointee type to another pointer whose pointee type is not const

  • unqualify_pointee: a cast from a pointer with a pointee type qualifier to another pointer whose pointee type does not have that qualifier

  • unqualify_volatile_pointee: a cast from a pointer with a volatile pointee type to another pointer whose pointee type is not volatile

  • unqualify_atomic_pointee: a cast from a pointer with an _Atomic pointee type to another pointer whose pointee is not _Atomic

  • unsigned_to_signed: a cast from an unsigned integral type to a signed integral type

  • virtual_base_to_derived: a cast from a pointer to a virtual base class to a pointer to a derived class

FROM_MATCHER

accepted forms are:

  • type(TYPE_MATCHER): the type of the source expression matches TYPE_MATCHER (see the -type_selector global configuration)

  • expr(STMT_MATCHER): the source expression matches STMT_MATCHER (see the -stmt_selector global configuration)

LANGUAGE

accepted forms are:

  • c: C

  • cpp: C++

Rule CCR.EXP06

Summary

Operands to the sizeof operator should not contain side effects. (See https://www.securecoding.cert.org/confluence/display/seccode/EXP06-C.+Operands+to+the+sizeof+operator+should+not+contain+side+effects ☞.)

Configuration

See generic service options.

Option effects
effects
-config=CCR.EXP06,effects={TAGS, CONDS},...

Specifies the report tags for effects.

The configuration’s content is a list of report tags with a set of conditions on the effects found within the context specified by the guideline.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONDS:

the effects found in the expression and its context must match CONDS. Accepted forms are:

  • [+]AND_MATCHER: the effects matches AND_MATCHER

  • -AND_MATCHER: the effects does not match AND_MATCHER

  • [+]AND_MATCHER||CONDS: either the effects match AND_MATCHER or match EFFECT_MATCHER

  • -AND_MATCHER||CONDS: the effects do not match AND_MATCHER but do match CONDS

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the effects match BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the effects match BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (CONDS): the effects match CONDS

  • !BASIC_MATCHER: the effects do not match BASIC_MATCHER

  • any(): any effects match

  • none(): no effects match

  • count(RANGE,EFFECT_MATCHER): the context’s effects must satisfy RANGE and EFFECT_MATCHER

  • empty stringEFFECT_KIND: one of the expression’s effects must match EFFECT_KIND

EFFECT_MATCHER

accepted forms are:

  • EFFECT_MATCHER[&&EFFECT_MATCHER]*): the constraint is one of the EFFECT_MATCHER

RANGE

accepted forms are:

  • all: there can be any number of effects

  • any: there must be at least one effect

  • MIN_MAX: the number of effects must be in the range MIN_MAX

EFFECT_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the effects matches AND_MATCHER

  • -AND_MATCHER: the effects does not match AND_MATCHER

  • [+]AND_MATCHER||EFFECT_MATCHER: either the effects match AND_MATCHER or match EFFECT_MATCHER

  • -AND_MATCHER||EFFECT_MATCHER: the effects do not match AND_MATCHER but do match EFFECT_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the effects match BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the effects match BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (EFFECT_MATCHER): the effects match EFFECT_MATCHER

  • !BASIC_MATCHER: the effects do not match BASIC_MATCHER

  • any(): any effects match

  • none(): no effects match

  • EFFECT_KIND: an effect matches EFFECT_KIND

EFFECT_KIND

accepted forms are:

  • asm: an asm

  • call: a call

  • const: call with property const

  • exit: exit

  • indirect_jump: an indirect jump

  • jump: jump

  • leave: leave

  • loop: loop

  • noeffect: call with property noeffect

  • nothrow: call with property nothrow

  • pure: call with property pure

  • read: read

  • read_write: read/write

  • throw: throw

  • unevaluated: an unevaluated expression

  • volatile: reference to a volatile

  • write: write

Rule CCR.EXP09

Summary

Use sizeof to determine the size of a type or variable. (See https://www.securecoding.cert.org/confluence/display/seccode/EXP09-C.+Use+sizeof+to+determine+the+size+of+a+type+or+variable ☞.)

Configuration

See generic service options.

Option calls
calls
-config=CCR.EXP09,calls={TAGS, CALL_MATCHER},...

Specifies the report tags for calls.

The configuration’s content is a list of clauses specifying the calls and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CALL_MATCHER:

a -call_selector identifier or a matcher expression used to select the calls.

Rule CCR.EXP12

Summary

Do not ignore values returned by functions. (See https://www.securecoding.cert.org/confluence/display/seccode/EXP12-C.+Do+not+ignore+values+returned+by+functions ☞.)

Description

Notes:

  • calls to a non-void function whose return value is ignored are reported;

  • calls where the return value is cast to void are not individually reported as the explicit cast to void is taken to be a deviation request by the user.

  • all calls are included in a statistical summary for the program and the called function;

  • the summary provides:

    • the number of calls to the function,

    • the number of times the return value is ignored but this was expected,

    • the number of times the return value is cast to void and

    • the number of times it is ignored unexpectedly;

  • the selection of samples to be shown can be changed using the sample_reports service configuration.

  • the number of samples shown can be changed using the use_samples service configuration.

Configuration

See generic service options.

Option use_samples
use_samples
-config=CCR.EXP12,use_samples={TAG, MAX},...

Specify the maximum number of samples to be output.

The configuration’s content is a list of return use tags (ignored, to_void, used) with the maximum number of samples to be output; if a use tag is not specified, then all calls matching the tag will be shown as violations.

TAG:

tag indicating the return use. Accepted values are:

  • used: return value is used;

  • ignored: return value is ignored;

  • to_void: return value is cast to void;

MAX:

maximum number of samples to be shown. It must be an integer greater than or equal to -1.

Default:

-config=CCR.EXP12,use_samples={ignored, -1}, {to_void, 1}, {used, 1}
Option calls
calls
-config=CCR.EXP12,calls={TAGS, CALL_MATCHER},...

Specifies the report tags for calls.

The configuration’s content is a list of clauses specifying the calls and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CALL_MATCHER:

a -call_selector identifier or a matcher expression used to select the calls.

Option declarations
declarations
-config=CCR.EXP12,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option sample_reports
sample_reports
-config=CCR.EXP12,sample_reports={TAG, REPORT_MATCHER},...

Specifies the sample reports that should be shown/counted.

The configuration’s content is a short-circuit sequence specifying the reports to be chosen as samples.

TAG:

a short-circuit sequence for sample reports. Accepted values are:

  • hide: discard if it matches the associated conditions;

  • hate: avoid when possible if it matches the associated conditions;

  • kill: ignore if it matches the associated conditions;

  • show: show if it matches the associated conditions;

REPORT_MATCHER:

a -report_selector identifier or a matcher expression used to select the reports.

Rule CCR.EXP13

Summary

Treat relational and equality operators as if they were nonassociative. (See https://www.securecoding.cert.org/confluence/display/seccode/EXP13-C.+Treat+relational+and+equality+operators+as+if+they+were+nonassociative ☞.)

Configuration

See generic service options.

Option trusted_pairs
trusted_pairs
-config=CCR.EXP13,trusted_pairs={TAGS, PAIRS},...

Specify the tags for trusted pairs of main and child operators.

The configuration’s content is a set of tagged main and child operator pairs.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

PAIRS:

the main and child operator trusted pair. Accepted forms are:

  • OP_PAIR[||OP_PAIR]*: main and child operator pairs

OP_PAIR

accepted forms are:

  • OPERATOR_TAG1:OPERATOR_TAG2: main and child operator pair

OPERATOR_TAG

accepted forms are:

  • arrow: -> member designation operator

  • dot: . member designation operator

  • arrow_star: ->* pointer to member operator

  • dot_star: .* pointer to member operator

  • addrof: & address-of operator

  • co_await: co_await operator

  • deref: * indirection operator

  • imag: imaginary part operator

  • real: real part operator

  • plus: + unary plus operator

  • minus: - unary minus operator

  • not: ~ one’s complement operator

  • lnot: ! logical negation operator

  • post_dec: -- postfix decrement operator

  • post_inc: ++ postfix increment operator

  • pre_dec: -- prefix decrement operator

  • pre_inc: ++ prefix increment operator

  • sizeof_expr: sizeof operator

  • sizeof_type: sizeof operator

  • alignof_expr: alignof operator

  • alignof_type: alignof operator

  • vec_step_expr: vec_step operator

  • vec_step_type: vec_step operator

  • extension: extension operator

  • div: / division operator

  • mul: * multiplication operator

  • rem: % remainder operator

  • add: + addition operator

  • sub: - subtraction operator

  • shl: << left shift operator

  • shr: >> right shift operator

  • ge: >= greater-than or equal operator

  • gt: > greater-than operator

  • le: <= less-than or equal operator

  • lt: < less-than operator

  • eq: == equality operator

  • ne: != inequality operator

  • and: & bitwise AND operator

  • or: | bitwise OR operator

  • xor: ^ bitwise XOR operator

  • land: && logical AND operator

  • lor: || logical OR operator

  • conditional: ?: conditional operator

  • binary_conditional: ?: binary conditional operator

  • assign: = assignment operator

  • add_assign: += addition assignment operator

  • and_assign: &= bitwise AND assignment operator

  • div_assign: /= division assignment operator

  • mul_assign: *= multiplication assignment operator

  • or_assign: |= bitwise OR assignment operator

  • rem_assign: %= remainder assignment operator

  • shl_assign: <<= left shift assignment operator

  • shr_assign: >>= right shift assignment operator

  • sub_assign: -= subtraction assignment operator

  • xor_assign: ^= bitwise XOR assignment operator

  • throw: throw operator

  • comma: , comma operator

  • OP_COLLECTION: operator collections

OP_COLLECTION

accepted forms are:

  • multiplicative: *, / or % operator

  • additive: + or - operator

  • equality: == or != operator

  • relational: <, <=, > or >= operator

  • bitwise: ^, & or | operator

  • binary_logical: || or &&

  • logical: ||, && or ! operator

  • arithmetic: +, -, *, /, %, real or imag operator

  • assignment: =, +=, &=, /=, *=, <<=, >>=, -= or ^= operator

Rule CCR.EXP18

Summary

Do not perform assignments in selection statements. (See https://www.securecoding.cert.org/confluence/display/seccode/EXP18-C.+Do+not+perform+assignments+in+selection+statements ☞.)

Configuration

See generic service options.

Option statements
statements
-config=CCR.EXP18,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Option contexts
contexts
-config=CCR.EXP18,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Rule CCR.EXP21

Summary

Place constants on the left of equality comparisons. (See https://www.securecoding.cert.org/confluence/display/seccode/EXP21-C.+Place+constants+on+the+left+of+equality+comparisons ☞.)

Description

Reports when constants are not on the left of the equality == operator.

Configuration

See generic service options.

Option statements
statements
-config=CCR.EXP21,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Option contexts
contexts
-config=CCR.EXP21,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Rule CCR.FIO07

Summary

Prefer fseek() to rewind(). (See https://www.securecoding.cert.org/confluence/display/seccode/FIO07-C.+Prefer+fseek%28%29+to+rewind%28%29 ☞.)

Configuration

See generic service options.

Option declarations
declarations
-config=CCR.FIO07,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CCR.FIO12

Summary

Prefer setvbuf() to setbuf(). (See https://www.securecoding.cert.org/confluence/display/seccode/FIO12-C.+Prefer+setvbuf%28%29+to+setbuf%28%29 ☞.)

Configuration

See generic service options.

Option declarations
declarations
-config=CCR.FIO12,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CCR.FLP00

Summary

Understand the limitations of floating point numbers. (See https://www.securecoding.cert.org/confluence/display/seccode/FLP00-C.+Understand+the+limitations+of+floating+point+numbers ☞.)

Description

Floating-point expressions must not be tested for equality.

Exceptions

Note that comparison with 0.0 can be exempted using the statements service configuration.

Implementation

Floating-point expressions are non-compliant if they are used:

  1. as operands f1 and f2 in explicit equality and inequality comparisons f1 == f2 and f1 != f2;

  2. as arguments to boolean operators &&, || or !;

  3. as the conditions for if, for, do, and while statements;

  4. in indirect tests for equality for floating point expressions (f1 op1 f2) && (f3 op2 f4), where op1 and op2 are relational operators <=, >=, < or > and either op1 is the inverse of op2, the expressions f1 and f3 are equivalent, and the expressions f2, f4 are equivalent, or op1 and op2 are the same, the expressions f1, f4 are equivalent and the expressions f2, f3 are equivalent.

Note that in item 4, for this rule, expressions e1, e2 are taken to be equivalent, if, after dropping any parentheses and unary + operators:

  • they are the same variable or literal;

  • have the same operator and have equivalent arguments;

  • have the forms f1 op f2 and f3 op f4 where op is a non-assignment binary operator, the expressions f1, f3 are equivalent and the expressions f2, f4 are equivalent or op is one of the commuting operators + or * and the expressions f1, f4 are equivalent and the expressions f2, f3 are equivalent.

Imprecision

False negatives are present because recognising indirect equality and inequality tests is undecidable.

For example, the following function, depending on the definition of g() might or might not test the equality of x and y:

float* p;
int f(float x, float y) {
  if (x < y)
    return 0;
  *p = y;
  g();
  if (-*p < -y)
    return 0;
  return 1;
}

Said that, the rule captures most (if not all) reasonable ways in which a programmer in good-faith (i.e., not deliberately attempting to break the rule) might code an equality/inequality test on floating-point expressions.

Configuration

See generic service options.

Option statements
statements
-config=CCR.FLP00,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Rule CCR.INT02

Summary

Understand integer conversion rules. (See https://www.securecoding.cert.org/confluence/display/seccode/INT02-C.+Understand+integer+conversion+rules ☞.)

Description

Reports:

  • implicit sign conversions for integral operands of arithmetic (and logical) operators;

  • implicit narrowing conversions for integral operands;

  • the use of unary - when the type of the operand is unsigned;

  • when the result of applying operators ~ and << to an operand having type unsigned char or unsigned short is not immediately cast back to the type of the operand.

Configuration

See generic service options.

Option etypes
etypes
-config=CCR.INT02,etypes={TAGS, NODE_MATCHER, ETYPE_MATCHER},...

Specifies the report tags for essential types.

The configuration’s content is a list of clauses specifying the nodes, the essential types and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

NODE_MATCHER:

an expression, declaration or type whose child is an expression with a type to be checked. Accepted forms are:

  • [+]AND_MATCHER: the node matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||NODE_MATCHER: either the node matches AND_MATCHER or it matches NODE_MATCHER

  • -AND_MATCHER||NODE_MATCHER: the node does not match AND_MATCHER but does match NODE_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the node matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the node matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (NODE_MATCHER): the node matches NODE_MATCHER

  • !BASIC_MATCHER: the node does not match BASIC_MATCHER

  • any(): any node matches

  • none(): no node matches

  • implicit(): the context uses an implicit conversion

  • member_initializer(): the context node is a member initializer

  • decl(DECL_MATCHER): the context node is a declaration matching DECL_MATCHER (see the -decl_selector global configuration)

  • type(TYPE_MATCHER): the context node is a type matching TYPE_MATCHER (see the -type_selector global configuration)

  • stmt(STMT_MATCHER): the context node is an expression or statement matching STMT_MATCHER (see the -stmt_selector global configuration)

ETYPE_MATCHER:

an expression defining the etype conditions. Accepted forms are:

  • [+]AND_MATCHER: the etype matches AND_MATCHER

  • -AND_MATCHER: the etype does not match AND_MATCHER

  • [+]AND_MATCHER||ETYPE_MATCHER: either the etype matches AND_MATCHER or it matches ETYPE_MATCHER

  • -AND_MATCHER||ETYPE_MATCHER: the etype does not match AND_MATCHER but does match ETYPE_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the etype matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the etype matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (ETYPE_MATCHER): the etype matches ETYPE_MATCHER

  • !BASIC_MATCHER: the etype does not match BASIC_MATCHER

  • any(): any etype matches

  • none(): no etype matches

  • 01_to_boolean(): source expression is evaluatable integer that evaluates to 0 or 1 and destination type is a Boolean

  • child(ETYPE_CHILDS): the child kind

  • dst_type(ETYPE_CONDS): the destination type conditions

  • src_type(ETYPE_CONDS): the source type conditions

  • src_expr(EXPR_CONDS): the source expression conditions

  • different_category(): the source and destination types are in different categories (which are any of [boolean, character, floating, signed, unsigned, enum, nullptr, other or void])

  • init_list_0(): the source expression is an initializer list that is a singleton with value 0

  • narrow(): the width of the destination type is less than that of the source type

  • sibling(ETYPE_CHILD,SIBLING_CONDS): the source expression has a sibling with child kind ETYPE_CHILD that satisfies one of the SIBLING_CONDSs

  • preserved_integer_constant(): the source is an integer constant expression and the destination essential type is an integer type that can represent its value

  • compatible(): the destination type is not void and the source and destination types are compatible

  • wider(): the width of the destination type is more than that of the source type

ETYPE_CHILDS

accepted forms are:

  • ETYPE_CHILD[||ETYPE_CHILD]*: the child conditions

ETYPE_CHILD

accepted forms are:

  • cond: condition

  • common: common child of a binary_conditional_operator

  • then: then child of a binary_conditional_operator or conditional_operator

  • else: else child of a binary_conditional_operator or conditional_operator

  • lhs: left-hand operand

  • rhs: right-hand operand

  • subscript: subscript expression

EXPR_CONDS

accepted forms are:

  • EXPR_COND[||EXPR_COND]*: the expression conditions

EXPR_COND

accepted forms are:

  • STMT_MATCHER: the expression matches STMT_MATCHER (see the -stmt_selector global configuration)

  • mc2_complex: source expression is complex (see page 49 of MISRA-C:2004 [62] ☞, Section 6.10.5)

  • mc3_composite: source expression is composite (see page 98 of MISRA C:2012 [43] ☞, Section 8.10.3)

  • mp1_cvalue: source expression is a cvalue (see page 66 of MISRA C++:2008 [64] ☞, Section 6)

ETYPE_CONDS

accepted forms are:

  • ETYPE_COND[||ETYPE_COND]*: the essential type conditions

ETYPE_COND

accepted forms are:

  • any_boolean: type is Boolean or essentially Boolean (see page 204 MISRA C:2012 [43] ☞, Section 8.10)

  • boolean: type is Boolean

  • complete_object_pointee: type is a non-function pointer to a complete type

  • character: type is a character

  • ebool: type is essentially Boolean (see page 204 MISRA C:2012 [43] ☞, Section 8.10)

  • enum: type is an enumerator

  • floating: type is a floating point

  • incompatible: destination type is the balancing of incompatible types

  • integer: type is integral

  • !ETYPE_CONDS: type does not satisfy ETYPE_CONDS

  • number: type is numeric

  • other: type is not a boolean, signed or unsigned integer, floating point, enumerator or character

  • signed: type is signed integral

  • signed_char: type is signed char

  • signed_small: type is signed with rank less than or equal to int

  • unsigned: type is unsigned integral

  • unsigned_char: type is unsigned char

  • void: type is void

SIBLING_MATCHER

accepted forms are:

  • [+]AND_MATCHER: the sibling matches AND_MATCHER

  • -AND_MATCHER: the node does not match AND_MATCHER

  • [+]AND_MATCHER||SIBLING_MATCHER: either the sibling matches AND_MATCHER or it matches SIBLING_MATCHER

  • -AND_MATCHER||SIBLING_MATCHER: the sibling does not match AND_MATCHER but does match SIBLING_MATCHER

AND_MATCHER

accepted forms are:

  • BASIC_MATCHER: the sibling matches BASIC_MATCHER

  • BASIC_MATCHER&&AND_MATCHER: the sibling matches BASIC_MATCHER and AND_MATCHER

BASIC_MATCHER

accepted forms are:

  • (SIBLING_MATCHER): the sibling matches SIBLING_MATCHER

  • !BASIC_MATCHER: the sibling does not match BASIC_MATCHER

  • any(): any sibling matches

  • none(): no sibling matches

  • type(ETYPE_CONDS): sibling type satisfies ETYPE_CONDS

  • expr(EXPR_CONDS): sibling expression satisfies EXPR_CONDS

  • different_category(): sibling is in a different category

Rule CCR.INT07

Summary

Use only explicitly signed or unsigned char type for numeric values. (See https://www.securecoding.cert.org/confluence/display/seccode/INT07-C.+Use+only+explicitly+signed+or+unsigned+char+type+for+numeric+values ☞.)

Configuration

See generic service options.

Option calls
calls
-config=CCR.INT07,calls={TAGS, CALL_MATCHER},...

Specifies the report tags for calls.

The configuration’s content is a list of clauses specifying the calls and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CALL_MATCHER:

a -call_selector identifier or a matcher expression used to select the calls.

Rule CCR.INT09

Summary

Ensure enumeration constants map to unique values. (See https://www.securecoding.cert.org/confluence/display/seccode/INT09-C.+Ensure+enumeration+constants+map+to+unique+values ☞.)

Configuration

See generic service options.

Option declarations
declarations
-config=CCR.INT09,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CCR.INT12

Summary

Do not make assumptions about the type of a plain int bit-field when used in an expression. (See https://www.securecoding.cert.org/confluence/display/seccode/INT12-C.+Do+not+make+assumptions+about+the+type+of+a+plain+int+bit-field+when+used+in+an+expression ☞.)

Description

Note that, for this service, the report category is the reported type.

Configuration

See generic service options.

Option declarations
declarations
-config=CCR.INT12,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Option types
types
-config=CCR.INT12,types={TAGS, TYPE_MATCHER},...

Specifies the report tags for types.

The configuration’s content is a list of clauses specifying the types and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

TYPE_MATCHER:

a -type_selector identifier or a matcher expression used to select types.

Rule CCR.INT13

Summary

Use bitwise operators only on unsigned operands. (See https://www.securecoding.cert.org/confluence/display/seccode/INT13-C.+Use+bitwise+operators+only+on+unsigned+operands ☞.)

Configuration

See generic service options.

Option statements
statements
-config=CCR.INT13,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Option contexts
contexts
-config=CCR.INT13,contexts={TAGS, CONTEXT_MATCHER},...

Specifies the report tags for contexts.

The configuration’s content is a list of clauses specifying the contexts and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CONTEXT_MATCHER:

a -context_selector identifier or a matcher expression used to select the contexts.

Rule CCR.MEM02

Summary

Immediately cast the result of a memory allocation function call into a pointer to the allocated type. (See https://www.securecoding.cert.org/confluence/display/seccode/MEM02-C.+Immediately+cast+the+result+of+a+memory+allocation+function+call+into+a+pointer+to+the+allocated+type ☞.)

Configuration

See generic service options.

Option calls
calls
-config=CCR.MEM02,calls={TAGS, CALL_MATCHER},...

Specifies the report tags for calls.

The configuration’s content is a list of clauses specifying the calls and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CALL_MATCHER:

a -call_selector identifier or a matcher expression used to select the calls.

Rule CCR.MEM08

Summary

Use realloc() only to resize dynamically allocated arrays. (See https://www.securecoding.cert.org/confluence/display/seccode/MEM08-C.+Use+realloc%28%29+only+to+resize+dynamically+allocated+arrays ☞.)

Configuration

See generic service options.

Option calls
calls
-config=CCR.MEM08,calls={TAGS, CALL_MATCHER},...

Specifies the report tags for calls.

The configuration’s content is a list of clauses specifying the calls and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

CALL_MATCHER:

a -call_selector identifier or a matcher expression used to select the calls.

Rule CCR.MSC00

Summary

Compile cleanly at high warning levels. (See https://www.securecoding.cert.org/confluence/display/seccode/MSC00-C.+Compile+cleanly+at+high+warning+levels ☞.)

Configuration

See generic service options.

Option hidden_options
hidden_options
-config=CCR.MSC00,hidden_options={TAGS, TOOL, {OPTION_MATCHER,...}},...

Specify tags for command lines that match the option selectors.

The configuration’s content is list of tagged option matchers.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

TOOL:

tool kind. Accepted values are:

  • compiler: compiler tool;

  • linker: linker tool;

OPTION_MATCHER:

option matcher string. Accepted forms are:

  • ^REGEX$: option matches ^REGEX$

  • !OPTION_MATCHER: option does not match OPTION_MATCHER

  • ID: option matches one of the patterns listed in ecl variable ID (a name beginning with a letter)

  • TEXT: option matches string TEXT

REGEX

accepted forms are:

Rule CCR.MSC01

Summary

Strive for logical completeness. (See https://www.securecoding.cert.org/confluence/display/seccode/MSC01-C.+Strive+for+logical+completeness ☞.)

Configuration

See generic service options.

Option else_empty
else_empty
-config=CCR.MSC01,else_empty={EMPTY_ELSE, COMMENT_MATCHER},...

Specify what is meant by an empty else clause and whether a comment can be used instead.

The configuration’s content is a set of pairs indicating the intended meaning for empty else and an optional matcher for a replacement comment.

EMPTY_ELSE:

choose what is meant by empty else. Accepted values are:

  • null: the else clause contains just a null statement and any comment must be immediately after the null statement;

  • empty_compound: the else clause contains just an empty block statement and any comment must be in the block or immediately after the block statement;

  • no_effect: the else clause contains a block statement with code that has no effect and any comment must be in the block or immediately after the block statement;

  • missing: there is no else clause and any comment must be immediately after the else if statement;

COMMENT_MATCHER:

no comment, indicating that comments are ignored or a -comment_selector identifier or a matcher expression used to select the comments.

Default:

-config=CCR.MSC01,else_empty={missing, "none()"}, {null, "none()"}, {empty_compound, "any()"}
Option ignored_comments
ignored_comments
-config=CCR.MSC01,ignored_comments=COMMENT_MATCHER,...

Specify the comments that should be ignored.

The configuration’s content is a list of comment matchers.

COMMENT_MATCHER:

a -comment_selector identifier or a matcher expression used to select the comments.

Option declarations
declarations
-config=CCR.MSC01,declarations={TAGS, DECL_MATCHER},...

Specifies the report tags for declarations.

The configuration’s content is a list of clauses specifying the declarations and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

DECL_MATCHER:

a -decl_selector identifier or a matcher expression used to select the declarations.

Rule CCR.MSC04

Summary

Use comments consistently and in a readable fashion. (See https://www.securecoding.cert.org/confluence/display/seccode/MSC04-C.+Use+comments+consistently+and+in+a+readable+fashion ☞.)

Configuration

See generic service options.

Option code_lines
code_lines
-config=CCR.MSC04,code_lines=LINES

Specify the minimum number of consecutive (non-blank) lines of commented code; set the value to 0, if no check on the number of lines is needed.

LINES:

minimum number of consecutive (non-blank) lines of commented code (note that blank lines in the code block, possibly in a comment, are ignored); if the value is 0, then there is no check on the number of lines. It must be an integer greater than or equal to 0.

Default:

-config=CCR.MSC04,code_lines=0
Option comments
comments
-config=CCR.MSC04,comments={TAGS, COMMENT_MATCHER},...

Specifies the report tags for comments.

The configuration’s content is a list of clauses specifying the comments and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

COMMENT_MATCHER:

a -comment_selector identifier or a matcher expression used to select the comments.

Option ignored_comments
ignored_comments
-config=CCR.MSC04,ignored_comments=COMMENT_MATCHER,...

Specify the comments that should be ignored.

The configuration’s content is a list of comment matchers.

COMMENT_MATCHER:

a -comment_selector identifier or a matcher expression used to select the comments.

Default:

-config=CCR.MSC04,ignored_comments=__doxygen_comments

Rule CCR.MSC05

Summary

Do not manipulate time_t typed values directly. (See https://www.securecoding.cert.org/confluence/display/seccode/MSC05-C.+Do+not+manipulate+time_t+typed+values+directly ☞.)

Configuration

See generic service options.

Option statements
statements
-config=CCR.MSC05,statements={TAGS, STMT_MATCHER},...

Specifies the report tags for statements.

The configuration’s content is a list of clauses specifying the statements and related report tags.

TAGS:

a possibly empty sequence of report tags separated by +. Notes:

  • A report tag or rtag can have one of two forms:

    • Domain:Tag_Name where Domain is a tag domain and Tag_Name is a tag in Domain,

    • Tag_Name where Tag_Name is a tag in the domain tag;

  • the tag missing is reserved as a default tag; a report that has no specified tag in a domain Domain is given the tag missing for Domain;

  • if the special tag hide (after any remapping) is applicable to a report, then that report will be hidden;

  • tags (including hide) can be remapped to other tags using the -remap_rtag global configuration.

STMT_MATCHER:

a -stmt_selector identifier or a matcher expression used to select the expressions or the statements.

Option contexts
contexts
-config=CCR.MSC05,contexts={TAGS, CONTEXT_MATCHER