1.. _language_c:
2
3C Language Support
4##################
5
6C is a general-purpose low-level programming language that is widely used for
7writing code for embedded systems.
8
9Zephyr is primarily written in C and natively supports applications written in
10the C language. All Zephyr API functions and macros are implemented in C and
11available as part of the C header files under the :file:`include` directory, so
12writing Zephyr applications in C gives the developers access to the most
13features.
14
15The ``main()`` function must have the return type of ``int`` as Zephyr
16applications run in a "hosted" environment as defined by the C
17standard. Applications must return zero (0) from main. All non-zero return
18values are reserved.
19
20.. _c_standards:
21
22Language Standards
23******************
24
25Zephyr does not target a specific version of the C standards; however, the
26Zephyr codebase makes extensive use of the features newly introduced in the
271999 release of the ISO C standard (ISO/IEC 9899:1999, hereinafter referred to
28as C99) such as those listed below, effectively requiring the use of a compiler
29toolchain that supports the C99 standard and above:
30
31* inline functions
32* standard boolean types (``bool`` in ``<stdbool.h>``)
33* fixed-width integer types (``[u]intN_t`` in ``<stdint.h>``)
34* designated initializers
35* variadic macros
36* ``restrict`` qualification
37
38Some Zephyr components make use of the features newly introduced in the 2011
39release of the ISO C standard (ISO/IEC 9899:2011, hereinafter referred to as
40C11) such as the type-generic expressions using the ``_Generic`` keyword. For
41example, the :c:func:`cbprintf` component, used as the default formatted output
42processor for Zephyr, makes use of the C11 type-generic expressions, and this
43effectively requires most Zephyr applications to be compiled using a compiler
44toolchain that supports the C11 standard and above.
45
46In summary, it is recommended to use a compiler toolchain that supports at
47least the C11 standard for developing with Zephyr. It is, however, important to
48note that some optional Zephyr components and external modules may make use of
49the C language features that have been introduced in more recent versions of
50the standards, in which case it will be necessary to use a more up-to-date
51compiler toolchain that supports such standards.
52
53.. _c_library:
54
55Standard Library
56****************
57
58The `C Standard Library`_ is an integral part of any C program, and Zephyr
59provides the support for a number of different C libraries for the applications
60to choose from, depending on the compiler toolchain being used to build the
61application.
62
63.. toctree::
64   :maxdepth: 2
65
66   common_libc.rst
67   minimal_libc.rst
68   newlib.rst
69   picolibc.rst
70
71.. _`C Standard Library`: https://en.wikipedia.org/wiki/C_standard_library
72
73.. _c_library_formatted_output:
74
75Formatted Output
76****************
77
78C defines standard formatted output functions such as ``printf`` and
79``sprintf`` and these functions are implemented by the C standard
80libraries.
81
82Each C standard library has its own set of requirements and configurations for
83selecting the formatted output modes and capabilities. Refer to each C standard
84library documentation for more details.
85
86.. _c_library_dynamic_mem:
87
88Dynamic Memory Management
89*************************
90
91C defines a standard dynamic memory management interface (for example,
92:c:func:`malloc` and :c:func:`free`) and these functions are implemented by the
93C standard libraries.
94
95While the details of the dynamic memory management implementation varies across
96different C standard libraries, all supported libraries must conform to the
97following conventions. Every supported C standard library shall:
98
99* manage its own memory heap either internally or by invoking the hook
100  functions (for example, :c:func:`sbrk`) implemented in :file:`libc-hooks.c`.
101
102* maintain the architecture- and memory region-specific alignment requirements
103  for the memory blocks allocated by the standard dynamic memory allocation
104  interface (for example, :c:func:`malloc`).
105
106* allocate memory blocks inside the ``z_malloc_partition`` memory partition
107  when userspace is enabled. See :ref:`memory_domain_predefined_partitions`.
108
109For more details regarding the C standard library-specific memory management
110implementation, refer to each C standard library documentation.
111
112.. note::
113   Native Zephyr applications should use the :ref:`memory management API
114   <memory_management_api>` supported by the Zephyr kernel such as
115   :c:func:`k_malloc` in order to take advantage of the advanced features
116   that they offer.
117
118   C standard dynamic memory management interface functions such as
119   :c:func:`malloc` should be used only by the portable applications and
120   libraries that target multiple operating systems.
121