C Checker Reference Manual

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 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.

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.

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:

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.

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 Chapter 3, Integral Types to Chapter 8, Symbol Table Dump ; for example the check for implicit function declarations described in Section 2.3.1, “Implicit Function Declarations” may be switched on using -X:implicit_func=check.

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.

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 -ffilecommand 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 :dircommand 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.

The only types which may be interconverted legally are integral types, floating point types and pointer types. Even if these rules are observed, the results of some conversions can be surprising and may vary on different machines. The checker can detect three categories of conversion: integer to integer conversions, pointer to integer and integer to pointer conversions, and pointer to pointer conversions.

In the default mode, the checker allows all integer to integer conversions, explicit integer to pointer and pointer to integer conversions and the explicit pointer to pointer conversions defined by the ISO C standard (all conversions between pointers to function types and other pointers are undefined according to the ISO C standard).

Checks to detect these conversions are controlled by the pragma:

#pragma TenDRA conversion analysis status

Unless explicitly stated to the contrary, throughout the rest of the document where status appears in a pragma statement it represents one of on (enable the check and produce errors), warning (enable the check but produce only warnings), or off (disable the check). Here status may be on to give an error if a conversion is detected, warning to produce a warning if a conversion is detected, or off to switch the checks off. The checks may also be controlled using the command line option-X:test=state where test is one of convert_all, convert_int, convert_int_explicit, convert_int_implicit, convert_int_ptr and convert_ptr and state is check,warn or dont.

Due to the serious nature of implicit pointer to integer, implicit pointer to pointer conversions and undefined explicit pointer to pointer conversions, such conversions are flagged as errors by default. These conversion checks are not controlled by the global conversion analysis pragma above, but must be controlled by the relevant individual pragmas given in sections Section 2.1.2, “Pointer to integer and integer to pointer conversions” and Section 2.1.3, “Pointer to pointer conversions”

#pragma TenDRA conversion analysis ( int-int ) status

#pragma TenDRA conversion analysis ( int-int explicit ) status

#pragma TenDRA conversion analysis ( int-int implicit ) status

#pragma TenDRA conversion analysis ( int-enum implicit ) status

#pragma TenDRA conversion analysis ( int-pointer explicit ) status

#pragma TenDRA conversion analysis ( int-pointer implicit ) status

#pragma TenDRA conversion analysis ( int-pointer ) status

#pragma TenDRA conversion analysis ( pointer-pointer ) status

#pragma TenDRA conversion analysis ( pointer-pointer explicit ) status

#pragma TenDRA conversion analysis ( pointer-pointer implicit ) status

#pragma TenDRA function pointer as pointer permit

#pragma TenDRA compatible type : char * == void * permit

#include <stdio.h>
void print ( string, offset, scale )
char *string;
unsigned int offset;
int scale;
{
  string += ( scale * offset );
  ( void ) puts ( string );
  return;
}

int main ()
{
  char *s = "hello there";
  print ( s + 4, 2U, -2 );
  return ( 0 );
}

The importance of function type checking in C lies in the conversions which can result from type mismatches between the arguments in a function call and the parameter types assumed by its definition or between the specified type of the function return and the values returned within the function definition. Until the introduction of function prototypes into ISO standard C, there was little scope for detecting the correct typing of functions. Traditional C allows for absolutely no type checking of function arguments, so that totally bizarre functions, such as:

int f ( n ) int n ; {
  return ( f ( "hello", "there" ) ) ;
}

are allowed, although their effect is undefined. However, the move to fully prototyped programs has been relatively slow. This is partially due to an understandable reluctance to change existing, working programs, but the desire to maintain compatibility with existing C compilers, some of which still do not support prototypes, is also a powerful factor. Prototypes are allowed in the checker's default mode but tchk can be configured to allow, allow with a warning or disallow prototypes, using:

#pragma TenDRA prototype permit

where permit is allow, disallow or warning.

Even if prototypes are not supported the checker has a facility, described below, for detecting incorrectly typed functions.

#pragma TenDRA weak prototype analysis status

void f ( n )long n;{
  printf ( "%ld\n", n );
}
void g (){
  f ( 3 );
}

#ifdef __STDC__
  void f ( long );
#endif

void f WEAK ( long );

extern void f ();
void g () {
  f ( 3 );
  f ( 4U );
}

