5. Environment

5.1 Conceptual Models

5.1.1 Translation Environment

5.1.1.1 Program structure

A program consists of one or more translation units, translated separately or together, and then combined by a linking process into an executable program image.

A translation unit is a source file together with everything it includes, after conditional inclusion has removed the source lines that do not apply.

A translation unit may refer to entities defined in another translation unit through external declarations. See clause 6.9.

ISO C99 mapping: 5.1.1.1.

5.1.1.2 Translation phases

Ocean Edition I defines translation as a pipeline of six phases. A conforming implementation shall behave as if the phases occur in this order, and may implement them in any way that produces the same result.

1. source intake
2. directive processing
3. lexical analysis
4. syntactic analysis
5. semantic normalization
6. code generation

Phase 1: source intake.

Source text is read as UTF-8. See clause 5.2.1.

A backslash immediately followed by a newline is deleted, splicing the two physical lines into one logical line. Splicing occurs before any other processing of line content.

A source file that does not end in a newline is accepted, and behaves as though a final newline were present.

Line endings are normalized. A carriage return followed by a line feed, a bare line feed, and a bare carriage return each denote one line ending. See behavior.md section 4.

No trigraph replacement occurs, because trigraphs are not part of this edition. See clause 5.2.1.1.

Phase 2: directive processing.

The source is decomposed into preprocessing tokens and sequences of whitespace. Preprocessing directives are executed, macro invocations are expanded, and _Pragma operators are executed. Included files are processed by phases 1 and 2 recursively, and the result replaces the directive.

An imported header is processed by phases 1 through 5 as a complete source file, in its own macro environment, and contributes its declarations and its exported macros rather than its text. See clause 6.10.11.

The namespace governing each source file is established in this phase, from a #namespace directive where one is present. See clause 6.10.10.

Comments are replaced by one space each. A comment does not span a directive boundary in a way that changes which directive is seen; comment removal is complete before directives are recognized.

Phase 3: lexical analysis.

Each preprocessing token is converted into a token. Adjacent string literal tokens are concatenated. See clause 6.4.5.

Phase 4: syntactic analysis.

Tokens are parsed according to the grammar of annex-a-grammar.md. The parser has access to declaration information, because typedef names require it. That requirement is accepted rather than designed around. See syntax.md section 21.

Phase 5: semantic normalization.

Declarations are resolved, namespace membership and linkage names are determined, types are computed, constraints are checked, constant expressions are evaluated, conversions are made explicit, evaluation order is fixed, default initialization is materialized, and trap points are placed.

Every semantic guarantee of this edition is established in this phase. No later phase decides a question this specification has answered. See syntax.md section 55.

Phase 6: code generation.

The normalized program is lowered to the target. Optimization occurs here, subject to clause 4.7 and to the determinism requirements of Annex K clause K.9.

Determinism of the pipeline.

Every phase is a function of its input. Given the same translation input closure, each phase produces the same result, and the artifacts produced by phase 6 are byte-for-byte identical. An implementation may execute phases concurrently, incrementally, or out of order where the result is unaffected, and shall not let the choice affect the output. See clause 4.10.

Difference: ISO C99 defines eight translation phases and places string concatenation, escape-sequence conversion, and character-set mapping among them. Ocean Edition I folds those steps into the phases above and drops the phases whose only purpose was to describe trigraph replacement and source character-set mapping. The observable result for source that contains no removed construct is identical. See syntax.md section 54.

ISO C99 mapping: 5.1.1.2.

5.1.1.3 Diagnostics

An implementation shall produce at least one diagnostic message for any translation unit containing a violation of a syntax rule or constraint, as required by clause 4.3.

ISO C99 mapping: 5.1.1.3.

5.1.2 Execution Environments

Two execution environments are defined: freestanding and hosted. In both, program startup occurs when a designated function is called by the execution environment.

Objects with static storage duration receive their initial values before program startup, as required by clause 6.7.9.

ISO C99 mapping: 5.1.2.

