14. Pragma directives

Pragma directives are a standard C mechanism allowing vendor-specific extensions to the C language while maintaining portability.

You can use pragma directives to control compiler behavior, such as suppressing warnings or placing objects in specific memory areas using custom sections.

Pragma directives are always enabled and can be used with either the #pragma preprocessor directive or the _Pragma preprocessor operator.

14.1. Pragma directives reference

This section details all available pragma directives.

Summary of pragmas

The following table summarizes the recognized pragma directives:

Pragma directive	Description
#pragma clang section	Control custom section for code or data
#pragma message	Generate custom warning
#pragma GCC warning	Generate custom warning
#pragma GCC error	Generate custom error
#pragma clang diagnostic	Control diagnostic messages inside a source file
#pragma require	Force inclusion of other module
#pragma rtattr	Define a runtime attribute

Note

Since Clang is the C front end, some pragmas are inherited and function similarly. This simplifies compiler switching, despite pragmas being vendor-specific extensions.

Description of pragma directives

section

The #pragma clang section directive assigns section names to functions, global, and static objects.

The compiler typically places global and static objects into predefined sections, but you can override this to control placement to a specific memory area.

The section names can be specified as:

#pragma clang section bss="myBSS" data="myData" rodata="myRodata" text="myText"

The section names can be reverted back to default name by supplying an empty string to the section kind, for example:

#pragma clang section bss="" data="" text="" rodata=""

The new section name applies to all functions, global and static objects that follow from the pragma directive.

You are not required to define a name for every section category. If you omit some, the most recently specified one is used.

The section attribute takes precedence over the clang section pragma directive; a section name specified with __attribute__((section(“myname”))) has precedence.

Note

Section names are not interpreted. For example, naming a section .bss.mySec does not mean it will be a BSS section name.

message

You can generate a custom warning with message pragma. In addition there are a couple of GCC variants of this supported:

// The following will generate warning messages
#pragma message "my own diagnostic message"
#pragma GCC warning "my own diagnostic message"

// This will give and error
#pragma GCC error "not supported"

diagnostics

You can control diagnostic messages in source code using pragmas, which is useful for temporarily disabling specific warnings in a section of code.

The pragma controls any command-line-configurable warning. Warnings can be set to ignored, warning, error, or fatal.

You can also push and pop the current warning state. This is useful when writing a header file that others will compile, as their warning flags are unknown.

In the example below, -Wextra-tokens is ignored for a few lines; diagnostics then revert to their previous state.

#if foo
#endif foo // warning: extra tokens at end of #endif directive

#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wextra-tokens"

#if foo
#endif foo // no warning

#pragma clang diagnostic pop

The push and pop pragmas will save and restore the full diagnostic state, regardless of how it was set.

require

The #pragma require directive ensures that a module is included at the link stage, even if no functions or data objects within it are called or referenced.

This is primarily for libraries that request code slices or objects. For example, the C library’s heap system uses a require pragma in its malloc() module to enable heap initialization during system startup:

#pragma require __call_heap_initialize

rtattr

The #pragma rtattr directive defines a runtime attribute within a C source file.

This is primarily for building libraries with alternative modules. While runtime attributes can be defined using the --rtattr command-line option, defining them in the source file may simplify build rules.

#pragma rtattr myAttribute "someValue"