C/C++ Checker Reference Manual

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

The command line options for portability checking are:

where status can be check, warn or dont.

1.2. Customising checking profiles

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.

1.3. Scoping checking profiles

Almost all the available checks are scoped (exceptions will be mentioned in the description of the check). Scopes may be controlled by the same #pragma TenDRA begin directive described by the C/C++ Producer Configuration Guide.

1.4. Other checks

Several checks of varying utility have been implemented in the C++ producer but do not as yet have individual directives controlling their use. These can be enabled en masse using the directive:

#pragma TenDRA++ catch all allow

It is intended that this directive will be phased out as these checks are assigned controlling directives. It is possible to achieve finer control over these checks by enabling their individual error messages as described above.

2.1. Integer promotion rules

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:

Note that even with these simple built-in types, there is a degree of uncertainty, namely concerning the promotion of unsigned short. On most machines, int is strictly larger than short so the promotion of unsigned short is int. However, it is possible for short and int to have the same size, in which case the promotion is unsigned int. When using the ISO C promotion rules, the checker usually avoids making assumptions about the implementation by treating the promotion of unsigned short as an abstract integral type. If, however, the -Y32bit option is specified, int is assumed to be strictly larger than short, and unsigned short promotes to int.

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.

2.2. Arithmetic operations on integer types

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:

1. If either promoted type is unsigned long, the result type is unsigned long;

2. Otherwise, if one promoted type is long and the other is unsigned int, then if a long int can represent all values of an unsigned int, the result type is long; otherwise the result type is unsigned long;

3. Otherwise, if either promoted type is long, the result type is long;

4. Otherwise, if either promoted type is unsigned int, the result type is unsigned int;

5. Otherwise the result type is int.

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

2.3. Interaction with the integer conversion checks

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

2.4. Target dependent integral types

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

2.5. Integer overflow checks

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

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

2.6. Integer operator checks

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 enabled checks on:

• shift operations where an expression is shifted by a negative number or by an amount greater than or equal to the width in bits of the expression being shifted;

• right shift operation with a negative value of signed integral type as the first argument;

• division operation with a negative operand;

• test for an unsigned value strictly greater than or less than 0 (these are always true or false respectively);

• conversion of a negative constant value to an unsigned type;

• application of unary - operator to an unsigned value.

2.7. Support for 64 bit integer types (long long)

Although the use of long long to specify a 64 bit integer type is not supported by the ISO C90 standard it is becoming increasingly popular as in programming use. By default, tcc 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 types 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:

• the types of integer arithmetic operations where neither argument has long long type are unaffected;

• long long and unsigned long long both promote to themselves;

• the result type of arithmetic operations with one or more arguments of type unsigned long long is unsigned long long;

• otherwise if either argument has type signed long long the overall type is long long if both arguments can be represented in this form, otherwise the type is unsigned long long.

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.

3.1. Type specifications

const int a ;
int a ;

#pragma TenDRA incompatible type qualifier permit

#pragma TenDRA ignore struct/union/enum tag on

#pragma TenDRA forward enum declaration allow

#pragma TenDRA extra , allow

#pragma TenDRA complete struct/union analysis on

struct tag *p;

#pragma TenDRA complete struct/union analysis status

struct tag *p;
struct tag {
	int a;
	int b;
};

3.2. Type conversions

The only types which may be interconverted legally in C 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 §3.2.2 and §4.5.

#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-int explicit) on
#pragma TenDRA conversion analysis (int-int implicit) on

#pragma TenDRA conversion analysis (int-pointer explicit) on
#pragma TenDRA conversion analysis (int-pointer implicit) on

#pragma TenDRA conversion analysis (pointer-int explicit) on
#pragma TenDRA conversion analysis (pointer-int implicit) on

#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

#pragma TenDRA conversion analysis (int-int) on

#pragma TenDRA conversion analysis (int-pointer) on
#pragma TenDRA conversion analysis (pointer-int) on
#pragma TenDRA conversion analysis (pointer-pointer) on

#pragma TenDRA conversion analysis on

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

#pragma TenDRA++ conversion analysis (void*-pointer implicit) on

#pragma TenDRA++ conversion analysis (pointer-void* implicit) on

#pragma TenDRA function pointer as pointer allow

char a = 1, b = 2 ;
			char c = a + b ;

int a = 1, b = 2 ;
			char c = a + b ;

#pragma TenDRA keyword identifier for type representation

#pragma token PROC ( EXP : t : ) EXP : s : conv #

#pragma TenDRA conversion identifier-list allow

t a ;
			s b = a ;		// maps to conv ( a )

#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 );
}

3.3. Function type checking

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 tdfc2 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 ) ;
}

#pragma TenDRA weak prototype analysis on

#pragma TenDRA keyword identifier for weak

#pragma TenDRA prototype allow
#pragma TenDRA prototype (weak) allow

#pragma TenDRA argument type-id as type-id
#pragma TenDRA argument type-id as ...
#pragma TenDRA extra ... allow
#pragma TenDRA incompatible promoted function argument allow

#pragma TenDRA type identifier for ... printf
#pragma TenDRA type identifier for ... scanf

#ifdef __NO_PRINTF_CHECKS
		typedef const char *__printf_string ;
		#else
#pragma TenDRA type __printf_string for ... printf
		#endif

		int printf ( __printf_string, ... ) ;
		int fprintf ( FILE *, __printf_string, ... ) ;
		int sprintf ( char *, __printf_string, ... ) ;

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 ) ;
}

#pragma TenDRA++ ambiguous overload resolution allow

#pragma TenDRA++ overload resolution allow

int f ( int ) ;
			int f ( unsigned int ) ;
			int f ( long ) ;
			int f ( unsigned long ) ;

			int a = f ( sizeof ( int ) ) ;	// which f?

#pragma TenDRA++ conditional overload resolution allow
#pragma TenDRA++ conditional overload resolution (complete) allow

#pragma TenDRA++ conditional overload resolution (incomplete) allow

3.4. Overriding type checking

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;
{
...
}

#pragma TenDRA incompatible promoted function argument

4.1. Unreachable code analysis

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

The directive:

#pragma TenDRA unreachable code allow

