JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
C and C++
Binaries

Implementing and Including Custom Checks with the Extension API

This section describes two methods for implementing new CodeSonar checks using the Extension API and insert these checks into a project.

Overview

New CodeSonar checks can be implemented using the Extension API. CodeSonar provides two alternatives for users wishing to insert these checks into a project: inserting new code directly into the program file, or writing a special code wrapper in a separate file linked into the CodeSonar project. Each method has both advantages and disadvantages, as shown in the following table.

[Method I] Insert a few lines of code directly into the program.
PRO There is always a reminder in the source code that a check is taking place.
CON The original code must be modified.
[Method II] Write a special code wrapper in a separate file, and link this file into the CodeSonar project but not into real builds.
PRO Easy reuse.
CON More files to manage.

To illustrate the use of these two mechanisms, suppose you have two procedures foo() and bar(), and that procedure bar() should not be called while foo() is active

int foo()
{
/* start work */
}
void bar()
{
/* should not be called while foo() is working */
}

[Method I] Add lines to original code

If the project is built using these modified versions of foo() and bar(), then CodeSonar will detect and report calls to bar() while foo() is active.

  1. Add #include <stdlib.h> and #include "csonar.h" directives to the source file, and implement the check using the Extension API. We recommend using #ifdef __CODESONAR__ ... #endif to enclose these parts of the program. 
    #ifdef __CODESONAR__
#include <stdlib.h>
#include "csonar.h"
#endif
        
static int foo_is_executing = 0;

int foo(void){
    foo_is_executing = 1; 
    ... 
    return 42;
}

void bar(void){
    #ifdef __CODESONAR__

    csonar_trigger(foo_is_executing, "==", 1, "bar should never be called while foo is active" );

    #endif
}
  2. Add the following rule to the general project configuration file. 
    EDG_FRONTEND_OPTIONS_APPEND += -Icsonar_libmodels_path
    where csonar_libmodels_path is the path to the codesonar/libmodels subdirectory of the CodeSonar installation directory. The example command lines below provide some examples of suitable -I settings.

The behavior of csonar_trigger is described in the CodeSonar Extension API Functions and Macros section.

[Method II] Use a special code wrapper

It is often desirable to implement a check without modifying existing code. To support this, CodeSonar provides a feature whereby any function p can be intercepted by a function called csonar_replace_p.

The following steps explain how to add a custom check to project MyProj.

  1. Create a new file called (for example) check_foo_bar.c. 
    /* file check_foo_bar.c */

#include <stdlib.h>
#include "csonar.h"
static int foo_is_executing = 0;
        
int csonar_replace_foo(void){
    int rv;
    foo_is_executing = 1;
    rv = foo();
    return rv;
}

void csonar_replace_bar(void){
    csonar_trigger(foo_is_executing, "==", 1, "bar should never be called while foo is active" );
    bar();
}

    CodeSonar will pretend that calls to foo() and bar() are actually calls to csonar_replace_foo() and csonar_replace_bar() because of the way the replacement functions are named.

  2. Add the following rule to the general project configuration file. 
    EDG_FRONTEND_OPTIONS_APPEND += -Icsonar_libmodels_path
    where csonar_libmodels_path is the path to the codesonar/libmodels subdirectory of the CodeSonar installation directory. Some example command lines are shown below.
  3. Use codesonar build to observe the compilation of check_foo_bar.c and add a corresponding CodeSonar representation to MyProj.
    codesonar build MyProj host:port compiler_command include_libmodels options check_foo_bar.c
    where:
    host:port is the hub location.
    compiler_command is the command for invoking your compiler.
    Example: gcc
    include_libmodels is the compiler option setting required to include the codesonar/libmodels subdirectory of your CodeSonar installation.
    Example: -I/path/to/codesonar/libmodels
    options are any compilation options that might be required. In general, these should be similar to those used for the rest of the project, including any preprocessor-related options that might be required for compatibility.
    Example (for gcc and similar compilers): -c
    For example, with gcc and a hub located at alex:7340:
    codesonar build
    MyProj alex:7340 gcc -I/path/to/codesonar/libmodels -c check_foo_bar.c
  4. Build and analyze the remainder of MyProj.

If you are automatically invoking the CodeSonar analysis as part of your build, it will usually make sense to edit the build to include the generation of CodeSonar representation for check_foo_bar.c. There are two possible approaches:

Example Command Lines

The following examples add the custom checks in file codesonar_custom_check_file.c to project MyProj, using the hub at alex:7340.

 

To report problems with this documentation, please visit https://support.codesecure.com/.