void f ( a ) int a; {
  printf ( "%d\n", a );
}
void g () {
  f ( 3, 4 );
}

int execl ( const char *, const char *, ... );

printf ( "%ld", 4 );

int printf ( const char *,long );

#pragma TenDRA type PSTRING for ... printf

typedef const char *PSTRING;

int f ( PSTRING, ... );

#ifdef __TenDRA__
#pragma TenDRA type PSTRING for ... printf
#else
typedef const char *PSTRING;
#endif

int f ( int c )
{
  if ( c ) return ( 1 );
  return;
}

#pragma TenDRA incompatible void return permit

int f ( int c )
{
  if ( c ) return ( 1 );
}

There are several commonly used features of C, some of which are even allowed by the ISO C standard, which can circumvent or hinder the type-checking of a program. The checker may be configured either to enforce the absence of these features or to support them with or without a warning, as described below.

int f ( int c ) {
  return ( g( c )+1 );
}

extern int g ();

#pragma TenDRA implicit function declaration status

int f(char);
int f(a)char a;{
...
}

const int a;
int a;

#pragma TenDRA incompatible type qualifier permit

The ISO C standard rules may be summarised as follows: long integral types promote to themselves; other integral types promote to whichever of int or unsigned int they fit into. In full the promotions are:

The traditional C integer promotion rules are often referred to as the signed promotion rules. Under these rules, long integral types promote to themselves, as in ISO C, but the other integral types promote to unsigned int if they are qualified by unsigned, and int otherwise. Thus the signed promotion rules may be represented as follows:

The traditional promotion rules are applied in the Xt built-in environment only. All of the other built-in environments specify the ISO C promotion rules. Users may also specify their own rules for integer promotions and minimum integer ranges; the methods for doing this are described in Annex H.

The ISO C standard rules for calculating the type of an arithmetic operation involving two integer types is as follows - work out the integer promotions of the types of the two operands, then:

Both promoted values are converted to the result type, and the operation is then applied.

A simple-minded implementation of the integer conversion checks described in 3.2 would interact badly with these rules. Consider, for example, adding two values of type char:

char f ( char a, char b )
{
  char c = a + b ;
  return ( c ) ;
}

The various stages in the calculation of c are as follows - a and b are converted to their promotion type, int, added together to give an int result, which is converted to a char and assigned to c. The conversions of a and b from char to int are always safe, and so present no difficulties to the integer conversion checks. The conversion of the result from int to char, however, is precisely the type of value destroying conversion which these checks are designed to detect.

Obviously, an integer conversion check which flagged all char arithmetic would never be used, thereby losing the potential to detect many subtle portability errors. For this reason, the integer conversion checks are more sophisticated. In all typed languages, the type is used for two purposes - for static type checking and for expressing information about the actual representation of data on the target machine. Essentially it is a confusion between these two roles which leads to the problems above. The C promotion and arithmetic rules are concerned with how data is represented and manipulated, rather than the underlying abstract types of this data. When a and b are promoted to int prior to being added together, this is only a change in representation; at the conceptual level they are still char's. Again, when they are added, the result may be represented as an int, but conceptually it is a char. Thus the assignment to c, an actual char, is just a change in representation, not a change in conceptual type.

So each expression may be regarded as having two types - a conceptual type which stands for what the expression means, and a representational type which stands for how the expression is to represented as data on the target machine. In the vast majority of expressions, these types coincide, however the integral promotion and arithmetic conversions are changes of representational, not conceptual, types. The integer conversion checks are concerned with detecting changes of conceptual type, since it is these which are most likely to be due to actual programming errors.

It is possible to define integral types within the TenDRA extensions to C in which the split between concept and representation is made explicit. The pragma:

#pragma TenDRA keyword TYPE for type representation

may be used to introduce a keyword TYPE for this purpose (as with all such pragmas, the precise keyword to be used is left to the user). Once this has been done, TYPE ( r, t ) may be used to represent a type which is conceptually of type t but is represented as data like type r. Both t and r must be integral types. For example:

TYPE ( int, char ) a ;

declares a variable a which is represented as an int, but is conceptually a char.

In order to maintain compatibility with other compilers, it is necessary to give TYPE a sensible alternative definition. For all but conversion checking purposes, TYPE ( r, t ) is identical to r, so a suitable definition is:

#ifdef __TenDRA__
#pragma TenDRA keyword TYPE for type representation
#else
#define TYPE( r, t ) r
#endif

