

*****************
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.

Pragma directives reference
===========================

This section details all available pragma directives.

Summary of pragmas
------------------

The following table summarizes the recognized pragma directives:

.. table::
 :widths: 2 3
 :column-dividers: none single none

 +-----------------------------+-----------------------------------------+
 |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.


.. _section-pragma:

Description of pragma directives
--------------------------------

.. index:: section; pragma directive, pragma directive; section

``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:

.. code-block:: C

   #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:

.. code-block:: C

   #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.


.. index:: message; pragma directive, pragma directive; message
.. index:: warning; pragma directive, pragma directive; warning
.. index:: error; pragma directive, pragma directive; error

``message``
^^^^^^^^^^^

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

.. code-block:: C

   // 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"


.. index:: diagnostics; pragma directive, pragma directive; diagnostics

``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.

.. code-block:: C

   #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.


.. index:: require; pragma directive, pragma directive; require

``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:

.. code-block:: C

   #pragma require __call_heap_initialize

.. index:: rtattr; pragma directive, pragma directive; rtattr
.. index:: runtime attribute; pragma directive, pragma directive; runtime attribute

``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.

.. code-block:: C

   #pragma rtattr myAttribute "someValue"
