C Checker Reference Manual

January 1998

next section previous section current document TenDRA home page document index

3.1 - Introduction
3.2 - Type conversions units;

  • variable analysis, including detection of unused variables, use of uninitialised variables, dependencies on order of evaluation in expressions and detection of unused function returns, computed values and static variables;

  • detection of unused header files;

  • configurable tests for detecting many other common programming errors;

  • complete standard API usage analysis;

  • several built-in checking environments plus support for user-defined checking profiles.

    1.3 About this document

    This document is designed as a reference manual detailing the features of the C static checker. It contains eleven chapters (including this introduction) and nine annexes.

    • Chapter 2: Configuring the Checker describes the built-in checking modes and the design of customised environments;

    • Chapters 3-8: Type Checking, Integral Types, Data Flow and Variable Analysis , Preprocessing Checks, ISO C and Other Dialects and Common Errors respectively;

    • Chapter 9: The Symbol Table Dump deals with the detection of unused header files, type checking across translation units and complete standard API usage analysis;

    • Chapter 10: Conditional Compilation describes the checker's approach to conditional compilation;

    • Chapter 11: References lists the references used in the production of this document;

    • Annex A: Checking Modes gives a description of the built-in environments;

    • Annex B: Command Line Options lists the command line checking options;

    • Annex C: Specifying Integral Types describes the built-in integer modes and the methods for customising them;

    • Annex D: Pragma Syntax Specification;

    • Annex E: Symbol Table Dump Specification;

    • Annex F: Token Syntax describes the methods and syntax used to produce abstract APIs;

    • Annex G: Abstract API Manipulation gives details of the ways in which TenDRA abstract APIs may be extended, combined or overriden by local declarations;

    • Annex H: Specifying Conversions with Tokens.

    Part of the TenDRA Web.
    Crown Copyright © 1998.

    ./usr/share/doc/tendra-doc/html/tdfc/tdfc5.html0000644000000000000000000002741706466607534021463 0ustar rootroot00000000000000 C Checker Reference Manual: Configuring the Checker

    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.

    • Xs ( strict checks ) denotes strict ISO standard C with most extra checks enabled as warnings;

    • Xp ( partial checks ) denotes strict ISO standard C with some extra checks enabled;

    • Xc ( conformance ) denotes strict ISO standard C with no extra checks enabled;

    • Xw ( warning mode ) represents a `warning' oriented compilation mode. Many non-ISO standard C features are permitted with a warning. Extra checks are performed to produce warnings.

    • Xa ( `standard-ish' C ) denotes ISO standard C with syntatic relaxation and no extra checks;

    • Xt ( traditional C ) denotes traditional ( Kernighan and Ritchie ) C with no extra checks.

    ( 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:

    • ansi ANSI X3.159;

    • iso ISO MSE 9899:1990(Amendment 1:1993(E));

    • posix POSIX 1003.1;

    • posix2 POSIX 1003.2;

    • xpg3 X/Open Portability Guide 3;

    • xpg4 X/Open Portability Guide 4;

    • cose COSE 1170;

    • svid3 System V Interface Definition 3rd Edition;

    • aes AES Revision A;

    • system System headers as main API.

    and the extension APIs are:

    • bsd_extn BSD-like extension for use with POSIX etc.;

    • x5_lib X11 (Release 5) Library;

    • x5_t X11 (Release 5) Intrinsics Toolkit;

    • x5_mu X11 (Release 5) Miscellaneous Utilities;

    • x5_aw X11 (Release 5) Athena Widgets;

    • x5_mit X11 (Release 5) MIT Implementation;

    • x5_proto X11 (Release 5) Protocol Extension;

    • x5_ext X11 (Release 5) Extensions;

    • x5_private X11 (Release 5) private headers (otherwise protected );

    • motif Motif 1.1;

    • system+ System headers as last resort API. Search the system headers only for those objects for which no declaration or definition can be found within the base API.

    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.

    ./usr/share/doc/tendra-doc/html/tdfc/tdfc6.html0000644000000000000000000010245006466607534021453 0ustar rootroot00000000000000 C Checker Reference Manual: Type Checking

    C Checker Reference Manual

    January 1998

    next section previous section current document TenDRA home page document index

    3.1 - Introduction
    3.2 - Type conversions units;

  • variable analysis, including detection of unused variables, use of uninitialised variables, dependencies on order of evaluation in expressions and detection of unused function returns, computed values and static variables;

  • detection of unused header files;

  • configurable tests for detecting many other common programming errors;

  • complete standard API usage analysis;

  • several built-in checking environments plus support for user-defined checking profiles.

    1.3 About this document

    This document is designed as a reference manual detailing the features of the C static checker. It contains eleven chapters (including this introduction) and nine annexes.

    • Chapter 2: Configuring the Checker describes the built-in checking modes and the design of customised environments;

    • Chapters 3-8: Type Checking, Integral Types, Data Flow and Variable Analysis , Preprocessing Checks, ISO C and Other Dialects and Common Errors respectively;

    • Chapter 9: The Symbol Table Dump deals with the detection of unused header files, type checking across translation units and complete standard API usage analysis;

    • Chapter 10: Conditional Compilation describes the checker's approach to conditional compilation;

    • Chapter 11: References lists the references used in the production of this document;

    • Annex A: Checking Modes gives a description of the built-in environments;

    • Annex B: Command Line Options lists the command line checking options;

    • Annex C: Specifying Integral Types describes the built-in integer modes and the methods for customising them;

    • Annex D: Pragma Syntax Specification;

    • Annex E: Symbol Table Dump Specification;

    • Annex F: Token Syntax describes the methods and syntax used to produce abstract APIs;

    • Annex G: Abstract API Manipulation gives details of the ways in which TenDRA abstract APIs may be extended, combined or overriden by local declarations;

    • Annex H: Specifying Conversions with Tokens.

    Part of the TenDRA Web.
    Crown Copyright © 1998.

    ./usr/share/doc/tendra-doc/html/tdfc/tdfc5.html0000644000000000000000000002741706466607534021463 0ustar rootroot00000000000000 C Checker Reference Manual: Configuring the Checker

    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.

    • Xs ( strict checks ) denotes strict ISO standard C with most extra checks enabled as warnings;

    • Xp ( partial checks ) denotes strict ISO standard C with some extra checks enabled;

    • Xc ( conformance ) denotes strict ISO standard C with no extra checks enabled;

    • Xw ( warning mode ) represents a `warning' oriented compilation mode. Many non-ISO standard C features are permitted with a warning. Extra checks are performed to produce warnings.

    • Xa ( `standard-ish' C ) denotes ISO standard C with syntatic relaxation and no extra checks;

    • Xt ( traditional C ) denotes traditional ( Kernighan and Ritchie ) C with no extra checks.

    ( 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:

    • ansi ANSI X3.159;

    • iso ISO MSE 9899:1990(Amendment 1:1993(E));

    • posix POSIX 1003.1;

    • posix2 POSIX 1003.2;

    • xpg3 X/Open Portability Guide 3;

    • xpg4 X/Open Portability Guide 4;

    • cose COSE 1170;

    • svid3 System V Interface Definition 3rd Edition;

    • aes AES Revision A;

    • system System headers as main API.

    and the extension APIs are:

    • bsd_extn BSD-like extension for use with POSIX etc.;

    • x5_lib X11 (Release 5) Library;

    • x5_t X11 (Release 5) Intrinsics Toolkit;

    • x5_mu X11 (Release 5) Miscellaneous Utilities;

    • x5_aw X11 (Release 5) Athena Widgets;

    • x5_mit X11 (Release 5) MIT Implementation;

    • x5_proto X11 (Release 5) Protocol Extension;

    • x5_ext X11 (Release 5) Extensions;

    • x5_private X11 (Release 5) private headers (otherwise protected );

    • motif Motif 1.1;

    • system+ System headers as last resort API. Search the system headers only for those objects for which no declaration or definition can be found within the base API.

    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.

    ./usr/share/doc/tendra-doc/html/tdfc/tdfc6.html0000644000000000000000000010245006466607534021453 0ustar rootroot00000000000000 C Checker Reference Manual: Type Checking

    C Checker Reference Manual

    January 1998

    next section previous section current document TenDRA home page document index

    3.1 - Introduction
    3.2 - Type conversions units;

  • variable analysis, including detection of unused variables, use of uninitialised variables, dependencies on order of evaluation in expressions and detection of unused function returns, computed values and static variables;

  • detection of unused header files;

  • configurable tests for detecting many other common programming errors;

  • complete standard API usage analysis;

  • several built-in checking environments plus support for user-defined checking profiles.

    1.3 About this document