CodeSonar C++ API

Table of Contents

• Getting Started
  • Using the C++ API
  • Example
• Exceptions
• Links

The C++ API for CodeSonar is provided within the cs namespace.
Visit the cs Namespace Reference page for an index of classes and typedefs.

Getting Started

See Writing C++ Plug-Ins For CodeSonar for information about writing and building a C++ plug-in.

Users who have previously used the C API and are considering switching to the C++ API may also wish to read Comparison: C++ API vs C API.

Using the C++ API

To use the C++ API, include csonar_api.hpp and use the 'cs' namespace.

The C++ API has the same link-time dependencies as the C API. The entire C++ API is implemented in header files that wrap the C API, in order to avoid any C++ linkage. This ensures compatibility with many compiler toolchains.

However, the C++ API does use some global variables. In order to get definitions for these globals, place this at the beginning of one C++ file in your plug-in:

#define CS_CPP_IMPL
#include "csonar_api.hpp"

Having CS_CPP_IMPL defined will cause all global variables in the API to be defined by that compilation unit. This is necessary to avoid undefined symbol errors when linking.

Example

The following simple plug-in reimplements the "Goto Statement" warning class. It flags all goto statements. It calls the warning "Use of Goto".

// make sure csonar_api.hpp defines all global variables (as opposed
// to merely declaring them). 
#define CS_CPP_IMPL
 
// Include the entire CodeSonar C++ API
#include "csonar_api.hpp"
 
// for std::cout
#include <iostream>
 
// Define a new warning class
static cs::warningclass use_of_goto = cs::analysis::create_warningclass("Use of goto");
 
// Create a program point visitor that detects goto statements.
class my_point_visitor : public cs::visitor<cs::point>
{
    // CodeSonar will invoke this function on every program point in
    // the program.
    void operator()(cs::point p)
    {
        // Most API functions can throw cs::result.  Use a try/catch
        // if you prefer soft failure to the hard crash of an uncaught
        // exception.
        try{
 
            // This will print to the analysis log page of the hub,
            // unless running in foreground mode, in which case it
            // will print to stdout.  Very handy for debugging.
            std::cout << "Visiting " << p << std::endl;
            
            // If it is a goto statement, then report a warning at
            // this program point
            if( p.get_syntax_kind() == cs::point_syntax_kind::GOTO )
                use_of_goto.report(p, "Goto was used here");
        } catch( const cs::result &r ) {
            std::cout << "*** my_point_visitor exception: " << r << std::endl;
        }
    }
};
 
// Construct an instance of our visitor class.  CodeSonar takes
// possession of the visitor, and invokes it on every program point.
// We could just as well do this inside cs_plug_main, but it is
// often more convenient to do it near the visitor class definition.
static char dummy = (cs::analysis::add_point_visitor(new my_point_visitor()), 0);
 
// Runs when the plug-in loads, but doesn't need to do anything for
// this plug-in.
static void cs_plug_main(void){}
 
// my_plugin must be the basename of the .dll/.so/.bundle file
CS_DEFINE_PLUGIN(my_plugin)

Exceptions

Most methods in the C++ API potentially throw a cs::result. CodeSonar does not catch uncaught exceptions – the C++ runtime will call std::terminate() and abort if you do not use a try/catch construct to catch the exception.

Uncaught exceptions are one of the most common causes of crashes when using the C++ API.

If you wish to compile your plug-in without support for unwinding exceptions, define the CS_CPP_NO_EXCEPTIONS preprocessor symbol. This will prevent the API from catching any exceptions internally; all exceptions will become fatal errors. This configuration can be very challenging.

Links

• cs Namespace Reference: index of C++ API classes and typedefs.
• Writing C++ Plug-Ins For CodeSonar: information about writing and building a C++ plug-in.
• Plug-In API Tutorial: annotated example plug-ins in C++ and the other supported API languages, including step-by-step instructions for building and testing.