Since the checker uses only information about the minimum guaranteed ranges of integral types, integer values for which the actual type of the values is unknown may arise. Integer values of undetermined type generally arise in one of two ways: through the use of integer literals and from API types which are not completely specified.

int f ( int n ) {
  return ( n & 0xff00 ) ;
}

#include <stdlib.h>
int main() {
  size_t size;
  size = sizeof(int);
}

#pragma TenDRA set size_t:signed int

Given the complexity of the rules governing the types of integers and results of integer operations, as well as the variation of integral ranges with machine architecture, it is hardly surprising that unexpected results of integer operations are at the root of many programming problems. These problems can often be hard to track down and may suddenly appear in an application which was previously considered "safe", when it is moved to a new system. Since the checker supports the concept of a guaranteed minimum size of an integer it is able to detect many potential problems involving integer constants. The pragma:

#pragma TenDRA integer overflow analysis status

where status is on, warning or off, controls a set of checks on arithmetic expressions involving integer constants. These checks cover overflow, use of constants exceeding the minimum guaranteed size for their type and division by zero. They are not enabled in the default mode.

There are two special cases of integer overflow for which checking is controlled separately:

Bitfield sizes. Obviously, the size of a bitfield must be smaller than or equal to the minimum size of its integral type. A bitfield which is too large is flagged as an error in the default mode. The check on bitfield sizes is controlled by:

#pragma TenDRA bitfield overflow permit

where permit is one of allow, disallow or warning.

Octal and hexadecimal escape sequences. According to the ISO C standard, the value of an octal or hexadecimal escape sequence shall be in the range of representable values for the type unsigned char for an integer character constant, or the unsigned type corresponding to wchar_t for a wide character constant. The check on escape sequence sizes is controlled by:

#pragma TenDRA character escape overflow permit

where the options for permit are allow, warning and disallow. The check is switched on by default.

The results of some integer operations are undefined by the ISO C standard for certain argument types. Others are implementation-defined or simply likely to produce unexpected results.In the default mode such operations are processed silently, however a set of checks on operations involving integer constants may be controlled using:

#pragma TenDRA integer operator analysis status

where status is replaced by on, warning or off. This pragma enables checks on:

Although the use of long long to specify a 64 bit integer type is not supported by the ISO C standard it is becoming increasingly popular as in programming use. By default, tchk does not support the use of long long but the checker can be configured to support the long long type to different degrees using the following pragmas:

#pragma TenDRA longlong type permit

where permit is one of allow (long long type accepted), disallow (errors produced when long long types are detected) or warning (long long type are accepted but a warning is raised).

#pragma TenDRA set longlong type : type_name

where type_name is long or long long.

The first pragma determines the behaviour of the checker if the type long long is encountered as a type specifier. In the disallow case, an error is raised and the type specifier mapped to long, otherwise the type is stored as long long although a message alerting the user to the use of long long is raised in the warning mode. The second pragma determines the semantics of long long. If the type specified is long long, then long long is treated as a separate integer type and if code generation is enabled, long long types appears in the output. Otherwise the type is mapped to long and all objects declared long long are output as if they had been declared long (a warning is produced when this occurs). In either case, long long is treated as a distinct integer type for the purpose of integer conversion checking.

Extensions to the integer promotion and arithmetic conversion rules are required for the long long type. These have been implemented as follows:

There are now three cases where the type of an integer arithmetic operation is not completely determined from the type of its arguments, i.e.

In these cases, the type of the operation is represented using an abstract integral type as described in section Section 3.1, “Integer promotion rules”

Consider the following function definition:

int f ( int n )
{
  if ( n ) {
  return ( 1 );
} else {
  return ( 0 );
}
  return ( 2 );
}

The final return statement is redundant since it can never be reached. The test for unreachable code is controlled by:

#pragma TenDRA unreachable code permit

where permit is replaced by disallow to give an error if unreached code is detected, warning to give a warning, or allow to disable the test (this is the default).

There are also equivalent command-line options to tchk of the form -X:unreached=state, where state can be check, warn or dont.

Annotations to the code in the form of user-defined keywords may be used to indicate that a certain statement is genuinely reached or unreached. These keywords are introduced using:

#pragma TenDRA keyword REACHED for set reachable
#pragma TenDRA keyword UNREACHED for set unreachable

