illumos-gate Documentation

To prevent ambiguity in function calls (like log(1)), use Pattern B for math functions and other functions commonly called with integer arguments. This pattern is required for compatibility with libstdc++ and avoids the failure mode where multiple type variants (float, double, long double) are pulled into the global namespace simultaneously.

Pattern B Structure

• Global Namespace (::): Contains only what the C standard defines (e.g., double log(double)).
• namespace std:
  • Contains the C-standard form via using ::log.
  • Contains C++-only type variant overloads (e.g., float and long double variants) as inlines defined directly within namespace std.

This ensures that when a user calls log(1), the C++ compiler can resolve the call using the integer-covering templates provided by the C++ library within namespace std, rather than encountering ambiguous overloads in the global namespace.

illumos uses the global-primary model for C system headers used in C++. This model ensures compatibility with modern C++ toolchains (like libstdc++) and aligns with the C and C++ standards.

Comparison of Models

• std-primary (Legacy): ISO C library functions are declared inside namespace std {}. The global namespace (::) is populated via using std::func declarations. This can lead to ambiguity (e.g., log(int) becoming ambiguous if multiple type variants are pulled into ::).
• global-primary (Current/Target): ISO C library functions are declared directly in the global namespace (::) via extern "C" {}. The std:: namespace is then populated via using ::func declarations.

Key Rules for Header Implementation

1. C Declarations: Always put C declarations in the global namespace (::).
2. namespace std: Populate this namespace only with names required by the C++ standard.
3. Extensions: Keep extension names (those gated on __EXTENSIONS__, _XOPEN_SOURCE, etc.) in the global namespace (::), never in namespace std.
4. Math Functions: Use Pattern B (see below) for math functions and functions commonly called with integer arguments to avoid ambiguity.

illumos headers follow a 'global-primary' namespace model. The global namespace (::) is the primary location for declarations, while std:: is secondary and populated only with what the C++ standard requires.

Each ISO header is organized into six distinct sections:

1. Unconditional C declarations: Standard C library functions declared with C linkage in the global namespace.
2. Conditional C declarations: Functions gated by environment macros (e.g., _C99_SOURCE, _XOPEN_SOURCE, __EXTENSIONS__) in the global namespace. Extension symbols are not aliased into namespace std.
3. C-linkage helpers for C++ only: Type-variant C functions (like acosf or acosl) declared in the global namespace under extern "C" but guarded by #ifdef __cplusplus. These are used by C++ inlines but have no purpose in C.
4. C++ overloaded inlines: Located in a separate extern "C++" block. Depending on the function type, these inlines are placed either in the global namespace (Pattern A) or omitted here to be placed in namespace std (Pattern B).
5. C++ overloads for conditionally-exposed functions: Type-variant inlines for functions declared in Section 2, placed in the global namespace and guarded by the same environment macros.
6. namespace std: Populated with standard-required names via using :: aliases. This is also where Pattern B inlines are defined.

/* 
 * Global-primary namespace model
 * --------------------------------
 * All C library function declarations go in the global namespace (::)
 * inside extern "C" {}. The C++ standard namespace (std::) is then
 * populated exclusively via "using ::" aliases, never by redeclaring
 * symbols inside "namespace std {}".
 */

When implementing C++ overloads in headers, choose between two patterns based on how the function is typically called:

Pattern A: Inlines in the global namespace (::)

• Usage: Place inlines in Section 4 within the extern "C++" block.
• Mechanism: Use using ::func in Section 6 (namespace std) to bring all type variant overloads into std:: at once.
• When to use: Use this when the function is unlikely to be called with integer arguments. For example, acos(1) is unambiguous even with type variants in the global namespace.

Pattern B: Inlines in namespace std only

• Usage: Do not provide inlines in Section 4. Instead, define the type-variant inlines directly inside namespace std in Section 6.
• Mechanism: using ::func in Section 6 brings only the C-standard form (e.g., double) into std::. The other variants (e.g., float, long double) exist only within std::.
• When to use: Use this for functions that are commonly called with integer arguments (such as math functions like log, sin, etc.). This prevents ambiguity; for example, log(1) will correctly resolve to the double version in std:: rather than being ambiguous among multiple overloads in the global namespace.

/* Pattern A: global namespace; acos(1) is unambiguous */
inline float       acos(float __x)       { return acosf(__x); }
inline long double acos(long double __x) { return acosl(__x); }

/* Pattern B functions have no inlines here; see Section 6 */

namespace std {
    using ::acos;            /* Pattern A: brings double+float+ldbl */

    using ::log;             /* Pattern B: double form only */
    inline float       log(float __x)       { return logf(__x); }
    inline long double log(long double __x) { return logl(__x); }
}

The SVR4 installation process executes several types of scripts provided within the package. These scripts are run at specific lifecycle stages:

1. Request Script: Executed early to allow the package to ask for user input or configuration. Results are stored in a response file.
2. Preinstall Script: Executed after the package is unpacked but before files are installed. Used for environment preparation or dependency validation.
3. Checkinstall Script: Executed to perform additional checks before the actual installation begins.
4. Postinstall Script: Executed after the files have been installed to perform final configuration or cleanup.

Execution Details:

• Scripts are typically found in the install/ directory of the package source or the pkgbin directory.
• The installation service may set a ULIMIT to prevent scripts from consuming excessive resources.
• If pkgverbose is enabled, scripts are executed with the -x flag (e.g., sh -x script).