Skip to main content

IAR Embedded Workbench for RL78 5.20

C/C++ standard library overview

In this section:

The compiler comes with two different implementations of the C/C++ standard library.

The IAR DLIB runtime environment offers low-level support for C as well as C++. When using this runtime environment, you have a choice of two libraries:

  • The IAR DLIB C/C++ library is a complete implementation of the C/C++ standard library, compliant with standard C and C++14, except for thread-related functionality. It can be configured to include different levels of support for locale, file descriptors, multibyte characters, etc.

  • The IAR Libc++ library is a complete implementation of the C/C++ standard library, compliant with standard C and C++17, except for parallel algorithms, execution policies, and thread-related and filesystem functionality. The Libc++ library is taken from LLVM under an open source license and is used as is, with extensions and limitations from the C++17 standard. At the time of the release of this text, the version is libc++v16. For more information about the feature set of the LLVM Libc++ library, see https://libcxx.llvm.org/Status/Cxx17.html.

Both these implementations are built on top of the IAR DLIB runtime environment and both implementations support floating-point numbers in IEC 60559 format. For more information about this environment, and about how to customize the DLIB library, see The DLIB runtime environment.

For detailed information about the DLIB library functions, see the documentation supplied with the product in the rl78\doc directory in the file HelpDLIB6.chm. There is no reference information available for the Libc++ library functions.

For more information about library functions, see the sections about implementation-defined behavior.

Header files

Your application program gains access to library definitions through header files, which it incorporates using the #include directive. The definitions are divided into several different header files, each covering a particular functional area, letting you include just those that are required.

It is essential to include the appropriate header file before making any reference to its definitions. Failure to do so can cause the call to fail during execution, or generate error or warning messages at compile time or link time.

Library object files

Most of the library definitions can be used without modification, that is, directly from the library object files that are supplied with the product. For information about how to set up a runtime library, see Setting up the runtime environment. The linker will include only those routines that are required—directly or indirectly—by your application.

For information about how you can override library modules with your own versions, see Overriding library modules.

Alternative more accurate library functions

The default implementation of cos, sin, tan, and pow is designed to be fast and small. As an alternative, there are versions designed to provide better accuracy. They are named __iar_xxx_accuratef for float variants of the functions and __iar_xxx_accuratel for long double variants of the functions, and where xxx is cos, sin, etc.

To use these more accurate versions, use the ‑‑accurate_math linker option.

Reentrancy

A function that can be simultaneously invoked in the main application and in any number of interrupts is reentrant. A library function that uses statically allocated data is therefore not reentrant.

Most parts of the DLIB runtime environment are reentrant, but the following functions and parts are not reentrant because they need static data:

  • Heap functions—malloc, free, realloc, calloc, etc. and the C++ operators new and delete

  • Locale functions—localeconv, setlocale

  • Multibyte functions—mblen, mbrlen, mbrtowc, mbsrtowc, mbtowc, wcrtomb, wcsrtomb, wctomb

  • Rand functions—rand, srand

  • Time functions—asctime, localtime, gmtime, mktime

  • The miscellaneous functions atexit, perror, strerror, strtok

  • Functions that use files or the heap in some way. This includes scanf, sscanf, getchar, getwchar, putchar, and putwchar. In addition, if you are using the options ‑‑printf_multibytes and ‑‑dlib_config=Full, the printf and sprintf functions (or any variants) can also use the heap.

Functions that can set errno are not reentrant, because an errno value resulting from one of these functions can be destroyed by a subsequent use of the function before it is read. This applies to math and string conversion functions, among others.

Remedies for this are:

  • Do not use non-reentrant functions in interrupt service routines

  • Guard calls to a non-reentrant function by a mutex, or a secure region, etc.

The longjmp function

Warning

A longjmp is in effect a jump to a previously defined setjmp. Any variable length arrays or C++ objects residing on the stack during stack unwinding will not be destroyed. This can lead to resource leaks or incorrect application behavior.