enables a flow analysis check to detect unreachable code. It is possible to assert that a statement is reached or not reached by preceding it by a keyword introduced by one of the directives:

#pragma TenDRA keyword identifier for set reachable
#pragma TenDRA keyword identifier for set unreachable

The fact that certain functions, such as exit, do not return a value can be exploited in the flow analysis routines. The equivalent directives:

#pragma TenDRA bottom identifier
#pragma TenDRA++ type identifier for bottom

can be used to introduce a typedef declaration for the type, bottom, returned by such functions. The TenDRA API headers declare exit and similar functions in this way, for example:

#pragma TenDRA bottom __bottom
__bottom exit ( int ) ;
__bottom abort ( void ) ;

The bottom type is compatible with void in function declarations to allow such functions to be redeclared in their conventional form.

4.2. Case fall through

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" );
	}
}

Note that FALL_THROUGH is inserted between the two cases, rather than at the end of the list of statements following the first case.

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

4.3. Enumerations controlling switch statements

Enumerations are commonly used as control expressions in switch statements. When case labels for some of the enumeration constant belonging to the enumeration type do not exist and there is no default label, the switch statement has no effect for certain possible values of the control expression. Checks to detect such switch statements are controlled by:

#pragma TenDRA enum switch analysis status

where status is on (raise an error), warning (produce a warning), or off (the default mode when no errors are produced).

4.4. Empty if statements

Consider the following C statements:

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

The conditional statement serves no purpose here and the second statement will always be executed regardless of the value of var1. This is almost certainly not what the programmer intended to write. A test for if statements with no body is controlled by:

#pragma TenDRA extra ; after conditional permit

with the usual allow (this is the default setting), warning and disallow options for permit.

4.5. Use of assignments as control expressions

Using the C assignment operator, =, when the equality operator == was intended is an extremely common problem. The pragma:

#pragma TenDRA assignment as bool permit

is used to control the treatment of assignments used as the controlling expression of a conditional statement or a loop, e.g.

