C Checker Reference Manual

January 1998

next section previous section current document TenDRA home page document index

2.1 - Introduction
2.1.1 - Built-in checking profiles
2.1.2 - Minimum integer ranges
2.1.3 - API selection
2.1.4 - Individual command line checking options
2.1.5 - Construct a customised checking environment
2.2 - Scoping checking profiles

2 Configuring the Checker

2.1 Introduction

There are several methods available for configuring the checker most of which are selected by using the relevant command line option. More detailed customisation may require special #pragma statements to be incorporated into the source code to be analysed (this commonly takes the form of a startup file). The configuration options generally act independently of one another and unless explicitly forbidden in the descriptions below, they may be combined in any way.

2.1.1 Built-in checking profiles

Six standard checking profiles are provided with the tool and are held as a set of startup files which are automatically included in each C source file. A brief description of each profile is given below, for a complete descriptions see Annex A.

( The modes Xc, Xa, and Xt are meant to roughly correspond to the modes found on some System V compilers. )

The default checking environment is Xc, other environments are specified by passing the name of the environment to the checker as a command line flag, e.g. the -Xs flag specifies that the Xs environment is to be used. These environments are the base checking modes and may not be combined: if more than one base mode is specified, only the final base mode is actually used - the earlier ones are ignored.

There are also two "add-on" checking profiles, called nepc (no extra portability checks) and not_ansi, which may be used to complement any base mode. The "add-on" modes may alter the status of checks set in the base mode. The nepc mode switches off many of the checks relating to portability issues and may be specified by passing the -nepc command line option to tchk. The not_ansi mode supports a raft of non-ISO features and is specified using the -not_ansi command line flag.

2.1.2 Minimum integer ranges

By default the checker assumes that all integer ranges conform to the minimum ranges prescribed by the ISO C standard, i.e. char contain at least 8 bits, short and int contain at least 16 bits and long contains at least 32 bits. If the -Y32bit flag is passed to the checker it assumes that integers conform to the minimum ranges commonly found on most 32 bit machines, i.e. int contains at least 32 bits and int is strictly larger than short so that the integral promotion of unsigned short is int under the ISO C standard integer promotion rules.

2.1.3 API selection

By default, programs are checked against the standard ISO C API as specified in the ISO C standard Chapter 7. Other APIs are specified by passing the -Yapi-name flag to the tchk, where api-name is one of the API designators listed below. APIs fall into two categories: base APIs and extension APIs. If more than one base API is specified to tchk, only the last one is used for checking; the others are ignored. Additional extension APIs, however, may be used in addition to any suitable base API.

The base APIs available are:

and the extension APIs are:

2.1.4 Individual command line checking options

Some of the checks available can be controlled using a command line option of the form -Xopt,opt,..., where the various opt options give a comma-separated list of commands. These commands have the form test=status, where test is the name of the check, and status is either check (apply check and give an error if it fails), warn (apply check and give a warning if it fails) or dont (do not apply check). The names of checks can be found with their descriptions in Chapters 3 - 8; for example the check for implicit function declarations described in
3.4.1 may be switched on using -X:implicit_func=check .

2.1.5 Construct a customised checking environment

The individual checks performed by the C static checker are generally controlled by #pragma directives. The reason for this is that the ISO standard places no restrictions on the syntax following a #pragma preprocessing directive, and most compilers/checkers can be configured to ignore any unknown #pragma directives they encounter.

Most of these directives begin:

	#pragma TenDRA ...
and are always checked for syntactical correctness. The individual directives, together with the checks they control are described in Chapters 3 - 8. Section 2.2 describes the method of constructing a new checking profile from these individual checks.

2.2 Scoping checking profiles

Almost all the available checks are scoped (exceptions will be mentioned in the description of the check). A new checking scope may be started by inserting the pragma:

	#pragma TenDRA begin
at the outermost level. The scope runs until the matching:

	#pragma TenDRA end
directive, or to the end of the translation unit (the ISO C standard definition of a translation unit as being a source file, together with any headers or source files included using the #include preprocessing directive, less any source lines skipped by any of the conditional inclusion preprocessing directives, is used throughout this document).

Checking scopes may be nested in the obvious way.

Each new checking scope inherits its initial set of checks from the checking scope which immediately contains it (this includes the implicit main checking scope consisting of the entire source file). Any checks switched on or off within the scope apply only to that scope and any scope it contains. The set of checks applied reverts to its previous state at the end of a scope. Thus, for example:

	#pragma TenDRA variable analysis on
	/* Variable analysis is on here */
	#pragma TenDRA begin
	#pragma TenDRA variable analysis off
	/* Variable analysis is off here */
	#pragma TenDRA end
	/* Variable analysis is on again here */
Once a check has been set any attempt to change its status within the same scope is flagged as an error. If checks need to be switched on and off in the same source file, they must be properly scoped. The built-in compilation modes have the entire source file as their scope.

The method of applying different checking profiles to different parts of a program clearly needs to take into account those properties of C which can circumvent such scoping. Consider for example:

	#pragma TenDRA begin
	#pragma TenDRA unknown escape allow
	#define STRING "hello\!"
	#pragma TenDRA end
	char * f () {
		return ( STRING ) ;
The macro STRING is defined in an area where unknown escape sequences, such as \!, are allowed, but it is expanded in an area where they are not allowed (this is the default setting). The conventional approach to macro expansion would lead to the unknown escape sequence being flagged as an error, even though the user probably intended to avoid this. The checker therefore expands all macros using the checking profile in which they were defined, rather than the current checking scope.

The directives describing the user's desired checking profile could be included directly in the program itself, ideally in some configuration file which is #include'd in all source files. It is however perhaps more appropriate to store the directives as a startup file, file say, which is passed to the checker using the -ffile command line option. It should be noted that user-defined compilation modes are defined on top of a built-in mode base (normally Xc, the default mode). It is therefore important to scope the new checking profile as described above.

Names may be associated with checking scopes by using an alternative form of the begin directive:

	#pragma TenDRA begin name environment identifier
where identifier is any valid C identifier. Thereafter a statement of the form:

	#pragma TenDRA use environment identifier
changes the current checking environment to the environment associated with identifier.

Sometimes it may be desirable to use different checking profiles for different parts of a translation unit, e.g. applying less strict checks to any system headers which may be included. The checker can be configured to apply a named checking scope, env_name, to any files included from a directory which has been named dir_name, using:

	#pragma TenDRA directory dir_name use environment env_name
The directory name must be passed to the checker using the -Ndir_name :dir command line option. This is equivalent to the usual -Idir option for specifying include paths, except that it also attaches the name dir_name to the directory.

Part of the TenDRA Web.
Crown Copyright © 1998.