5.1.2.1 Freestanding environment

In a freestanding environment, program startup is implementation-defined, including the name, type, and signature of the entry function.

Library facilities available to a freestanding program are limited to the headers of clause 7.1.5.

The effect of program termination in a freestanding environment is implementation-defined.

ISO C99 mapping: 5.1.2.1.

5.1.2.2 Hosted environment

Program startup.

The entry function is main. It shall be defined in one of these forms:

int main(void)
{
	...
}

int main(int argc, char **argv)
{
	...
}

An implementation may accept additional forms and shall document them.

main shall not be declared static, shall not be declared inline, and shall not be called by the program itself. Calling main recursively is a constraint violation, because its arguments and its return path belong to the execution environment.

Program parameters.

If main is defined with parameters:

• argc is nonnegative,
• argv[argc] is a null pointer,
• if argc is greater than zero, argv[0] through argv[argc - 1] are pointers to the initial characters of null-terminated multibyte strings representing the program parameters,
• if argc is greater than zero, argv[0] represents the program name, and is an empty string if the name is not available from the host,
• the strings and the array are modifiable by the program, and retain their last-stored values for the whole of program execution.

The parameters are supplied by the host environment. Their content is implementation-defined.

Program termination.

If the return type of main is compatible with int, returning from the initial call to main is equivalent to calling exit with the returned value.

Reaching the closing brace of main without executing a return statement is equivalent to return 0;. This is the only function for which falling off the end is defined. See clause 6.9.1 and behavior.md section 40.

ISO C99 mapping: 5.1.2.2.

5.1.2.3 Program execution

The semantic descriptions in this specification describe the behavior of an abstract machine in which issues of optimization are irrelevant.

Observable behavior consists of:

• accesses to volatile-qualified objects, performed in the order the program specifies,
• data written to files at the point of program termination,
• the prompting and input dynamics of interactive devices described below,
• the occurrence and identity of the first defined trap, if any occurs.

An implementation may perform any transformation that preserves observable behavior. See clause 4.7.

Evaluation order.

The abstract machine evaluates subexpressions from left to right unless the syntax of the construct specifies a different control dependency. This is a language rule and not an implementation freedom. See clause 6.5.0.1 and annex-e-evaluation-order.md.

Difference: ISO C99 leaves the order of evaluation of subexpressions and of function arguments unspecified, and describes their interaction through sequence points. Ocean Edition I fixes the order and has no sequence points. See behavior.md section 104.

Floating-point contraction.

An implementation shall not contract a floating-point expression into an operation with different rounding behavior unless the program enables contraction through the pragma of clause 7.2.6. The default is off, because a silently different result is a semantic difference rather than an optimization.

Interactive devices.

At program startup and at the completion of a call to a function that reads from an interactive device, output that has been written to an interactive stream shall have appeared. What constitutes an interactive device is implementation-defined.

ISO C99 mapping: 5.1.2.3.

5.1.2.4 Concurrent execution

Ocean Edition I does not define a threading model or a memory model for concurrent execution.

An implementation may provide threads as an extension. If it does, it shall document the memory model those threads obey.

The following are stated so that no reader infers a guarantee this edition does not make:

• volatile does not imply atomicity, mutual exclusion, or inter-thread ordering. See clause 6.7.3.4.
• Defined evaluation order applies within a single execution of a single thread. It says nothing about the interleaving of two threads.
• Two threads accessing distinct memory locations do not interfere. Two threads accessing the same memory location without an implementation-provided synchronization operation produce a result this specification does not define.

ISO C99 mapping: new. ISO C99 has no concurrency clause; the subject is addressed here to prevent inference from the volatile rules.

5.2 Environmental Considerations

5.2.1 Character Sets

Two character sets are relevant: the source character set, in which source files are written, and the execution character set, in which character constants and string literals are interpreted at execution time.

The source character set is Unicode, encoded as UTF-8.

