The Specification

1. What This Collection Is

This directory contains the normative specification of C, Ocean Edition I.

It is written at the level of detail an implementer needs. Every subject that ISO/IEC 9899 specifies for C is specified here for Ocean Edition I, either by defining the same rule, by defining a narrower rule, or by recording that the construct is not part of this edition.

This specification is a derivative work of ISO/IEC 9899:1999. Its clause organization, grammar, declarator model, library interface, and computational model are taken from that standard and then modified. Where a clause here is silent on something ISO C99 specifies, the ISO C99 rule applies. The derivation is deliberate and is described in clause 1.3.

Ocean Edition I also adopts selectively from later C standards where a facility passes the test in clause 1.4.1. It does not track any later standard and is not a subset of one.

It adds one facility of its own: namespaces, comprising namespace, #namespace, ::, and #import. This is the only surface syntax the edition adds, it passed the deliberately strict test in clause 1.5.1, and syntax.md section 5.1 records why the white papers were amended to permit it. A namespaced entity has a linkage name the specification fixes, so C code calls it by writing that name. The most visible adoptions are bool, true, and false as core language constructs, null and NULL as typed null constants owned by the language, and #pragma once as a required part of the language. The full catalogue, including what was considered and rejected, is in Annex G clause G.5.

The two white papers in the parent directory remain the governing design documents:

• ../syntax.md, the syntactic and philosophical normalization pass,
• ../behavior.md, the behavioral model.

This collection is beholden to those two documents. Where a clause here appears to contradict either white paper, the white paper wins and the clause is a defect to be reported and corrected.

2. How the Documents Are Organized

The clause numbering mirrors ISO/IEC 9899 so that a reader holding both specifications can move between them without a translation table. Clause 6 is split across several files because the language clause is large; the ISO subclause numbers are preserved in the filenames.

2.1 Front matter

2.2 The language

2.3 The library

2.4 Annexes

3. Reading Order

A first-time reader who wants the shape of the language should read the two white papers, then annex-g-divergences-from-c99.md, then the language clauses in order.

A reader who wants to know how this edition relates to the C standards should read 01-scope.md clauses 1.3, 1.4, and 1.5, then 02-normative-references.md, then Annex G clauses G.5 and G.6.

An implementer should read 04-conformance.md first, then clause 6 in order, then the annexes. Annexes B, C, D, and K contain the obligations that are easiest to overlook, and Annex K is the one most likely to require changes to an existing compiler's internals rather than to its front end.

A programmer porting existing C should read annex-h-migration-and-interoperation.md first.

4. The Ten Laws

The whole specification is an elaboration of ten laws stated in ../behavior.md.

1. Syntax means what it says.
2. Expressions keep their types.
3. Evaluation has an order.
4. Objects begin valid.
5. Arithmetic describes finite machines.
6. Target differences must be real.
7. Optimization does not define semantics.
8. Dangerous is allowed.
9. Existing C syntax is preferred.
10. Fewer categories are better.

An eleventh commitment sits alongside the ten and is stated in clause 4.10 rather than in a white paper: translation itself is deterministic. The same inputs produce the same bytes. The ten laws make a program's behavior predictable from its source, and clause 4.10 makes the artifact predictable from the build.

That commitment is what allows a programmer to measure their own work. Where a compiler may optimize differently between two builds, a benchmark cannot separate the effect of a change from the effect of the compiler having chosen differently that time. See annex-k-deterministic-translation.md clause K.0.1.

When a clause in this collection is ambiguous, resolve it in favor of the law it serves.

Law 9 is the one an adoption most often has to answer to, and clause 1.4.1 test 3 is where it does. None of the visible adoptions introduces a spelling a C programmer has to learn. bool, true, and false are already what programmers write once <stdbool.h> is included, NULL is already what they write for a null pointer, and #pragma once is already at the top of most headers. Promoting them changes what the language guarantees rather than what the source looks like, which is why C23's nullptr was adopted in substance and not in spelling.

The namespace addition answers to Law 9 differently, because it does introduce a spelling that is new to C. It earned that by the test in clause 1.5.1, and the argument is that it automates the prefix convention every large C program already writes by hand, produces the same linkage names that convention produces, and can be removed by renaming. syntax.md section 5.1 states the reasoning and the boundary.

5. Defect Reporting

A defect in this specification is any of the following:

• a clause that contradicts ../syntax.md or ../behavior.md,
• a clause that contradicts another clause,
• a construct that ISO/IEC 9899 specifies and this collection neither specifies nor explicitly removes,
• a behavior described as defined without a rule sufficient to determine the result,
• a diagnostic requirement that no implementation can satisfy.

Defects are recorded against the clause number, not the file name, because file organization may change while clause numbering is stable.