Defining C functions in the C Standard Library as macros

Question

I have been reading The Open Group Base Specifications and the Posix Programmers man pages on C headers and this phrase reappears a lot "The following shall be declared as functions and may also be defined as macros" and I am not exactly sure what that means. What is the point of creating a macro out of a declared function. Wouldn't that just create a namespace conflict? Also why would you even want to do that?

Answer 1

Macros never conflict with other namespaces; macros are processed first and automatically 'win'.

The introduction section of the C Standard Library section of the standard, section 7.1 Introduction — and particularly §7.1.2, §7.1.3, and ¶7.1.4 — cover many of the points.

There are some functions that might be implemented more efficiently by a macro without incurring the overhead of a full function call. The rules of the standard allow an implementation to define macros for such functions, subject to a number of caveats. One is that the arguments to the macro may not be used more than once; another is that there must be a function for every function defined in the standard, even if it is also implemented as a macro.

The rules allow for flexibility in implementation without over-burdening the implementors or the users of the implementation.

§7.1.2 Standard headers

¶4 … If used, a header shall be included outside of any external declaration or definition, and it shall first be included before the first reference to any of the functions or objects it declares, or to any of the types or macros it defines. However, if an identifier is declared or defined in more than one header, the second and subsequent associated headers may be included after the initial reference to the identifier. The program shall not have any macros with names lexically identical to keywords currently defined prior to the inclusion of the header or when any macro defined in the header is expanded.

¶5 Any definition of an object-like macro described in this clause shall expand to code that is fully protected by parentheses where necessary, so that it groups in an arbitrary expression as if it were a single identifier.

¶6 Any declaration of a library function shall have external linkage.

¶7.1.3 Reserved identifiers

1 Each header declares or defines all identifiers listed in its associated subclause, and optionally declares or defines identifiers listed in its associated future library directions subclause and identifiers which are always reserved either for any use or for use as file scope identifiers.

• All identifiers that begin with an underscore and either an uppercase letter or another underscore are always reserved for any use.

• All identifiers that begin with an underscore are always reserved for use as identifiers with file scope in both the ordinary and tag name spaces.

• Each macro name in any of the following subclauses (including the future library directions) is reserved for use as specified if any of its associated headers is included; unless explicitly stated otherwise (see 7.1.4).

• All identifiers with external linkage in any of the following subclauses (including the future library directions) and errno are always reserved for use as identifiers with external linkage.¹⁸⁴⁾

• Each identifier with file scope listed in any of the following subclauses (including the future library directions) is reserved for use as a macro name and as an identifier with file scope in the same name space if any of its associated headers is included.

¶2 No other identifiers are reserved. If the program declares or defines an identifier in a context in which it is reserved (other than as allowed by 7.1.4), or defines a reserved identifier as a macro name, the behavior is undefined.

¶3 If the program removes (with #undef) any macro definition of an identifier in the first group listed above, the behavior is undefined.

¹⁸⁴⁾ The list of reserved identifiers with external linkage includes math_errhandling, setjmp, va_copy, and va_end.

¶7.1.4 Use of library functions

¶1 Each of the following statements applies unless explicitly stated otherwise in the detailed descriptions that follow: If an argument to a function has an invalid value (such as a value outside the domain of the function, or a pointer outside the address space of the program, or a null pointer, or a pointer to non-modifiable storage when the corresponding parameter is not const-qualified) or a type (after promotion) not expected by a function with variable number of arguments, the behavior is undefined. If a function argument is described as being an array, the pointer actually passed to the function shall have a value such that all address computations and accesses to objects (that would be valid if the pointer did point to the first element of such an array) are in fact valid. Any function declared in a header may be additionally implemented as a function-like macro defined in the header, so if a library function is declared explicitly when its header is included, one of the techniques shown below can be used to ensure the declaration is not affected by such a macro. Any macro definition of a function can be suppressed locally by enclosing the name of the function in parentheses, because the name is then not followed by the left parenthesis that indicates expansion of a macro function name. For the same syntactic reason, it is permitted to take the address of a library function even if it is also defined as a macro.¹⁸⁵⁾ The use of #undef to remove any macro definition will also ensure that an actual function is referred to. Any invocation of a library function that is implemented as a macro shall expand to code that evaluates each of its arguments exactly once, fully protected by parentheses where necessary, so it is generally safe to use arbitrary expressions as arguments.¹⁸⁶⁾ Likewise, those function-like macros described in the following subclauses may be invoked in an expression anywhere a function with a compatible return type could be called.¹⁸⁷⁾ All object-like macros listed as expanding to integer constant expressions shall additionally be suitable for use in #if preprocessing directives.

¶2 Provided that a library function can be declared without reference to any type defined in a header, it is also permissible to declare the function and use it without including its associated header.

¹⁸⁵⁾ This means that an implementation shall provide an actual function for each library function, even if it also provides a macro for that function.

¹⁸⁶⁾ Such macros might not contain the sequence points that the corresponding function calls do.

¹⁸⁷⁾ Because external identifiers and some macro names beginning with an underscore are reserved, implementations may provide special semantics for such names. For example, the identifier _BUILTIN_abs could be used to indicate generation of in-line code for the abs function. Thus, the appropriate header could specify:

#define abs(x) _BUILTIN_abs(x)

for a compiler whose code generator will accept it. In this manner, a user desiring to guarantee that a given library function such as abs will be a genuine function may write

#undef abs

whether the implementation’s header provides a macro implementation of abs or a built-in implementation. The prototype for the function, which precedes and is hidden by any macro definition, is thereby revealed also.

^{Emphasis added to ¶7.1.4}

These rules outline the main points in the treaty between the implementor (of the compiler and, more especially, the C library) and the programmer using that implementation.

Answer 2

The functions in the standard library must exist as functions because you can use them even if you do not #include any standard header. That is, the linker must be able to find the function, and you are free to insert the declaration yourself, as long as it is the correct declaration and you do not include any header which declares the function.

However, some functions can more efficiently be implemented as macros. (putc and isdigit are two common examples.) If that is the case, the implementation is free to take advantage of it by also including the efficient macro definition.

Macro names and functions are not in the same namespace in C, so no conflict will be produced. The macro will be expanded where the function is used, which means the external function will not normally be used, but there are two important ways that a symbol defined as a "function-like" macro will not be macro-expanded:

• If the symbol is used within the macro definition, because C does not allow recursive macro expansion. This is useful for functions for which the common calling case can be a macro, using the library function as a fallback. (For example the ctype functions could be defined as macros which call the function if the current locale is not the C locale.

• If the macro name is used without a parenthesized argument list. This allows you to take the address of a function even if it has a macro implementation. You (or the standard library) can force the use of the function instead of a macro by using redundant parentheses: (isdigit)(my_char)