Traditionally, C arrays are declared with an index that is either a fixed constant or empty. An array with a fixed constant index indicates to the compiler how much space to reserve for the array. An array declaration with an empty index is an incomplete type and indicates that the variable references a pointer to an array of indeterminate size.
The term conformant array parameter comes from Pascal; it refers to a function argument that is an array whose size is specified in the function declaration. Since C99, C has supported conformant array parameters by permitting array parameter declarations to use extended syntax. Subclause 220.127.116.11, paragraph 1, of C11 [ISO/IEC 9899:2011] summarizes the array index syntax extensions:
The [ and ] may delimit an expression or *. If they delimit an expression (which specifies the size of an array), the expression shall have an integer type. If the expression is a constant expression, it shall have a value greater than zero.
Consequently, an array declaration that serves as a function argument may have an index that is a variable or an expression. The array argument is demoted to a pointer and is consequently not a variable length array (VLA). Conformant array parameters can be used by developers to indicate the expected bounds of the array. This information may be used by compilers, or it may be ignored. However, such declarations are useful to developers because they serve to document relationships between array sizes and pointers. This information can also be used by static analysis tools to diagnose potential defects.
Subclause 18.104.22.168 of the C Standard [ISO/IEC 9899:2011] has several examples of conformant array parameters. Example 4 (paragraph 20) illustrates a variably modified parameter:
Example 4 illustrates a set of compatible function prototype declarators
Noncompliant Code Example
This code example provides a function that wraps a call to the standard
memset() function and has a similar set of arguments. However, although this function clearly intends that
p point to an array of at least
n chars, this invariant is not explicitly documented.
Noncompliant Code Example
This noncompliant code example attempts to document the relationship between the pointer and the size using conformant array parameters. However, the variable
n is used as the index of the array declaration before
n is itself declared. Consequently, this code example is not standards-compliant and will usually fail to compile.
Compliant Solution (GCC)
This compliant solution uses a GNU extension to forward declare the
n before using it in the subsequent array declaration. Consequently, this code allows the existing parameter order to be retained and successfully documents the relationship between the array parameter and the size parameter.
Compliant Solution (API change)
This compliant solution changes the function's API by moving the
n to before the subsequent array declaration. Consequently, this code complies with the C99 standard and successfully documents the relationship between the array parameter and the size parameter, but requires all callers to be updated.
API05-C-EX0: The extended array syntax is not supported by C++, or platforms that do not support C99, such as MSVC. Consequently, C programs that must support such platforms, including Windows, need not use conformant array parameters. One option for portable code that must support such platforms is to use macros:
Failing to specify conformant array dimensions increases the likelihood that another developer will invoke the function with out-of-range integers, which could cause an out-of-bounds memory read or write.
|[ISO/IEC 9899:2011]||Subclause 22.214.171.124, "Array Declarators"|
Subclause 126.96.36.199, "Function Declarators (Including Prototypes)"