The statement REACHED then indicates that this portion of the program is actually reachable, whereas UNREACHED indicates that it is unreachable. For example, one way of fixing the program above might be to say that the final return is reachable (this is a blatant lie, but never mind). This would be done as follows:

int f ( int n ) {
  if ( n ) {
return ( 1 );
  } else {
return ( 0 )
  }
  REACHED
  return ( 2 );
}

An example of the use of UNREACHED might be in the function below which falls out of the bottom without a return statement. We might know that, because it is never called with c equal to zero, the end of the function is never reached. This could be indicated as follows:

int f ( int c ){
  if ( c ) return ( 1 );
  UNREACHED
}

As always, if new keywords are introduced into a program then definitions need to be provided for conventional compilers. In this case, this can be done as follows:

#ifdef __TenDRA__
#pragma TenDRA keyword REACHED for set reachable
#pragma TenDRA keyword UNREACHED for set unreachable
#else
#define REACHED
#define UNREACHED
#endif

Another flow analysis check concerns fall through in case statements. For example, in:

void f ( int n )
{
  switch ( n ) {
case 1 : puts ( "one" );
   case 2 : puts ( "two" );
  }
}

the control falls through from the first case to the second. This may be due to an error in the program (a missing break statement), or be deliberate. Even in the latter case, the code is not particularly maintainable as it stands - there is always the risk when adding a new case that it will interrupt this carefully contrived flow. Thus it is customary to comment all case fall throughs to serve as a warning.

In the default mode, the TenDRA C checker ignores all such fall throughs. A check to detect fall through in case statements is controlled by:

#pragma TenDRA fall into case permit

where permit is allow (no errors), warning (warn about case fall through) or disallow (raise errors for case fall through).

There are also equivalent command-line options to tcc of the form -X:fall_thru=state, where state can be check, warn or dont.

Deliberate case fall throughs can be indicated by means of a keyword, which has been introduced using:

#pragma TenDRA keyword FALL_THROUGH for fall into case

Then, if the example above were deliberate, this could be indicated by:

void f ( int n ){
  switch ( n ) {
case 1 : puts ( "one" );
FALL_THROUGH
case 2 : puts ( "two" );
  }
}

If a keyword is introduced in this way, then an alternative definition needs to be introduced for conventional compilers. This might be done as follows:

#ifdef __TenDRA__
#pragma TenDRA keyword FALL_THROUGH for fall into case
#else
#define FALL_THROUGH
#endif

The following three checks are designed to detect possible errors in conditional statements.

if( var1 == 1 ) ;
var2 = 0 ;

#pragma TenDRA extra ; after conditional permit

#pragma TenDRA assignment as bool permit

if( var = 1 ) { ...

#pragma TenDRA const conditional permit

The ISO C standard section 6.3, provides a set of rules governing the order in which operators within expressions should be applied. These rules are said to specify the operator precedence and are summarised in the table over the page. Operators on the same line have the same precedence and the rows are in order of decreasing precedence. Note that the unary +, -, * and & operators have higher precedence than the binary forms and thus appear higher in the table.

The precedence of operators is not always intuitive and often leads to unexpected results when expressions are evaluated. A particularly common example is to write:

if ( var & TEST == 1) { ...
}
else { ...

assuming that the control expression will be evaluated as:

( ( var & TEST ) == 1 )

However, the == operator has a higher precedence than the bitwise & operator and the control expression is evaluated as:

( var & ( TEST == 1 ) )

which in general will give a different result

The TenDRA C checker can be configured to flag expressions containing certain operators whose precedence is commonly confused, namely:

The check is switched off by default and is controlled using:

#pragma TenDRA operator precedence status

where status is on, warning or off.

The variable analysis checks are controlled by:

#pragma TenDRA variable analysis status

where status is on, warning or off as usual. The checks are switched off in the default mode.

There are also equivalent command line options to tchk of the form -X:variable=state, where state can be check, warn or dont.

The variable analysis is concerned with the evaluation of expressions and the use of local variables, including function arguments. Occasionally it may not be possible to statically perform a full analysis on an expression or variable and in these cases the messages produced indicate that there may be a problem. If a full analysis is possible a definite error or warning is produced. The individual checks are listed in sections 5.6.1 to 5.6.6 and section 5.7 describes the source annotations which can be used to fine-tune the variable analysis.

var = i + arr[ i++ ] ;

var = arr[i++] + i++ ;