if( var = 1 ) { ...

The options for permit are allow, warning and disallow. The default setting allows assignments to be used as control statements without raising an error.

4.6. Constant control expressions

Statements with constant control expressions are not really conditional at all since the value of the control statement can be evaluated statically. Although this feature is sometimes used in loops, relying on a break, goto or return statement to end the loop, it may be useful to detect all constant control expressions to check that they are deliberate. The check for statically constant control expressions is controlled using:

#pragma TenDRA const conditional permit

where permit may be replaced by disallow to give an error when constant control expressions are encountered, warning to replace the error by a warning, or the check may be switched off using allow (this is the default).

4.7. Conditional and iteration statements

The directive:

#pragma TenDRA const conditional allow

can be used to enable a check for constant expressions used in conditional contexts. A literal constant is allowed in the condition of a while , for or do statement to allow for such common constructs as:

while ( true ) {
	// while statement body
}

and target dependent constant expressions are allowed in the condition of an if statement, but otherwise constant conditions are reported according to the status of this check.

The common error of writing = rather than == in conditions can be detected using the directive:

#pragma TenDRA assignment as bool allow

which can be used to disallow such assignment expressions in contexts where a boolean is expected. The error message can be suppressed by enclosing the assignment within parentheses.

Another common error associated with iteration statements, particularly with certain brace styles, is the accidental insertion of an extra semicolon as in:

for ( init ; cond ; step ) ;
{
	// for statement body
}

The directive:

#pragma TenDRA extra ; after conditional allow

can be used to enable a check for such suspicious empty iteration statement bodies (it actually checks for ;{).

4.8. Exception analysis

The ISO C++ rules do not require exception specifications to be checked statically. This is to facilitate the integration of large systems where a single change in an exception specification could have ramifications throughout the system. However it is often useful to apply such checks, which can be enabled using the directive:

#pragma TenDRA++ throw analysis on

This detects any potentially uncaught exceptions and other exception problems. In the error messages arising from this check, an uncaught exception of type ... means that an uncaught exception of an unknown type (arising, for example, from a function without an exception specification) may be thrown. For example:

void f ( int ) throw ( int ) ;
void g ( int ) throw ( long ) ;
void h ( int ) ;

void e () throw ( int )
{
	f ( 1 ) ;   // OK
	g ( 2 ) ;   // uncaught 'long' exception
	h ( 3 ) ;   // uncaught '...' exception
}

5.1. Order of evaluation

The ISO C standard specifies certain points in the expression syntax at which all prior expressions encountered are guaranteed to have been evaluated. These positions are called sequence points and occur:

• after the arguments and function expression of a function call have been evaluated but before the call itself;

• after the first operand of a logical &&, or || operator;

• after the first operand of the conditional operator, ?:;

• after the first operand of the comma operator;

• at the end of any full expression (a full expression may take one of the following forms: an initialiser; the expression in an expression statement; the controlling expression in an if, while, do or switch statement; each of the three optional expressions of a for statement; or the optional expression of a return statement).

Between two sequence points however, the order in which the operands of an operator are evaluated, and the order in which side effects take place is unspecified - any order which conforms to the operator precedence rules above is permitted. For example:

var = i + arr[ i++ ] ;

may evaluate to different values on different machines, depending on which argument of the + operator is evaluated first. The checker can detect expressions which depend on the order of evaluation of sub-expressions between sequence points and these are flagged as errors or warnings when the variable analysis is enabled.

5.2. Operator precedence

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:

• && versus ||

• << and >> versus + and -

• & versus == != < > <= >= + and -

• ^ versus & == |= < > <= >= + and -

• | versus ^ & == |= < > <= >= + and -

The check is switched off by default. The the directive:

#pragma TenDRA operator precedence analysis on

can be used to enable a check for expressions where the operator precedence is not necessarily what might be expected. The intended precedence can be clarified by means of explicit parentheses. The precedence levels checked are as follows:

• && versus ||.

• << and >> versus binary + and -.

• Binary & versus binary +, -, ==, !=, >, >=, < and <=.

• ^ versus binary &, +, -, ==, !=, >, >=, < and <=.

• | versus binary ^, &, +, -, ==, !=, >, >=, < and <=.

Also checked are expressions such as a < b < c which do not have their normal mathematical meaning. For example, in:

d = a << b + c ;	// precedence is a << ( b + c )

the precedence is counter-intuitive, although strangely enough, it isn't in:

cout << b + c ;		// precedence is cout << ( b + c )

Other dubious arithmetic operations can be checked for using the directive:

#pragma TenDRA integer operator analysis on

This includes checks for operations, such as division by a negative value, which are implementation dependent, and those such as testing whether an unsigned value is less than zero, which serve no purpose. Similarly the directive:

#pragma TenDRA++ pointer operator analysis on

checks for dubious pointer operations. This includes very simple bounds checking for arrays and checking that only the simple literal 0 is used in null pointer constants:

char *p = 1 - 1 ;	// valid, but weird

The directive:

#pragma TenDRA integer overflow analysis on

is used to control the treatment of overflows in the evaluation of integer constant expressions. This includes the detection of division by zero.

5.3. Floating point equality

Due to the rounding errors that occur in the handling of floating point values, comparison for equality between two floating point values is a hazardous and unpredictable operation. Tests for equality of two floating point numbers are controlled by:

#pragma TenDRA floating equality permit

where permit is allow, warning or disallow. By default the check is switched off.

5.4. Operand of sizeof

According to the ISO C standard, section 6.3.3.4, the operand of the sizeof operator is not itself evaluated. If the operand has any side-effects these will not occur. When the variable analysis is enabled, the checker detects the use of expressions with side-effects in the operand of the sizeof operator.

6.1. Variable lifetime analysis

The directive:

#pragma TenDRA variable analysis on

enables checks on the uses of automatic variables and function parameters. These checks detect:

• If a variable is not used in its scope.

• If the value of a variable is used before it has been assigned to.

• If a variable is assigned to twice without an intervening use.

• If a variable is assigned to twice without an intervening sequence point.

as illustrated by the variables a, b, c and d respectively in:

void f ()
{
	int a ;        // a never used
	int b ;
	int c = b ;    // b not initialised
	c = 0 ;        // c assigned to twice
	int d = 0 ;
	d = ++d ;      // d assigned to twice
}

The second, and more particularly the third, of these checks requires some fairly sophisticated flow analysis, so any hints which can be picked up from exhaustive switch statements etc. is likely to increase the accuracy of the errors detected.

In a non-static member function the various non-static data members are analysed as if they were automatic variables. It is checked that each member is initialised in a constructor. A common source of initialisation problems in a constructor is that the base classes and members are initialised in the canonical order of virtual bases, non-virtual direct bases and members in the order of their declaration, rather than in the order in which their initialisers appear in the constructor definition. Therefore a check that the initialisers appear in the canonical order is also applied.

It is possible to change the state of a variable during the variable analysis using the directives:

#pragma TenDRA set expression
#pragma TenDRA discard expression

The first asserts that the variable given by the expression has been assigned to; the second asserts that the variable is not used. An alternative way of expressing this is by means of keywords:

SET ( expression )
DISCARD ( expression )

introduced using the directives.

#pragma TenDRA keyword identifier for set
#pragma TenDRA keyword identifier for discard variable

respectively. These expressions can appear in expression statements and as the first argument of a comma expression.

6.2. 5.6.2 Modification between sequence points

The ISO C standard states that if an object is modified more than once, or is modified and accessed other than to determine the new value, between two sequence points, then the behaviour is undefined. Thus the result of:

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

is undefined, since the value of i is being incremented twice between sequence points. This behaviour is detected by the variable analysis.

6.3. Unused variables

As part of the variable analysis, a simple test applied to each local variable at the end of its scope to determine whether it has been used in that scope. For example, in:

int f ( int n )
{
	int r;
	return ( 0 );
}

both the function argument n and the local variable r are unused.

6.4. Values set and not used

This is a more complex test since it is applied to every instance of setting the variable. For example, in:

int f ( int n )
{
	int r = 1;
	r = 5;
	return ( r );
}

the first value r is set to 1 and is not used before it is overwritten by 5 (this second value is used however). This test requires some flow analysis. For example, if the program is modified to:

int f ( int n )
{
	int r = 1;
	if ( n == 3 ) {
		r = 5;
	}
	return ( r );
}

the initial value of r is used when n != 3, so no error is detected. However in:

int f ( int n )
{
	int r = 1;
	if ( n == 3 ) {
		r = 5;
	} else {
		r = 6;
	}
	return ( r );
}

the initial value of r is overwritten regardless of the result of the conditional, and hence is unused.

6.5. Variable which has not been set is used

This test also requires some flow analysis, for example in:

int f ( int n )
{
	int r;
	if ( n == 3 ) {
		r = 5;
	}
	return ( r );
}

the use of the variable r as a return value is reported because there are paths leading to this statement in which r is not set (i.e. when n != 3). However, in:

int f ( int n )
{
	int r;
	if ( n == 3 ) {
		r = 5;
	} else {
		r = 6;
	}
	return ( r );
}

r is always set before it is used, so no error is detected.

6.6. Variable shadowing

It is quite legal in C to have a variable in an inner scope, with the same name as a variable in an outer scope. These variables are distinct and whilst in the inner scope, the declaration in the outer scope is not visible - it is shadowed by the local variable of the same name. Confusion can arise if this was not what the programmer intended. The checker can therefore be configured to detect shadowing in three cases: a local variable shadowing a global variable; a local variable shadowing a local variable with a wider scope and a local variable shadowing a typedef name, by using:

#pragma TenDRA variable hiding analysis status

If status is on an error is raised when a local variable that shadows another variable is declared, if warning is used the error is replaced by a warning and the off option restores the default behaviour (shadowing is permitted and no errors are produced).

The directive:

#pragma TenDRA variable hiding analysis on

can be used to enable a check for hiding of other variables and, in member functions, data members, by local variable declarations.

6.7. Overriding the variable analysis

Although many of the problems discovered by the variable analysis are genuine mistakes, some may be as the result of deliberate decisions by the program writer. In this case, more information needs to be provided to the checker to convey the programmer's intentions. Four constructs are provided for this purpose: the discard variable, the set variable, the exhaustive switch and the non-returning function.

#pragma TenDRA discard x;

if ( n == 3 )
#pragma TenDRA discard x;
	puts ( "n is three" );

#pragma TenDRA keyword DISCARD for discard variable

DISCARD ( x );

#ifdef __TenDRA__
#pragma TenDRA keyword DISCARD for discard variable
#else
#define DISCARD(x) (( void ) 0 )
#endif

void f ( void )
{
	int i = 0;
	while ( i++ < 10 ) {
		puts ( "hello" );
	}
	while ( i++ < 10 ) {
		puts ( "goodbye" );
	}
}

void f ( int n )
{
	int r;
	if ( n != 0 ) r = n;
	if ( n > 2 ) {
		printf ( "%d\n", r );
	}
}

#pragma TenDRA set r;

SET ( r );

#pragma TenDRA keyword SET for set

char *f ( int n )
{
	char *r;
	switch ( n ) {
		case 1 : r = "one"; break;
		case 2 : r = "two"; break;
		case 3 : r = "three"; break;
	}
	return ( r );
}

....
switch ( n )
#pragma TenDRA exhaustive
{
	case 1 : r = "one"; break;
	....

#pragma TenDRA keyword EXHAUSTIVE for exhaustive

switch ( n ) EXHAUSTIVE {
	case 1 : r = "one"; break;

#ifdef __TenDRA__
#pragma TenDRA keyword EXHAUSTIVE for exhaustive
#else
#define EXHAUSTIVE
#endif

switch ( cond ) EXHAUSTIVE {
	// switch statement body
}

#pragma TenDRA exhaustive

#pragma TenDRA keyword identifier for exhaustive

#pragma TenDRA enum switch analysis on

enum bool { false = 0, true = 1 } ;

#pragma TenDRA fall into case allow

#pragma TenDRA keyword identifier for fall into case

extern void error ( const char * );
char *f ( int n )
{
	char *r;
	switch ( n ) {
		case 1 : r = "one"; break;
		case 2 : r = "two"; break;
		case 3 : r = "three"; break;
		default : error( "Illegal value" );
	}
	return ( r );
}

#pragma TenDRA type VOID for bottom

extern VOID error ( const char * );

#ifdef __TenDRA__
#pragma TenDRA type VOID for bottom
#else
typedef void VOID;
#endif

#include <stdlib.h>

int f ( int n )
{
	exit ( EXIT_FAILURE );
	return ( n );
}

#pragma TenDRA incompatible void return allow

7.1. Discarded function returns

Functions which return a value which is not used form the commonest instances of discarded values. For example, in:

#include <stdio.h>
int main ()
{
	puts ( "hello" );
	return ( 0 );
}

the function, puts, returns an int value, indicating whether an error has occurred, which is ignored.

7.2. Discarded computed values

A rarer instance of a discarded object, and one which is almost always an error, is where a value is computed but not used. For example, in:

int f ( int n )
{
	int r = 4;
	if ( n == 3 )
	{
		r == 5;
	}
	return ( r );
}

the value r == 5 is computed but not used. This is actually because it is a misprint for r = 5.

7.3. Unused static variables and procedures

The final example of discarded values, which perhaps more properly belongs with the variable analysis tests mentioned above, is for static objects which are unused in the source module in which they are defined. Of course this means that they are unused in the entire program. Such objects can usually be removed.

7.4. Discarded expressions

The directive:

#pragma TenDRA discard analysis on

can be used to enable a check for values which are calculated but not used. There are three checks controlled by this directive, each of which can be controlled independently. The directive:

#pragma TenDRA discard analysis (function return) on

checks for functions which return a value which is not used. The check needs to be enabled for both the declaration and the call of the function in order for a discarded function return to be reported. Discarded returns for overloaded operator functions are never reported. The directive:

#pragma TenDRA discard analysis (value) on

checks for other expressions which are not used. Finally, the directive:

#pragma TenDRA discard analysis (static) on

checks for variables with internal linkage which are defined but not used.

An unused function return or other expression can be asserted to be deliberately discarded by explicitly casting it to void or, equivalently, preceding it by a keyword introduced using the directive:

#pragma TenDRA keyword identifier for discard value

A static variable can be asserted to be deliberately unused by including it in list of identifiers in a directive of the form:

#pragma TenDRA suspend static identifier-list

7.5. Overriding the discard analysis

As with the variable analysis, certain constructs may be used to provide the checker with extra information about a program, to convey the programmer's intentions more clearly.

( void ) puts ( "hello" );

#pragma TenDRA keyword IGNORE for discard value

IGNORE puts ( "hello" );

#ifdef __TenDRA__
#pragma TenDRA keyword IGNORE for discard value
#else
#define IGNORE ( void )
#endif

#pragma TenDRA suspend static x y z

8.1. Preprocessor directives

By default, the TenDRA C checker understands those preprocessor directives specified by the ISO C standard, section 6.8, i.e. #if, #ifdef, #ifndef, #elif, #else, #endif, #error, #line and #pragma. As has been mentioned, #pragma statements play a significant role in the checker. While any recognised #pragma statements are processed, all unknown pragma statements are ignored by default. The check to detect unknown pragma statements is controlled by:

#pragma TenDRA unknown pragma permit

The options for permit are disallow (raise an error if an unknown pragma is encountered), warning (allow unknown pragmas with a warning), or allow (allow unknown pragmas without comment).

In addition, the common non-ISO preprocessor directives, #file, #ident, #assert, #unassert and #weak may be permitted using:

#pragma TenDRA directive dir allow

where dir is one of file, ident, assert, unassert or weak. If allow is replaced by warning then the directive is allowed, but a warning is issued. In either case, the modifier (ignore) may be added to indicate that, although the directive is allowed, its effect is ignored. Thus for example:

#pragma TenDRA directive ident (ignore) allow

causes the checker to ignore any #ident directives without raising any errors.

Finally, the directive dir can be disallowed using:

#pragma TenDRA directive dir disallow

Finally, the directive dir can be disallowed using:

#pragma TenDRA unknown directive allow

Any other unknown preprocessing directives cause the checker to raise an error in the default mode. The pragma may be used to force the checker to ignore such directives without raising any errors.

Disallow and warning variants are also available.

8.2. Indented Preprocessing Directives

The ISO C standard allows white space to occur before the # in a preprocessing directive, and between the # and the directive name. Many older preprocessors have problems with such directives. The checker's treatment of such directives can be set using:

#pragma TenDRA indented # directive permit

which detects white space before the # and:

#pragma TenDRA indented directive after # permit

which detects white space before the # and the directive name. The options for permit are allow, warning or disallow as usual. The default checking profile allows both forms of indented directives.

8.3. Multiple macro definitions

The ISO C standard states that, for two definitions of a function-like macro to be equal, both the spelling of the parameters and the macro definition must be equal. Thus, for example, in:

#define f( x ) ( x )
#define f( y ) ( y )

the two definitions of f are not equal, despite the fact that they are clearly equivalent. Tchk has an alternative definition of macro equality which allows for consistent substitution of parameter names. The type of macro equality used is controlled by:

#pragma TenDRA weak macro equality allow

where permit is allow (use alternative definition of macro equality), warning (as for allow but raise a warning), or disallow (use the ISO C definition of macro equality - this is the default setting).

More generally, the pragma:

#pragma TenDRA extra macro definition allow

allows macros to be redefined, both consistently and inconsistently. If the definitions are incompatible, the first definition is overwritten. This pragma has a disallow variant, which resets the check to its default mode.

8.4. Macro arguments

According to the ISO C standard, section 6.8.3, if a macro argument contains a sequence of preprocessing tokens that would otherwise act as a preprocessing directive, the behaviour is undefined. Tchk allows preprocessing directives in macro arguments by default. The check to detect such macro arguments is controlled by:

#pragma TenDRA directive as macro argument permit

where permit is allow, warning or disallow.

The ISO C standard, section 6.8.3.2, also states that each # preprocessing token in the replacement list for a function-like macro shall be followed by a parameter as the next preprocessing token in the replacement list. By default, if tdfc2 encounters a # in a function-like macro replacement list which is not followed by a parameter of the macro an error is raised. The checker's behaviour in this situation is controlled by:

#pragma TenDRA no ident after # permit

where the options for permit are allow (do not raise errors), disallow (default mode) and warning (raise warnings instead of errors).

8.5. Unmatched quotes

The ISO C standard, section 6.1, states that if a ' or " character matches the category of preprocessing tokens described as single non-whitespace-characters that do not lexically match the other preprocessing token categories, then the behaviour is undefined. For example:

#define a 'b

would result in undefined behaviour. By default the ' character is ignored by tdfc2. A check to detect such statements may be controlled by:

#pragma TenDRA unmatched quote permit

The usual allow, warning and disallow options are available.

8.6. Include depth

Most preprocessors set a maximum depth for #include directives (which may be limited by the maximum number of files which can be open on the host system). By default, the checker supports a depth equal to this maximum number. However, a smaller maximum depth can be set using:

#pragma TenDRA includes depth n

where n can be any positive integral constant.

8.7. Text after #endif

The ISO C standard, section 6.8, specifies that #endif and #else preprocessor directives do not take any arguments, but should be followed by a newline. In the default checking mode, tdfc2 raises an error when #endif or #else statements are not directly followed by a new line. This behaviour may be modified using:

#pragma TenDRA text after directive permit

where permit is allow (no errors are raised and any text on the same line as the #endif or #else statement is ignored), warning or disallow.

8.8. Text after #

The ISO C standard specifies that a # occuring outside of a macro replacement list must be followed by a new line or by a preprocessing directive and this is enforced by the checker in default mode. The check is controlled by:

#pragma TenDRA no directive/nline after ident permit

where permit may be allow, disallow or warning.

8.9. New line at end of file

The ISO C standard, section 5.1.1.2, states that source files must end with new lines. Files which do not end in new lines are flagged as errors by the checker in default mode. The behaviour can be modified using:

#pragma TenDRA no nline after file end permit

where permit has the usual allow, disallow and warning options.

8.10. Conditional Compilation

Tchk generally treats conditional compilation in the same way as other compilers and checkers. For example, consider:

#if expr
.... /* First branch */
#else
.... /* Second branch */
#endif

the expression, expr, is evaluated: if it is non-zero the first branch of the conditional is processed; if it is zero the second branch is processed instead.

Sometimes, however, tdfc2 may be unable to evaluate the expression statically because of the abstract types and expressions which arise from the minimum integer range assumptions or the abstract standard headers used by the tool (see target-dependent types in section 4.5). For example, consider the following ISO compliant program:

#include <stdio.h>
#include <limits.h>
int main ()
{
#if ( CHAR_MIN == 0 )
	puts ("char is unsigned");
#else
	puts ("char is signed");
#endif
	return ( 0 );
}

The TenDRA representation of the ISO API merely states that CHAR_MIN - the least value which fits into a char - is a target dependent integral constant. Hence, whether or not it equals zero is again target dependent, so the checker needs to maintain both branches. By contrast, any conventional compiler is compiling to a particular target machine on which CHAR_MIN is a specific integral constant. It can therefore always determine which branch of the conditional it should compile.

In order to allow both branches to be maintained in these cases, it has been necessary for tdfc2 to impose certain restrictions on the form of the conditional branches and the positions in which such target-dependent conditionals may occur. These may be summarised as:

• Target-dependent conditionals may not appear at the outer level. If the checker encounters a target-dependent conditional at the outer level an error is produced. In order to continue checking in the rest of the file an arbitrary assumption must be made about which branch of the conditional to process; tdfc2 assumes that the conditional is true and the first branch is used;

• The branches of allowable target-dependent conditionals may not contain declarations or definitions.

8.11. Target dependent conditional inclusion

One of the effects of trying to compile code in a target independent manner is that it is not always possible to completely evaluate the condition in a #if directive. Thus the conditional inclusion needs to be preserved until the installer phase. This can only be done if the target dependent #if is more structured than is normally required for preprocessing directives. There are two cases; in the first, where the #if appears in a statement, it is treated as if it were a if statement with braces including its branches; that is:

#if cond
	true_statements
#else
	false_statements
#endif

maps to:

if ( cond ) {
	true_statements
} else {
	false_statements
}

In the second case, where the #if appears in a list of declarations, normally gives an error. The can however be overridden by the directive:

#pragma TenDRA++ conditional declaration allow

which causes both branches of the #if to be analysed.

8.12. Unused headers

Header files which are included but from which nothing is used within the other source files comprising the translation unit, might just as well not have been included. Tchk can detect top level include files which are unnecessary, by analysing the tdfc2dump output for the file. This check is enabled by passing the -Wd,-H command line flag to tcc. Errors are written to stderr in a simple ascii form by default, or to the unified dump file in dump format if the -D command line option is used.

9.1. Including headers

The token syntax described in the previous annex provides the means of describing an API specification independently of any particular implementation of the API. Every object in the API specification is described using the appropriate #pragma token statement. These statements are arranged in TenDRA header files corresponding to the headers comprising the API. Each API consists of a separate set of header files. For example, if the ANSI C89 API is used, the statement:

#include <sys/types.h>

will lead to a header not found error, whereas the header will be found in the POSIX API.

Where relationships exist between APIs these have been made explicit in the headers. For example, the POSIX version of stdio.h consists of the ANSI version plus some extra objects. This is implemented by making the TenDRA header describing the POSIX version of stdio.h include the ANSI C89 version of stdio.h.

9.2. Specifying APIs to tcc

The API against which a program is to be checked is specified to tcc by means of a command-line option of the form -Yapi where api is the API name. For example, ANSI X3.159 is specified by -Yc89 (this is the default API) and POSIX 1003.1 is specified by -Yposix (for a full list of the supported APIs see Chapter 2).

Extension APIs, such as X11, require special attention. The API for a program is never just X11, but X11 plus some base API, for example, X11 plus POSIX or X11 plus XPG3. These composite APIs may be specified by, for example, passing the options -Yposix -Yx5_lib (in that order) to tcc to specify POSIX 1003.1 plus X11 (Release 5) Xlib. The rule is that base APIs, such as POSIX, override the existing API, whereas extension APIs, such as X11, extend it. The command-line option -info causes tcc to print the API currently in use. For example:

% tcc -Yposix -Yx5_lib -info file.c

will result in the message:

tcc: Information: API is X11 Release 5 Xlib plus POSIX (1003.1).

9.3. API Checking Examples

As an example of the TenDRA compiler's API checking capacities, consider the following program which prints the names and inode numbers of all the files in the current directory:

#include <stdio.h>
#include <sys/types.h>
#include <dirent.h>

int main ()
{
	DIR *d = opendir ( "." );
	struct dirent *e;
	if ( d = NULL ) return ( 1 );
	while ( e = readdir(d), e != NULL ) 
	{
		printf ( "%s %lu\n", e->d_name, e->d_ino );
	}
	closedir ( d );
	return ( 0 );
}

A first attempted compilation using strict checking:

% tcc -Xs a.c

results in messages to the effect that the headers <sys/types.h> and <dirent.h> cannot be found, plus a number of consequential errors. This is because tcc is checking the program against the default API, that is against the ANSI API, and the program is certainly not ANSI compliant. It does look as if it might be POSIX compliant however, so a second attempted compilation might be:

% tcc -Xs -Yposix a.c

This results in one error and three warnings. Dealing with the warnings first, the returns of the calls of printf and closedir are being discarded and the variable d has been set and not used. The discarded function returns are deliberate, so they can be made explicit by casting them to void. The discarded assignment to d requires a little more thought - it is due to the mistyping d = NULL instead of d == NULL on line 9. The error is more interesting. In full the error message reads:

"a.c":11 printf ( "%s %lu\n", e->d_name, e->d_ino!!!! ); Error:ISO[6.5.2.1]{ANSI[3.5.2.1]}: The identifier 'd_ino' is not a member of 'struct/union posix.dirent.dirent'. ISO[6.3.2.3]{ANSI[3.3.2.3]}: The second operand of '->' must be a member of the struct/union pointed to by the first.

That is, struct dirent does not have a field called d_ino. In fact this is true; while the d_name field of struct dirent is specified in POSIX, the d_ino field is an XPG3 extension (This example shows that the TenDRA representation of APIs is able to differentiate between APIs at a very fine level). Therefore a third attempted compilation might be:

% tcc -Xs -Yxpg3 a.c

This leads to another error message concerning the printf statement, that the types unsigned long and (the promotion of) ino_t are incompatible. This is due to a mismatch between the printf format string %lu and the type of e->d_ino. POSIX only says that ino_t is an arithmetic type, not a specific type like unsigned long. The TenDRA representation of POSIX reflects this abstract nature of ino_t, so that the potential portability error is detected. In fact it is impossible to give a printf string which works for all possible implementations of ino_t. The best that can be done is to cast e->d_ino to some fixed type like unsigned long and print that.

Hence the corrected, XPG3 conformant program reads:

#include <stdio.h>
#include <sys/types.h>
#include <dirent.h>

int main ()
{
	DIR *d = opendir ( "." );
	struct dirent *e;
	if ( d == NULL ) return ( 1 );
	while ( e = readdir(d), e != NULL )
	{
		( void ) printf ( "%s %lu\n", e->d_name, ( unsigned long ) e->d_ino );
	}
	( void ) closedir ( d );
	return ( 0 );
}

9.4. Redeclaring Objects in APIs

Of course, it is possible to redeclare the functions declared in the TenDRA API descriptions within the program, provided they are consistent. However, what constitutes a consistent redeclaration in the fully abstract TenDRA machine is not as straightforward as it might seem; an interesting example is malloc in the ANSI API. This is defined by the prototype:

void *malloc ( size_t );

where size_t is a target dependent unsigned integral type. The redeclaration:

void *malloc ();

is only correct if size_t is its own integral promotion, and therefore is not correct in general.

Since it is not always desirable to remove these redeclarations (some machines may not have all the necessary functions declared in their system headers) the TenDRA compiler has a facility to accept inconsistent redeclarations of API functions which can be enabled by using the pragma:

#pragma TenDRA incompatible interface declaration allow

This pragma supresses the consistency checking of re-declarations of API functions. Replacing allow by warning causes a warning to be printed. In both cases the TenDRA API description of the function takes precedence. The normal behaviour of flagging inconsistent redeclarations as errors can be restored by replacing allow by disallow in the pragma above. (There are also equivalent command-line options to tcc of the form -X:interface_decl=status, where status can be check, warn or dont.)

9.5. Defining Objects in APIs

Since the program API is meant to define the interface between what the program defines and what the target machine defines, the TenDRA compiler normally raises an error if any attempt is made to define an object from the API in the program itself. A subtle example of this is given by compiling the program:

#include <errno.h>
extern int errno;

with the ANSI API. ANSI states that errno is an assignable lvalue of type int, and the TenDRA description of the API therefore states precisely that. The declaration of errno as an extern int is therefore an inconsistent specification of errno, but a consistent implementation. Accepting the lesser of two evils, the error reported is therefore that an attempt has been made to define errno despite the fact that it is part of the API.

Note that if this same program is compiled using the POSIX API, in which errno is explicitly specified to be an extern int, the program merely contains a consistent redeclaration of errno and so does not raise an error.

The neatest workaround for the ANSI case, which preserves the declaration for those machines which need it, is as follows: if errno is anything other than an extern int it must be defined by a macro. Therefore:

#include <errno.h>
#ifndef errno
extern int errno;
#endif

should always work.

In most other examples, the definitions are more obvious. For example, a programmer might provide a memory allocator containing versions of malloc, free etc.:

#include <stdlib.h>

void *malloc ( size_t sz )
{
	....
}

void free ( void *ptr )
{
	....
}

If this is deliberate then the TenDRA compiler needs to be told to ignore the API definitions of these objects and to use those provided instead. This is done by listing the objects to be ignored using the pragma:

#pragma ignore malloc free ....

(also see section G.10). This should be placed between the API specification and the object definitions. The provided definitions are checked for conformance with the API specifications. There are special forms of this pragma to enable field selectors and objects in the tag namespace to be defined. For example, if we wish to provide a definition of the type div_t from stdlib.h we need to ignore three objects - the type itself and its two field selectors - quot and rem. The definition would therefore take the form:

#include <stdlib.h>
#pragma ignore div_t div_t.quot div_t.rem
typedef struct {
	int quot;
	int rem;
} div_t;

Similarly if we wish to define struct lconv from locale.h the definition would take the form:

#include <locale.h>
#pragma ignore TAG lconv TAG lconv.decimal_point 
....
struct lconv {
	char *decimal_point;
	....
};

to take into account that lconv lies in the tag name space. By defining objects in the API in this way, we are actually constructing a less general version of the API. This will potentially restrict the portability of the resultant program, and so should not be done without good reason.

9.6. Stepping Outside an API

Using the TenDRA compiler to check a program against a standard API will only be effective if the appropriate API description is available to the program being tested (just as a program can only be compiled on a conventional machine if the program API is implemented on that machine). What can be done for a program whose API are not supported depends on the degree to which the program API differs from an existing TenDRA API description. If the program API is POSIX with a small extension, say, then it may be possible to express that extension to the TenDRA compiler. For large unsupported program APIs it may be possible to use the system headers on a particular machine to allow for partial program checking (see section H.7).

For small API extensions the ideal method would be to use the token syntax described in Annex G to express the program API to the TenDRA compiler, however this is not currently encouraged because the syntax of such API descriptions is not yet firmly fixed. For the time being it may be possible to use C to express much of the information the TenDRA compiler needs to check the program. For example, POSIX specifies that sys/stat.h contains a number of macros, S_ISDIR, S_ISREG, and so on, which are used to test whether a file is a directory, a regular file, etc. Suppose that a program is basically POSIX conformant, but uses the additional macro S_ISLNK to test whether the file is a symbolic link (this is in COSE and AES, but not POSIX). A proper TenDRA description of S_ISLNK would contain the information that it was a macro taking a mode_t and returning an int, however for checking purposes it is sufficient to merely give the types. This can be done by pretending that S_ISLNK is a function:

#ifdef __TenDRA__
/* For TenDRA checking purposes only */
extern int S_ISLNK ( mode_t ); 
/* actually a macro */
#endif

More complex examples might require an object in the API to be defined in order to provide more information about it (see H.5). For example, suppose that a program is basically ANSI compliant, but assumes that FILE is a structure with a field file_no of type int (representing the file number), rather than a generic type. This might be expressed by:

#ifdef __TenDRA__
/* For TenDRA checking purposes only */
#pragma ignore FILE
typedef struct {
	/* there may be other fields here */
	int file_no;
	/* there may be other fields here */
} FILE;
#endif

The methods of API description above are what might be called example implementations rather than the abstract implementations of the actual TenDRA API descriptions. They should only be used as a last resort, when there is no alternative way of expressing the program within a standard API. For example, there may be no need to access the file_no field of a FILE directly, since POSIX provides a function, fileno, for this purpose. Extending an API in general reduces the number of potential target machines for the corresponding program.

9.7. Using the System Headers

One possibility if a program API is not supported by the TenDRA compiler is to use the set of system headers on the particular machine on which tcc happens to be running. Of course, this means that the API checking facilities of the TenDRA compiler will not be effective, but it is possible that the other program checking aspects will be of use.

The system headers are not, and indeed are not intended to be, portable. A simple-minded approach to portability checking with the system headers could lead to more portability problems being found in the system headers than in the program itself. A more sophisticated approach involves applying different compilation modes to the system headers and to the program. The program itself can be checked very rigorously, while the system headers have very lax checks applied.

This could be done directly, by putting a wrapper around each system header describing the mode to be applied to that header. However the mechanism of named compilation modes (see 2.2) provides an alternative solution. In addition to the normal -Idir command-line option, tcc also supports the option -Nname:dir, which is identical except that it also associates the identifier name with the directory dir. Once a directory has been named in this way, the name can be used in a directive:

#pragma TenDRA directory name use environment mode

which tells tcc to apply the named compilation mode, mode, to any files included from the directory, name. This is the mechanism used to specify the checks to be applied to the system headers.

The system headers may be specified to tcc using the -Ysystem command-line option. This specifies /usr/include as the directory to search for headers and passes a system start-up file to tcc. This system start-up file contains any macro definitions which are necessary for tcc to navigate the system headers correctly, plus a description of the compilation mode to be used in compiling the system headers.

In fact, before searching /usr/include, tcc searches another directory for system headers. This is intended to hold modified versions of any system headers which cause particular problems or require extra information. For example:

• A version of stdio.h is provided for all systems, which contains the declarations of printf and similar functions necessary for tcc to apply its printf-string checks (see 3.3.2).

• A version of stdlib.h is provided for all systems which includes the declarations of exit and similar functions necessary for tcc to apply its flow analysis correctly (see 5.7).

• Versions of stdarg.h and varargs.h are provided for all systems which work with tcc. Most system headers contain built-in functions which are recognised by cc (but not tcc) to deal with these.

The user can also use this directory to modify any system headers which cause problems. For example, not all system headers declare all the functions they should, so it might be desirable to add these declarations.

It should be noted that the system headers and the TenDRA API headers do not mix well. Both are parts of coherent systems of header files, and unless the intersection is very small, it is not usually possible to combine parts of these systems sensibly.

Even a separation, such as compiling some modules of a program using a TenDRA API description and others using the system headers, can lead to problems in the intermodular linking phase (see Chapter 9). There will almost certainly be type inconsistency errors since the TenDRA headers and the system headers will have different representations of the same object.

9.8. API usage analysis

The abstract standard headers provided with the tool are the basis for the API usage analysis checking on dump files described in Chapter 9. The declarations in each abstract header file are enclosed by the following pragmas:

#pragma TenDRA declaration block API_name begin
#pragma TenDRA declaration block end

API_name has a standard form e.g. api__ansi__stdio for stdio.h in the ANSI API.

This information is output in the dump format as the start and end of a header scope, i.e.

SSH		 position				ref_no = <API_name>
SEH		 position				ref_no

The first occurence of each identifier in the dump output contains scope information; in the case of an identifier declared in the abstract headers, this scope information will normally refer to a header scope. Since each use of the identifier can be traced back to its declaration, this provides a means of tracking API usage within the application when the abstract headers are used. The disadvantages of this method are that only APIs for which abstract headers are available can be used. Objects which are not part of the standard APIs are not available and if an application requires such an identifier (or indeed attempts to use a standard API identifier for which the appropriate header has not been included) the resulting errors may distort or even completely halt the dump output resulting in incomplete or incorrect analysis.

The second method of API analysis allows compilation of the application against the system headers, thereby overcoming the problems of non-standard API usage mentioned above. The dump of the application can be scanned to determine the identifiers which are used but not defined within the application itself. These identifiers form the program's external API with the system headers and libraries, and can be compared with API reference information, provided by dump output files produced from the abstract standard headers, to determine the applications API usage.

Analysis performed on the set of dump files produced for an entire application can detect the objects, types, etc. from external APIs which are used by the application. The API usage analysis is enabled by passing one or more -api_checkAPI flags to tcc where API may be any of the standard APIs listed in section 2.1. The -api_check_outFILE flag may be used to direct the API analysis information to the file FILE (by default it is written to stdout). The APIs used to perform API usage analysis may be different from those used to process the application. Annex G.8 contains details of the methods used to perform the API usage analysis.

10.1. Linking symbol table dump files

The amount of information about an object stored in a dump file depends on the compilation mode used to produce that file. For example, if extra prototype checks are enabled (see section 3.3), the dump file contains any information inferred about a function from its traditional style definition or from applications of that function. For example, if one file contains:

extern void f () ;
void g ()
{
	f ( "hello" ) ;
}

and another contained:

void f ( n )
int n ;
{
	return ;
}

then the inferred prototype:

void f WEAK ( char * ) ;

from the call of f would be included in the first dump file, whereas the weak prototype deduced from the definition of f:

void f WEAK ( int ) ;

would be included in the second. When these two dump files are linked, the inconsistency is discovered and an error is reported.

10.2. Linking C++ spec files

The overall compilation scheme controlled by tcc, as it relates to the C++ producer, can be represented as follows:

Each C++ source file, a.cc say, is processed using tcpplus to give an output TDF capsule, a.j, which is passed to the installer phase of tcc. The capsule is linked with any target dependent token definition libraries, translated to assembler and assembled to give a binary object file, a.o. The various object files comprising the program are then linked with the system libraries to give a final executable, a.out.

A C++ spec file is a dump of the C++ producer's internal representation of a translation unit. Such files can be written to, and read from, disk to perform such operations as intermodule analysis.

In addition to this main compilation scheme, tcpplus can additionally be made to output a C++ spec file for each C++ source file, a.K say. These C++ spec files can be linked, using tcpplus in its spec linker mode, to give an additional TDF capsule, x.j say, and a combined C++ spec file, x.K. The main purpose of this C++ spec linking is to perform intermodule checks on the program, however in the course of this checking exported templates which are defined in one module and used in another are instantiated. This extra code is output to x.j, which is then installed and linked in the normal way.

Note that intermodule checks, and hence intermodule template instantiations, are only performed if the -im option is passed to tcc.

The TenDRA checker is similar to the compiler except that it disables TDF output and has intermodule analysis enabled by default.

Note that the format of a C++ spec file is specific to the C++ producer and may change between releases to reflect modifications in the internal type system. The C producer has a similar dump format, called a C spec file, however the two are incompatible. If intermodule analysis between C and C++ source files is required then the tdfc2dump symbol table dump format should be used.

10.3. Template compilation

The C++ producer makes the distinction between exported templates, which may be used in one module and defined in another, and non-exported templates, which must be defined in every module in which they are used. As in the ISO C++ standard, the export keyword is used to distinguish between the two cases. In the past, different compilers have had different template compilation models; either all templates were exported or no templates were exported. The latter is easily emulated - if the export keyword is not used then no templates will be exported. To emulate the former behaviour the directive:

#pragma TenDRA++ implicit export template on

can be used to treat all templates as if they had been declared using the export keyword.