Plug-In Tutorial: C Version

• Preliminaries
• Part One
• Part Two

Preliminaries

It is important to build your plug-in with the same pointer width as that of your CodeSonar installation. Otherwise, the plug-in build will fail and report errors in cs_basic_types.h.

• If you are not sure whether you are using 32-bit or 64-bit CodeSonar, look at the "Host Platform" line in $CSONAR/SIGNATURE.txt.
• We provide command lines for some common cases below; in other cases you will need to consult your compiler documentation.

Part One

The plug-in for Part One implements a check for variable names containing upper case characters. There are three important elements in the plug-in:

• Creating a new warning class for the warnings that will be issued when variables contain upper case characters.
• Defining a function that takes a symbol (ABS_LOC) and, if it corresponds to a user-defined variable, checks the case of the characters in the variable name.
• Attaching that function to the visitor list for variable symbols.

• UCvar_plugin.c
• Preliminaries
• Build
• Install
• Exercise
• Clean Up

UCvar_plugin.c

Parts of file UCvar_plugin.c are reproduced below.

• Select any header file name to see the documentation for that file.
• Select any API function name to see the documentation for that function.

  
/*
 *      Copyright (c) 2023, an unpublished work by CodeSecure, Inc.
 *                      ALL RIGHTS RESERVED
 *
 *      Copyright (c) 2007-2023, an unpublished work by GrammaTech, Inc.
 *                      ALL RIGHTS RESERVED
 *
 *      This software is furnished under a license and may be used and
 *      copied only in accordance with the terms of such license and the
 *      inclusion of the above copyright notice.  This software or any
 *      other copies thereof may not be provided or otherwise made
 *      available to any other person.  Title to and ownership of the
 *      software is retained by CodeSecure, Inc.
 */

/* UCvar_plugin.c
 *
 * a small example plugin that reports declarations for variables
 * whose names contain upper case characters
 */

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>


/* All C plug-ins for CodeSonar must include this file. */

#include "csonar_plugin.h"

/* This plug-in accesses various parts of the internal representation
 * (IR), so the relevant API headers must be included. */

#include "cs_pdg_vertex.h"
#include "cs_abs_loc.h"
#include "cs_pdg.h"
#include "cs_utility.h"
#include "cs_source_files.h"

/* upvar is a new \warning class \ defined by this plug-in. It must be created in
 * a setup visitor. */

static cs_warningclass_t upvar;


/* helper function for check_var_case
 *
 * returns 1 if instr contains an upper case character
 * (or a bad-valued character, although this should never happen)
 * 0 otherwise
 */
static int has_upper_char(cs_string instr, cs_size_t sz)
{
    cs_size_t i;
    for (i=0; i<sz; i++)
    {
        if (isupper((unsigned char) instr[i])) return 1;
    }
    return 0;
}


/* Visitors should be at the finest granularity that is appropriate
 * for the check. This plug-in is checking a property of variable
 * names, so we define a visitor that operates on variable ABS_LOCs. */

