6.7.4 Function specifiers

Previous Table of Contents "New C Standard" commentary

function-specifier:
                inline

1523 Function specifiers shall be used only in the declaration of an identifier for a function.

1524 An inline definition of a function with external linkage shall not contain a definition of a modifiable object with static storage duration, and shall not contain a reference to an identifier with internal linkage.

1525 In a hosted environment, the inline function specifier shall not appear in a declaration of main.

1526 A function declared with an inline function specifier is an inline function.

1527 The function specifier may appear more than once;

1528 the behavior is the same as if it appeared only once.

1529 Making a function an inline function suggests that calls to the function be as fast as possible.¹¹⁸⁾

1530 The extent to which such suggestions are effective is implementation-defined.¹¹⁹⁾

1531 Any function with internal linkage can be an inline function.

1532 For a function with external linkage, the following restrictions apply:

1533 If a function is declared with an inline function specifier, then it shall also be defined in the same translation unit.

1534 118) By using, for example, an alternative to the usual function call mechanism, such as “inline substitution”.

1535 Inline substitution is not textual substitution, nor does it create a new function.

1536 Therefore, for example, the expansion of a macro used within the body of the function uses the definition it had at the point the function body appears, and not where the function is called;

1537 and identifiers refer to the declarations in scope where the body occurs.

1538 Likewise, the function has a single address, regardless of the number of inline definitions that occur in addition to the external definition.

1539 119) For example, an implementation might never perform inline substitution, or might only perform inline substitutions to calls in the scope of an inline declaration.

1540 If all of the file scope declarations for a function in a translation unit include the inline function specifier without extern, then the definition in that translation unit is an inline definition.

1541 An inline definition does not provide an external definition for the function, and does not forbid an external definition in another translation unit.

1542 An inline definition provides an alternative to an external definition, which a translator may use to implement any call to the function in the same translation unit.

1543 It is unspecified whether a call to the function uses the inline definition or the external definition.¹²⁰⁾

1544 EXAMPLE The declaration of an inline function with external linkage can result in either an external definition, or a definition available for use only within the translation unit. A file scope declaration with extern creates an external definition. The following example shows an entire translation unit.


        inline double fahr(double t)
        {
                return (9.0 * t) / 5.0 + 32.0;
        }

        inline double cels(double t)
        {
                return (5.0 * (t - 32.0)) / 9.0;
        }

        extern double fahr(double);        // creates an external definition

        double convert(int is_fahr, double temp)
        {
                /* A translator may perform inline substitutions */
                return is_fahr ? cels(temp) : fahr(temp);
        }

Note that the definition of fahr is an external definition because fahr is also declared with extern, but the definition of cels is an inline definition. Because cels has external linkage and is referenced, an external definition has to appear in another translation unit (see 6.9); the inline definition and the external definition are distinct and either may be used for the call.

1545 Forward references: function definitions (6.9.1).

1546 120) Since an inline definition is distinct from the corresponding external definition and from any other corresponding inline definitions in other translation units, all corresponding objects with static storage duration are also distinct in each of the definitions.