5.3.2 Stubs

A C application's namespace should not be polluted with non-ANSI and non-POSIX functions from the C libraries, unless the application explicitly uses these symbols. An example of a non-ANSI and non-POSIX function is uclock (@xref{uclock, , uclock, libc}).

But what happens if you wish to call a non-ANSI and/or non-POSIX function from C library code? The actual implementation is placed in the C library's private namespace with a stub function that calls the implementation. Consider uclock --- the library would use the __uclock function internally, but application code would use the stub uclock.

Functions that are stubbed have an entry in the include file `libc/stubs.h', e.g.:

#define uclock __uclock

Any C library sources defining or calling the implementation should include `libc/stubs.h' as the first include file. This is so that we can refer to, e.g., uclock as uclock in the library code, but the library code will actually define/call, e.g., __uclock and will not pollute the application namespace.

The stub files are assembly language files generated automagically from `libc/stubs.h' as part of the C library build process.

NB: The private name, e.g., __uclock, is not part of the published API.