6. Application Programming Interfaces

  1. 6.1. ANSI C standard functions
  2. 6.2. Common exceptional cases
    1. 6.2.1. c89.setjmp.setjmp
    2. 6.2.2. c89.setjmp.longjmp
    3. 6.2.3. ~alloca
    4. 6.2.4. c89.stdarg.va_list,
      c89.stdarg.__va_start,
      c89.stdarg.va_arg,
      c89.stdarg.va_end

Application Programming Interfaces are typically specified with a C mapping, which define the required contents for C header files which a portable C program must include by name to gain access to target specific implementations of an API library. The TDF approach to API specification includes using a #pragma token syntax within architecture neutral C header files, such that all implementation dependencies are encapsulated by API specific tokens. These API tokens are the TDF representation of the API. Both the API library and API token definitions are required before a TDF program using the API can be installed on any particular platform.

Platform specific definitions for API tokens are produced automatically, with few exceptions, for any platform with a conformant implementation of the API. This is achieved by a token library building process which analyses the architecture neutral header files for the API concerned, together with the platform specific header files that provide normal (non-TDF) C access to the API. The few exceptions occur where the platform specific header files have been written to make use of specific C compiler built-in features, typically recognised by identifiers with a prefix such as __builtin_. Such cases are very likely to require explicit recognition of the corresponding token name in TDF installers.

Generally, API token names and specifications are not detailed in this token register. The token specifications are clearly dependent on the associated API specifications. Authority for controlling the actual API token names, and the relationship between API tokens and the various API standardisation authorities, remain separate subjects of discussion.

Names and specifications are given or implied below for those API tokens which frequently require built-in support from installers, and for other cases where an installer may be able to produce better code than could be achieved by normal token expansion, for example by inlining standard function calls.

6.1. ANSI C standard functions

The set of tokens implied below all have the form:

c89.header.function

... :	 ...
	-> EXP

Tokens are defined for all cases where header is ctype or string or math or stdlib, and function is the name of a non-ellipsis function specified in the ANSI C standard library, declared within the corresponding header <header.h>. (Note that ellipsis functions, such as printf, cannot be represented as tokens since they may take a variable number of arguments.)

These tokens have arguments all of SORT EXP, whose number and shape, and token result shape, all correspond to the implementation shape of the named ANSI C standard library function parameters and result. For the few cases where the function is specified not to return (e.g. c89.stdlib.abort), the result shape may be either TOP or BOTTOM.

6.2. Common exceptional cases

6.2.1. c89.setjmp.setjmp

jb:	EXP
	-> EXP

c89.setjmp.setjmp is a token which has the semantics and argument and result implementation shapes corresponding to the ANSI C macro setjmp declared within <setjmp.h>.

6.2.2. c89.setjmp.longjmp

jb:	EXP
v:	EXP
	-> EXP

c89.setjmp.longjmp is a token which has the semantics and argument implementation shapes corresponding to the ANSI C macro longjmp declared within <setjmp.h>. The result shape may be either TOP or BOTTOM.

6.2.3. ~alloca

i:	EXP
	-> EXP

~alloca is a token which has the semantics and argument and result implementation shapes corresponding to the BSD specified function alloca.

6.2.4. c89.stdarg.va_list,
c89.stdarg.__va_start,
c89.stdarg.va_arg,
c89.stdarg.va_end

These four tokens are identical to the Interface Tokens ~va_list, ~__va_start, ~va_arg and ~va_end respectively.