This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

organization of C Extensions in manual


The page for Extensions to the C Language Family (https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html) is very long (60+ items) and completely unordered. This makes it hard to find things, even when you know they are there. I have taken a first shot at grouping these. Hopefully it can at least serve as the basis for discussion.

These section headings were just the general terms that first occurred to me. Feel free to propose more computer-y terminology. And yes, some of these topics are a stretch to be included in the sections in which I have placed them. Still, I believe this is better than what is there now.

Better section names and alternative groupings welcome.

Arrays and Vectors
    Designated Inits: Labeling elements of initializers.
Pointers to Arrays: Pointers to arrays with qualifiers work as expected.
    Subscripting: Any array can be subscripted, even if not an lvalue.
    Variable Length: Arrays whose length is computed at run time.
Vector Extensions: Using vector instructions through built-in functions.
    Zero Length: Zero-length arrays.

Attributes
    Attribute Syntax: Formal syntax for attributes.
Function Attributes: Declaring that functions have no side effects, or that they can never return.
    Inline: Defining inline functions (as fast as macros).
    Label Attributes: Specifying attributes on labels.
    Thread-Local: Per-thread variables.
    Type Attributes: Specifying attributes of types.
    Variable Attributes: Specifying attributes of variables.
    Volatiles: What constitutes an access to a volatile object.

BuiltIns
    __atomic Builtins: Atomic built-in functions with memory model.
    __sync Builtins: Legacy built-in functions for atomic memory access.
Cilk Plus Builtins: Built-in functions for the Cilk Plus language extension. Integer Overflow Builtins: Built-in functions to perform arithmetics and arithmetic overflow checking. Object Size Checking: Built-in functions for limited buffer overflow checking.
    Other Builtins: Other built-in functions.
Pointer Bounds Checker builtins: Built-in functions for Pointer Bounds Checker.
    Target Builtins: Built-in functions specific to particular targets.
x86 specific memory model extensions for transactional memory: x86 memory models.

Computed values
    Alignment: Inquiring about the alignment of a type or variable.
    Conditionals: Omitting the middle operand of a â?:â expression.
    Initializers: Non-constant initializers.
    Offsetof: Special syntax for implementing offsetof.
    Pointer Arith: Arithmetic on void-pointers and function pointers.
    Return Address: Getting the return or frame address of a function.
Statement Exprs: Putting statements and declarations inside expressions.
    Target Format Checks: Format checks specific to particular targets.
    Typeof: typeof: referring to the type of an expression.
    Variadic Macros: Macros with a variable number of arguments.

Constant Values
    Binary constants: Binary constants using the â0bâ prefix.
    Character Escapes: â\eâ stands for the character <ESC>.
Compound Literals: Compound literals give structures, unions or arrays as values.
    Escaped Newlines: Slightly looser rules for escaped newlines.
    Hex Floats: Hexadecimal floating-point constants.
    Labels as Values: Getting pointers to labels, and computed gotos.

Data types
    __int128: 128-bit integers---__int128.
    Complex: Data types for complex numbers.
    Decimal Float: Decimal Floating Types.
    Empty Structures: Structures with no members.
    Fixed-Point: Fixed-Point Types.
    Floating Types: Additional Floating Types.
    Half-Precision: Half-Precision Floating Point.
    Long Long: Double-word integers---long long int.

Naming
    Alternate Keywords: __const__, __asm__, etc., for header files.
    Cast to Union: Casting to union type from any member of the union.
    Dollar Signs: Dollar sign is allowed in identifiers.
Function Names: Printable strings which are the name of the current function.
    Incomplete Enums: enum foo;, with details to follow.
    Local Labels: Labels local to a block.
    Mixed Declarations: Mixing declarations and code.
    Named Address Spaces: Named address spaces.
    Unnamed Fields: Unnamed struct/union fields within structs/unions.

Misc
    C++ Comments: C++ comments are recognized.
    Case Ranges: `case 1 ... 9' and such.
    Constructing Calls: Dispatching a call to another function.
    Function Prototypes: Prototype declarations and old-style definitions.
    Nested Functions: As in Algol and Pascal, lexical scoping of functions.
    Pragmas: Pragmas accepted by GCC.
Using Assembly Language with C: Instructions and extensions for interfacing C with assembler.

In a related question, should we change the "Extensions" page to only contain these section headers ("Data types", "Builtins" etc) and make submenus (ie new pages) out of the items under them? From a strict "how docs should be written" point of view, perhaps we should. But from a "help people find things" point of view, perhaps not. Opinions?

dw


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]