Domain: C Language Standardization / Preprocessor Directives Expert Persona: Senior C Standards Analyst

Abstract:

This documentation outlines the syntax and semantics of the #embed preprocessor directive, introduced in C23 (ISO/IEC 9899:2024) for binary resource inclusion at translation time. The directive facilitates incorporating external data sources by replacing itself with a comma-separated sequence of integer constant expressions. The mechanism employs search paths similar, but distinct, to those used for standard file inclusion. Associated functionality is provided by the __has_embed preprocessor conditional inclusion macro, which evaluates resource availability and parameter compatibility. The standard defines specific required parameters (limit, prefix, suffix, if_empty) and mandates that the resulting integer sequence, under specific conditions (element width equals CHAR_BIT), should map bit-for-bit to the resource's binary content, enabling static initialization of character arrays with external binary data.

Binary Resource Inclusion (#embed and __has_embed) Summary (C23)

• Core Functionality: The #embed directive enables the inclusion of binary resources (data sources accessible from the translation environment) directly into the source code stream.
• Directive Replacement: Upon processing, #embed is replaced by a comma-separated list of integer constant expressions corresponding to the data bytes/elements of the resource. If this list is empty, the token sequence replacement is also empty.
• Resource Identification Syntax:
  • The directive supports two primary search mechanisms: bracketed (#embed <h-char-sequence>) and quoted (#embed "q-char-sequence"), with the latter potentially falling back to the bracketed search methodology.
  • A third syntax allows for macro replacement of pp-tokens before attempting to match the bracketed or quoted forms.
• __has_embed Conditional Macro:
  • This macro checks the availability of a specified resource and the support for passed parameters.
  • It evaluates to one of three specific values: __STDC_EMBED_FOUND__, __STDC_EMBED_EMPTY__, or __STDC_EMBED_NOT_FOUND__.
  • It is strictly limited to use within preprocessor conditional directives (#if, #elif, #ifdef, etc.).
• Resource Dimensions:
  • Implementation Resource Width: The implementation-defined total size of the located resource in bits.
  • Resource Width: Initially the implementation resource width, modifiable by the limit parameter. If zero, the resource is considered empty.
  • Embed Element Width: Default is CHAR_BIT, but can be modified by implementation-defined parameters. The Resource Width must be divisible by the Embed Element Width.
• Data Semantics:
  • The values of the expanded integer constant expressions are in the range $[0, 2^{\text{embed element width}})$.
  • Implementations are highly encouraged to map the binary data to the integer sequence such that initializing an array of character type (compatible with unsigned char, or char if non-negative) with the expansion results in data that compares bit-for-bit equal to data obtained via execution-time mechanisms (e.g., fread).
• Standard Embed Parameters: Four standard parameters are defined, each permitted at most once per directive.
  • limit(constant-expression): An integer constant expression that sets the maximum size of the resource inclusion (expression multiplied by element width) relative to the implementation resource width.
  • prefix(pp-balanced-token-sequence): Inserts the token sequence immediately before the resource data expansion if the resource is non-empty.
  • suffix(pp-balanced-token-sequence): Inserts the token sequence immediately after the resource data expansion if the resource is non-empty.
  • if_empty(pp-balanced-token-sequence): Replaces the entire #embed directive with the provided token sequence if the resource is determined to be empty.
• Error Handling: If the resource is not found or if an unsupported parameter is utilized, the program is considered ill-formed.