static void check_var_case(cs_abs_loc sym, void *ctx)
{
    cs_string varname;
    cs_size_t namesize,ns;
    char * buf;
    cs_abs_loc_kind varkind;

    /* We are only interested in user-defined variables. */
    if ( cs_abs_loc_get_kind(sym, &varkind) != CS_SUCCESS ) return;
    if ( varkind != cs_abs_loc_kind_user) return;
    
    /* Retrieving the variable name is a three-step process.
     *
     * 1. Call cs_abs_loc_name() with NULL and 0 as the second and
     * third parameters, respectively, in order to set namesize to the
     * length of the name (+1). This call should return CS_TRUNCATED,
     * since a variable name should not be able to fit into a 0-byte
     * space.
     *
     * 2. Allocate space for the varname according to the value of
     * namesize.
     *
     * 3. Call cs_abs_loc_name() again to set varname to the variable
     * name.
     */
    if ( cs_abs_loc_name(sym,NULL,0,&namesize) == CS_TRUNCATED)
    {
        varname = malloc(namesize * sizeof(char));

        /* Check that malloc() didn't fail. */
        if( !varname )         
            abort();
        if ( cs_abs_loc_name(sym,varname,namesize,&ns) 
             == CS_SUCCESS)
        {
            /* If an upper case character is found, and the variable
             * is declared in user code, issue a warning and return.*/
            if ( has_upper_char(varname, namesize) )
            {
                cs_sfid sfid;
                cs_line line;
                cs_result r;

                r = cs_abs_loc_file_line( sym, &sfid, &line );

                /* ... and if the variable is declared at some
                 * location in the source code... */
                if ( r == CS_SUCCESS )
                {
                    char filename[1024];
                    cs_size_t filename_sz;

                    /* ... and that location is not in a library...*/  
                    r = cs_file_get_include_name( sfid, 
                                                  filename, 
                                                  sizeof(filename), 
                                                  &filename_sz );
                    if( r != CS_TRUNCATED && r != CS_SUCCESS )
                        abort();

                    if( strstr( filename, "/libmodels/" )
                        || strstr( filename, "\\\\libmodels\\\\" )
                        || strstr( filename, "/smel/" )
                        || strstr( filename, "\\\\smel\\\\" ) )
                    {
                        free(varname);
                        return;
                    }
                    /* ... then construct and issue a warning.*/
                    buf = malloc(namesize + strlen("variable name %s has upper case character"));
                    if( !buf )
                        abort();
                    sprintf( buf,    
                             "variable name %s has upper case character",
                             varname );
                    csonar_report_location_warning( sfid, 
                                                    line, 
                                                    upvar, 
                                                    buf,
                                                    csrf_none,
                                                    NULL,
                                                    NULL);
                    free(buf);
                } 
                free(varname);
                return;
            } 
        } 
        free(varname);
    }
}


/* The plug-in defines a new warning class to go with its new
 * check. We do not associate any \CodeSonar mnemonics \ or
 * \CWE identifiers  \ with the new class, as none are appropriate.
 * The new warning class must be created with
 * csonar_create_warningclass(), which must be called from a setup
 * visitor.*/

static void setup(void *ctx)
{
    upvar = csonar_create_warningclass(
            "Variable name has upper case characters",
            "",
            1.0,
            csonar_bcf_padding,
            csws_style );
}


/* Every C plug-in for CodeSonar must define this function,
 * which must contain all the calls to csonar_add_*_visitor() and
 * csonar_create_warningclass() required for the plug-in. */

static void cs_plug_main(void)
{
    csonar_add_setup_visitor(NULL, setup, NULL);

    /* check_var_case() must be added as an ABS_LOC visitor inside
     * cs_plug_main() in order for CodeSonar to add it to the
     * visitor list. */
    csonar_add_abs_loc_visitor(NULL, check_var_case, NULL);
}

/* All CodeSonar C plug-ins require a line of this form at the
 * top level. Note that the argument to CS_DEFINE_PLUGIN corresponds
 * to the name of the compiled plug-in (which will be either
 * UCvar_plugin.dll or UCvar_plugin.so, depending on your system).*/

CS_DEFINE_PLUGIN(UCvar_plugin)

  

Build

Build the plug-in into a library.