The basic character set consists of the 26 uppercase Latin letters, the 26 lowercase Latin letters, the 10 decimal digits, the space character, the control characters representing horizontal tab, vertical tab, and form feed, the line ending, and the following graphic characters:

! " # % & ' ( ) * + , - . / :
; < = > ? [ \ ] ^ _ { | } ~ $ @ `

An implementation shall accept the basic character set directly, without any escape or substitution mechanism. See behavior.md section 4.

The execution character set includes the basic character set, and includes a null character whose value is zero and which terminates a string.

ISO C99 mapping: 5.2.1.

5.2.1.1 Trigraphs and alternate spellings

Trigraph sequences are not part of Ocean Edition I. A source sequence such as ??= is two question marks followed by an equals sign, with no replacement performed.

Digraph spellings such as <: and %: are not part of Ocean Edition I. The punctuator is spelled with the character it means.

The iso646.h alternative operator spellings are not part of the core language. See clause 7.2.9.

Design note. These mechanisms existed so that C could be written on keyboards and in character sets that lacked C punctuation. Every supported target has the punctuation. Source code should contain the characters it means. See syntax.md section 44.

ISO C99 mapping: 5.2.1.1, removed.

5.2.1.2 Multibyte characters

Source text is UTF-8, so a single character may occupy more than one byte in the source file.

A UTF-8 sequence in a string literal is preserved as the corresponding bytes of the execution character set when the execution character set is UTF-8, which is the default and is what an implementation should provide. An implementation that uses a different execution character set shall document the mapping.

The multibyte character model of the library, including shift states, is described in clause 7.2.24. Ocean Edition I does not require a stateful encoding, and an implementation targeting UTF-8 has no shift states to track.

ISO C99 mapping: 5.2.1.2.

5.2.2 Character Display Semantics

The following escape sequences produce the indicated effect on a display device:

The behavior of a backspace or tabulation at the edge of a display area is implementation-defined.

ISO C99 mapping: 5.2.2.

5.2.3 Signals and Interrupts

Functions may be interrupted by a signal, and may be called by a signal handler.

Signal handling in Ocean Edition I follows clause 7.2.14. The set of objects a handler may safely access is stated there rather than left to folklore.

ISO C99 mapping: 5.2.3.

5.2.4 Target Data Models and Limits

5.2.4.1 Target ABI selection

Every translation selects a target ABI. The selected ABI determines:

• the size and alignment of every primitive type,
• the layout and padding of every structure and union,
• bitfield allocation direction, container size, and boundary behavior,
• endianness,
• calling convention, including how aggregates and variadic arguments are passed,
• the representation of a null pointer,
• the width of an address.

Once an ABI is selected, no layout freedom remains for the implementation. An implementation shall document which ABI it selected and shall provide a way for the programmer to see that choice. See behavior.md section 23.

5.2.4.2 Data models

An implementation shall document its data model. The common data models and their type widths in bits are:

An implementation may support a data model not listed, and shall document its widths.

Ocean Edition I does not redefine the widths of the ordinary integer types, because doing so would create ABI incompatibility for no semantic gain. Programs that need a specific width use the exact-width types of clause 7.2.20. See syntax.md section 33.

5.2.4.3 Translation limits

An implementation shall be able to translate and execute at least one program that meets every limit in annex-b-implementation-limits.md clause B.1.

An implementation should not impose a fixed limit where a limit proportional to available storage is achievable. Where a fixed limit exists, the implementation shall document it.

ISO C99 mapping: 5.2.4.1.

5.2.4.4 Numerical limits

An implementation shall define the macros of <limits.h> and <float.h> as required by clause 7.2.8 and clause 7.2.5, with values consistent with the selected data model and with clause 6.2.6.

Because Ocean Edition I integers are two's complement with no padding bits, the minimum and maximum macros of a signed integer type of width N are exactly -2^(N-1) and 2^(N-1) - 1. An implementation shall not report a narrower range in order to describe a target that does not exist.

ISO C99 mapping: 5.2.4.2.