.. _c_library_minimal:

Minimal libc
############

The most basic C library, named "minimal libc", is part of the Zephyr codebase
and provides the minimal subset of the standard C library required to meet the
needs of Zephyr and its subsystems, primarily in the areas of string
manipulation and display.

It is very low footprint and is suitable for projects that do not rely on less
frequently used portions of the ISO C standard library. It can also be used
with a number of different toolchains.

The minimal libc implementation can be found in :file:`lib/libc/minimal` in the
main Zephyr tree.

Formatted Output
****************

The minimal libc does not implement its own formatted output processor;
instead, it maps the C standard formatted output functions such as ``printf``
and ``sprintf`` to the :c:func:`cbprintf` function, which is Zephyr's own
C99-compatible formatted output implementation.

For more details, refer to the :ref:`Formatted Output <formatted_output>` OS
service documentation.

Dynamic Memory Management
*************************

Dynamic memory management in the minimal libc can be enabled by selecting the
:kconfig:option:`CONFIG_MINIMAL_LIBC_MALLOC` in the application configuration
file.

The minimal libc internally uses the :ref:`kernel memory heap API <heap_v2>` to
manage the memory heap used by the standard dynamic memory management interface
functions such as :c:func:`malloc` and :c:func:`free`.

The internal memory heap is normally located in the ``.bss`` section. When
userspace is enabled, however, it is placed in a dedicated memory partition
called ``z_malloc_partition``, which can be accessed from the user mode
threads. The size of the internal memory heap is specified by the
:kconfig:option:`CONFIG_MINIMAL_LIBC_MALLOC_ARENA_SIZE`.

The standard dynamic memory management interface functions implemented by the
minimal libc are thread safe and may be simultaneously called by multiple
threads. These functions are implemented in
:file:`lib/libc/minimal/source/stdlib/malloc.c`.

Error numbers
*************

Error numbers are used throughout Zephyr APIs to signal error conditions as
return values from functions. They are typically returned as the negative value
of the integer literals defined in this section, and are defined in the
:file:`errno.h` header file.

A subset of the error numbers defined in the `POSIX errno.h specification`_ and
other de-facto standard sources have been added to the minimal libc.

A conscious effort is made in Zephyr to keep the values of the minimal libc
error numbers consistent with the different implementations of the C standard
libraries supported by Zephyr. The minimal libc :file:`errno.h` is checked
against that of the :ref:`Newlib <c_library_newlib>` to ensure that the error
numbers are kept aligned.

Below is a list of the error number definitions. For the actual numeric values
please refer to `errno.h`_.

.. doxygengroup:: system_errno

.. _`POSIX errno.h specification`: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/errno.h.html
.. _`errno.h`: https://github.com/zephyrproject-rtos/zephyr/blob/main/lib/libc/minimal/include/errno.h