• Choose the appropriate command line from the following table. Compilation instructions vary slightly depending on your operating system.
  • Windows
  • All other systems

  	Compiler	Command Line	Notes
  Windows
  	cl	cl /LD /MD "/I%CSONAR%\codesonar\include" "/I%CSONAR%\csurf\include" UCvar_plugin.c "%CSONAR%\codesonar\lib\codesonar.lib"	If you are using 64-bit CodeSonar, use 64-bit cl (see How to: Enable a 64-Bit Visual C++ Toolset on the Command Line).
  	Cygwin gcc	Note: Cygwin gcc is only suitable for building 32-bit CodeSonar plugins. Cygwin gcc only builds Cygwin binaries, so is not suitable for building 64-bit CodeSonar plug-ins. If you do not have an alternative gcc, you will need to download and install one. One option is mingw-w64. Cygwin 1.7 Use the gcc-3 executable (not gcc / gcc4, which does not support -mno-cygwin). If you do not have a gcc-3 binary, use Cygwin's setup.exe tool to install the mingw-gcc component. gcc-3 -shared -mno-cygwin "-I$CSONAR/codesonar/include" "-I$CSONAR/csurf/include" UCvar_plugin.c -o UCvar_plugin.dll "-L$CSONAR/codesonar/lib" -lcodesonar Cygwin 1.5 gcc -shared -mno-cygwin "-I$CSONAR/codesonar/include" "-I$CSONAR/csurf/include" UCvar_plugin.c -o UCvar_plugin.dll "-L$CSONAR/codesonar/lib" -lcodesonar	If you are using 32-bit CodeSonar on a 64-bit platform, add the -m32 flag to the command line (unless your compiler version will not accept it).
  	MinGW gcc	gcc -shared "-I$CSONAR\codesonar\include" "-I$CSONAR\csurf\include" UCvar_plugin.c -o UCvar_plugin.dll "-L$CSONAR\codesonar\lib" -lcodesonar	If you are using 64-bit CodeSonar, use 64-bit MinGW gcc. Note that, depending on your system configuration, this may not be the version invoked by the 'gcc' command - in this case you will need to either adjust your environment or use a different name to invoke the correct compiler. If you are using 32-bit CodeSonar on a 64-bit platform, add the -m32 flag to the command line (unless your gcc version will not accept it).
  All Other Systems We provide a full example for gcc. For other compilers, build UCvar_plugin.so from UCvar_plugin.c, including $CSONAR/codesonar/include and $CSONAR/csurf/include.
  	gcc	gcc -fPIC -shared -o UCvar_plugin.so UCvar_plugin.c -I$CSONAR/codesonar/include -I$CSONAR/csurf/include	If you are using 32-bit CodeSonar on a 64-bit platform, add the -m32 flag to the command line (unless it causes problems).

See Writing C Plug-Ins For CodeSonar for further compilation details and troubleshooting hints.

Install

Install the plug-in:

