Annex C. Implementation-Defined Behavior

C.0 The Obligation

An implementation shall document its choice for every item in this annex.

The documentation shall be available to a programmer using the implementation, shall be specific enough to predict program behavior, and shall be versioned alongside the implementation.

The admission test. An item belongs in this annex only when supported targets genuinely differ. Historical specification indecision is not a target property. If every supported modern target can share one reasonable rule, the language defines it universally instead. See clause 0.3 and behavior.md section 112.

The list below is therefore much shorter than ISO C99 Annex J.3, and every entry names a real difference between real machines.

C.1 Translation

• How a diagnostic message is identified as diagnostic, and how it is distinguished from other output. Clause 3.17.
• The way a physical source file is mapped to a header name or to a source file for #include and for #import, in both the angle-bracket form and the quoted form. Clause 6.10.2 and clause 6.10.11.
• Whether an import is processed textually, structurally, incrementally, or from a cached representation. The result shall not depend on the choice. Clause 6.10.11.
• Which additional Unicode characters, if any, are accepted in identifiers, and what normalization is applied. Clause 6.4.2.
• The execution character set, where it is not UTF-8, and the mapping from the source character set to it. Clause 5.2.1.2.
• Which fixed translation limits exist, and their values. Annex B clause B.0.
• How #pragma once determines that two inclusions name the same source file. Its provision is required, and only the identity rule is implementation-defined. Clause 6.10.2.4.
• The meaning of every #pragma the implementation recognizes.
• The value of __OCEAN_VERSION__. Clause 6.10.8.1.
• The default declared translation timestamp, and any option that sets it. Annex K clause K.5.1.
• The path mapping mechanism, the form of a recorded path, and the path separator written into artifacts. Annex K clause K.6.
• The rule by which symbols, sections, and relocations are ordered in an artifact. Annex K clause K.10.
• The fixed value written into padding and reserved fields of an artifact. Annex K clause K.4.
• Every optimization budget, its unit, its default, the option that adjusts it, and the response to exhausting it. Annex K clause K.9.2.
• The circumstances in which the implementation refuses to translate. Annex K clause K.2.1.
• The algorithm used for an artifact digest. Annex K clause K.11.3.
• The spelling of the verification mode, and the conditions it varies between the two translations. Annex K clause K.11.2.
• Which environment variables the implementation treats as build configuration. Annex K clause K.3.2.
• Where the implementation does not perform the link itself, the linker it invokes. Annex K clause K.10.

C.2 Environment

• The name, type, and signature of the entry point in a freestanding environment. Clause 5.1.2.1.
• Any entry signature for main beyond the two required forms. Clause 5.1.2.2.
• The content of the program parameters argc and argv, and how the host supplies them. Clause 5.1.2.2.
• What constitutes an interactive device. Clause 5.1.2.3.
• The effect of program termination in a freestanding environment. Clause 5.1.2.1.
• The status returned to the host environment for values other than EXIT_SUCCESS and EXIT_FAILURE.

C.3 Types, Sizes, and Layout

• The selected target ABI, by name and version. Clause 5.2.4.1.
• The data model, and the width of short, int, long, long long, and pointers. Clause 5.2.4.2.
• The alignment requirement of every type. Clause 6.2.6.6.
• Byte ordering within a multibyte scalar. Clause 6.2.6.2.
• The layout and padding of structures and unions for the selected ABI. Clause 6.2.6.1.
• Bitfield allocation direction, storage unit size, boundary crossing behavior, and the treatment of a zero-width bitfield. Clause 6.7.2.2.
• The representation of long double. Clause 6.2.6.4.
• Whether the target supports unaligned access, and which alignments trap. Clause 6.2.6.6.
• The definition of size_t, ptrdiff_t, wchar_t, wint_t, sig_atomic_t, and clock_t.
• The width of time_t beyond the 64-bit minimum of clause 7.2.23, and the epoch it counts from.
• Which extended integer types are provided, and their conversion ranks. Clause 6.2.5.2.
• Whether complex arithmetic is provided. Clause 6.2.5.2.
• Whether thread storage duration is provided, and the memory model of any threads. Clause 5.1.2.4.

C.4 Pointers

• The result of converting a pointer to an integer type other than through uintptr_t, and of converting an integer to a pointer type. Clause 6.3.2.3.
• The result of converting a pointer to an object type into a pointer to a function type, and back. Clause 6.3.2.3.
• Whether the pointer representation carries metadata that a uintptr_t round trip would lose, and what the resulting limitation is. Clause 6.3.2.5.
• The representation of a null pointer, where it is not all-zero bytes, and the cost that imposes on default initialization. Clause 6.7.9.2.

C.5 Arithmetic

The following remain implementation-defined because targets genuinely differ. Everything else about arithmetic is defined by clause 6.5.

• The representation and range of the floating types. Clause 6.2.6.4.
• The rounding behavior of floating operations, and the value of FLT_ROUNDS.
• The value of FLT_EVAL_METHOD, meaning whether floating expressions are evaluated in a wider format. Clause 7.2.5.
• Whether the implementation conforms to Annex F, and which of its optional parts.
• The direction of rounding when an integer is converted to a floating type and the value is not exactly representable. Clause 6.3.1.4.
• Whether a narrowing floating conversion whose magnitude exceeds the destination range produces an infinity or something else, on an implementation not conforming to Annex F. Clause 6.3.1.5.

C.6 Traps and Diagnostics

• The trap mechanism, meaning what an implementation does when a defined trap occurs: which signal is raised if any, what the exit status is, what is written, and whether buffered output is flushed. Clause 0.3.
• Whether returning from a handler for a trap-raised signal resumes, terminates, or does something else. Clause 7.2.14.
• Which recommended diagnostics of Annex I clause I.3 the implementation produces by default.
• The name and behavior of any suppression spelling for the fallthrough diagnostic. Clause 6.8.4.2.

C.7 Library

• The set of library functions that are safe to call from a signal handler. Clause 7.2.14.
• Additional errno values beyond EDOM, ERANGE, and EILSEQ, and which functions set them. Clause 7.1.7.
• Whether text streams and binary streams differ, and how. Clause 7.2.17.
• The behavior of system, and what constitutes a command processor. Clause 7.2.18.
• Whether the reentrant functions strerror_r, strtok_r, gmtime_r, and localtime_r have behavior beyond what clause 7.2.19 and clause 7.2.23 require. Their names are fixed by those clauses.
• Whether checked variants are provided, and how a program selects them. Clause 7.1.7.6.
• The value of CLOCKS_PER_SEC.
• Which headers a freestanding implementation provides beyond the required set. Clause 7.1.4.

C.8 Locale-Specific Behavior

The following depend on the locale in effect. An implementation shall document the behavior of every locale it provides, including the "C" locale.

• The character classifications of <ctype.h> and <wctype.h> beyond those the "C" locale fixes.
• The decimal point character and the grouping used by the formatted input and output functions.
• The collation sequence used by strcoll and strxfrm.
• The set of locale names accepted by setlocale.
• The content of struct lconv in each locale.
• The formats produced by strftime for locale-dependent conversions.

Note. ISO C99 treats locale-specific behavior as a separate category. Ocean Edition I folds it into implementation-defined behavior, because the obligation is the same one: document what you chose.

C.9 Unspecified Behavior

This is the complete list of behaviors where this specification permits a choice and does not require the implementation to document which it makes. Nothing else in the language is unspecified.

• Whether two string literals with the same contents designate the same object. Clause 6.4.5.
• The order in which the elements of a program image are laid out in storage, and therefore the relative addresses of two independently declared objects.
• The values of allocated storage bytes before anything is stored into them. Reading them through a character type is defined and yields these values, under clause 6.2.4.3. Clause 7.2.18.
• The amount of storage an allocation function reserves beyond the requested size.
• Whether an implementation merges identical static const objects with the same value.

Design note. Each of these permits a real and valuable implementation technique, and none of them can be observed by a program that does not go looking. A proposal to add a sixth entry should be treated as a last resort, under behavior.md section 113.

C.10 What Is Not in This Annex

The following are implementation-defined in ISO C99 and are defined by Ocean Edition I. They are listed here so that an implementer reading the ISO annex does not carry them over.