• Copy or move your compiled plug-in (UCvar_plugin.dll, UCvar_plugin.so, or UCvar_plugin.bundle) to directory
  $CSONAR/codesonar/plugins/
  (If you don't have access to this directory, use the PLUGINS configuration file option to specify the file path for your compiled plug-in.)

Exercise

We have provided an extremely short example program to exercise the plug-in. You can also try building other programs into CodeSonar projects to see how many variables they contain whose names include upper case letters.

• Build testvar.c into a CodeSonar project. Your exact build command will, as always, depend on your local build tools and on the hub location (host:port). In many cases, one of the following will suffice:

  with cl:	codesonar analyze testvar host:port cl /c testvar.c
  with gcc:	codesonar analyze testvar host:port gcc -c testvar.c

  See Building Projects (Command Line) or Building Projects (Windows Build Wizard) for more information about building a CodeSonar project.
• Look at the analysis results to see where the warnings are issued and what the warning reports look like.

  Note that procedure names are not associated with the warnings. This is because we issued the warnings with csonar_report_location_warning, which does not report a procedure name (because, among other reasons, a line may contain multiple procedures).

Clean Up

If you don't want to be warned in future about variable names containing upper case letters:

• Remove the compiled plug-in (UCvar_plugin.dll, UCvar_plugin.so, or UCvar_plugin.bundle) from $CSONAR/codesonar/plugins/

  (If you used an alternative location, remove the associated PLUGINS configuration file setting).

Part Two

The plug-in for Part Two implements a check for mismatched parentheses in the output of a program. This involves setting up a step visitor to ensure that the control-flow paths in the program involve properly balanced calls to the procedures that write opening and closing parentheses.

• callseq_plugin.c
• Build
• Install
• Exercise
• Clean Up

callseq_plugin.c

callseq_plugin.c contains comments describing the various elements of the plug-in. See these comments for details.

Build

Build the plug-in into a library.

• Choose the appropriate command line from the following table. Compilation instructions vary slightly depending on your operating system.
  • Windows
  • All other systems

  	Compiler	Command Line	Notes
  Windows
  	cl	cl /LD /MD "/I%CSONAR%\codesonar\include" "/I%CSONAR%\csurf\include" callseq_plugin.c "%CSONAR%\codesonar\lib\codesonar.lib"	If you are using 64-bit CodeSonar, use 64-bit cl (see How to: Enable a 64-Bit Visual C++ Toolset on the Command Line).
  	Cygwin gcc	Note: Cygwin gcc is only suitable for building 32-bit CodeSonar plugins. Cygwin gcc only builds Cygwin binaries, so is not suitable for building 64-bit CodeSonar plug-ins. If you do not have an alternative gcc, you will need to download and install one. One option is mingw-w64. Cygwin 1.7 Use the gcc-3 executable (not gcc / gcc4, which does not support -mno-cygwin). If you do not have a gcc-3 binary, use Cygwin's setup.exe tool to install the mingw-gcc component. gcc-3 -shared -mno-cygwin "-I$CSONAR/codesonar/include" "-I$CSONAR/csurf/include" callseq_plugin.c -o callseq_plugin.dll "-L$CSONAR/codesonar/lib" -lcodesonar Cygwin 1.5 gcc -shared -mno-cygwin "-I$CSONAR/codesonar/include" "-I$CSONAR/csurf/include" callseq_plugin.c -o callseq_plugin.dll "-L$CSONAR/codesonar/lib" -lcodesonar	If you are using 32-bit CodeSonar on a 64-bit platform, add the -m32 flag to the command line (unless your compiler version will not accept it).
  	MinGW gcc	gcc -shared "-I$CSONAR\codesonar\include" "-I$CSONAR\csurf\include" callseq_plugin.c -o callseq_plugin.dll "-L$CSONAR\codesonar\lib" -lcodesonar	If you are using 64-bit CodeSonar, use 64-bit MinGW gcc. Note that, depending on your system configuration, this may not be the version invoked by the 'gcc' command - in this case you will need to either adjust your environment or use a different name to invoke the correct compiler. If you are using 32-bit CodeSonar on a 64-bit platform, add the -m32 flag to the command line (unless your gcc version will not accept it).
  All Other Systems We provide a full example for gcc. For other compilers, build callseq_plugin.so from callseq_plugin.c, including $CSONAR/codesonar/include and $CSONAR/csurf/include.
  	gcc	gcc -fPIC -shared -o callseq_plugin.so callseq_plugin.c -I$CSONAR/codesonar/include -I$CSONAR/csurf/include	If you are using 32-bit CodeSonar on a 64-bit platform, add the -m32 flag to the command line (unless it causes problems).

Install

Install the plug-in:

• Copy or move your compiled plug-in (callseq_plugin.dll, callseq_plugin.so, or callseq_plugin.bundle) to directory
  $CSONAR/codesonar/plugins/
  (If you don't have access to this directory, use the PLUGINS configuration file option to specify the file path to your compiled plug-in.)

Exercise

We have provided an extremely short example program to exercise the plug-in.

• Build callseq_sample.c into a CodeSonar project. Your exact build command will, as always, depend on your local build tools and on the hub location (host:port). In many cases, one of the following will suffice:

  with cl:	codesonar analyze callseq host:port cl /c callseq_sample.c
  with gcc:	codesonar analyze callseq host:port gcc -c callseq_sample.c

  See Building Projects (Command Line) or Building Projects (Windows Build Wizard) for more information about building a CodeSonar project.
• Look at the analysis results to see where the warning is issued, where the warning name appears in the results, and where the warning message appears.

Clean Up

If you don't want to use this plug-in in future:

• Remove the compiled plug-in (callseq_plugin.dll, callseq_plugin.so, or callseq_plugin.bundle) from $CSONAR/codesonar/plugins/

  (If you used an alternative location, remove the associated PLUGINS configuration file setting).

More on Plug-Ins

General Information:

Specific API Language: