📄 emSecure-ECDSA User Guide & Reference Manual
📄 emSecure-RSA User Guide & Reference Manual
📄 emSSH User Guide & Reference Manual
📄 emSSL User Guide & Reference Manual
📄 emUSB-Device User Guide & Reference Manual
📄 emUSB-Host User Guide & Reference Manual
📄 emWeb User Guide & Reference Manual
📄 emWin User Guide & Reference Manual
📄 IoT Toolkit User Guide & Reference Manual
📄 SEGGER Assembler User Guide & Reference Manual
📄 SEGGER Linker User Guide & Reference Manual
📄 SEGGER Online Documentation
📄 AppWizard User Guide & Reference Manual
📄 embOS Real-Time Operating System User Guide & Reference Manual
📄 embOS-Ultra Real-Time Operating System User Guide & Reference Manual
📄 emCompress-Embed User Guide & Reference Manual
📄 emCompress-ToGo User Guide & Reference Manual
📄 emCrypt User Guide & Reference Manual
📄 emDropbox User Guide & Reference Manual
📄 emFile User Guide & Reference Manual
📄 emFloat User Guide & Reference Manual
📄 emNet User Guide & Reference Manual
📄 emRun User Guide & Reference Manual

emRun User Guide & Reference Manual

A small, efficient C runtime library.

Introduction

This section presents an overview of emRun, its structure, and its capabilities.

What is emRun?

emRun is an optimized C library for Arm and RISC-V processors.

Features

emRun is written in standard ANSI C and Arm assembly language and can run on any Arm or RISC-V CPU. Here’s a list summarising the main features of emRun:

We recommend keeping emRun separate from your application files. It is good practice to keep all the program files (including the header files) together in the LIB subdirectory of your project’s root directory. This practice has the advantage of being very easy to update to newer versions of emRun by simply replacing the LIB directory. Your application files can be stored anywhere.

Note

When updating to a newer emRun version: as files may have been added, moved or deleted, the project directories may need to be updated accordingly.

Package content

emRun is provided in source code and contains everything needed. The following table shows the content of the emRun Package:

Directory Description
Doc emRun documentation.
Src emRun source code.

Include directories

You should make sure that the system include path contains the following directory:

Note

Always make sure that you have only one version of each file!

It is frequently a major problem when updating to a new version of emRun if you have old files included and therefore mix different versions. If you keep emRun in the directories as suggested (and only in these), this type of problem cannot occur. When updating to a newer version, you should be able to keep your configuration files and leave them unchanged. For safety reasons, we recommend backing up (or at least renaming) the LIB directories before to updating.

Compiling emRun

User-facing source files

The standard C library is exposed to the user by a set of header files that provide an interface to the library. In addition, there must be additional “invisible” functions added to provide C language support, such as software floating point and integer mathematics, that the C compiler calls.

The user-facing interface files are:

File Description
<assert.h> Assertion macros.
<complex.h> Complex number functions.
<ctype.h> Character classification functions.
<errno.h> Access to errno.
<fenv.h> Floating-point environment functions.
<float.h> Parameterization of floating types.
<inttypes.h> Parameterization of formatting of integer types.
<iso646.h> Alternative spelling of C operators.
<limits.h> Minima and maxima of floating and integer types.
<locale.h> Functions for internationalizing software.
<math.h> Mathematical functions.
<setjmp.h> Non-local jumps.
<signal.h> Signals and interrupts.
<stdbool.h> Boolean type and values.
<stddef.h> Standard definitions such as NULL.
<stdint.h> Specification of fixed-size integer types.
<stdio.h> Formatted input and output functions.
<stdlib.h> Standardized common library functions.
<string.h> String and memory functions.
<time.h> Time and date functions.
<wchar.h> Wide character functions.
<wctype.h> Wide character classification functions.
<xlocale.h> Extended POSIX.1 locale functions.

In addition some private header files are required:

File Description
__SEGGER_RTL.h General definitions used when compiling the library.
__SEGGER_RTL_Conf.h Specific configuration of the library.
__SEGGER_RTL_ConfDefaults.h Default configuration of the library.

Implementation source files

emRun is delivered in a small number of files that must be added to your project before building:

File Description
codesets.c Support for code pages used in locales.
config.c Support for configuration checks.
compilersmops_arm.s Support for compiler-generated helpers and builtins (ARM).
compilersmops_rv.s Support for compiler-generated helpers and builtins (RISC-V).
convops.c Support for conversion between binary and printable strings.
errno.c Support for errno in a tasking environment.
errno_arm.c Support for errno in an AEABI environment (ARM).
execops.c Support for execution-control functions e.g. atexit().
execops_arm.c Support for execution-control functions in an AEABI environment (ARM).
fenvops.c Support for floating-point environment functions e.g. feraiseexcept().
fileops.c Support for file-based I/O operations e.g. fputs.
floatasmops_arm.s Support for low-level floating point functions (ARM).
floatasmops_rv.s Support for low-level floating point functions (RISC-V).
floatops.c Support for high-level floating point functions.
heapops.c Support for generic dynamic storage functions e.g. malloc().
heapops_minimal.c Support for allocate-only dynamic storage management.
heapops_basic.c Support for low-overhead dynamic storage management.
heapops_realtime.c Support for real-time O(1) dynamic storage management.
intops.c Support for high-level integer functions e.g. ldiv().
intasmops_arm.s Support for low-level integer functions (ARM).
intasmops_rv.s Support for low-level integer functions (RISC-V).
jumpasmops_arm.s Support for nonlocal ’goto’ functions e.g. longjmp (ARM).
jumpasmops_rv.s Support for nonlocal ’goto’ functions e.g. longjmp (RISC-V).
locales.c Support for various locales.
mbops.c Support for multi-byte functions e.g. mbtowc().
prinops.c Support for formatting functions e.g. sprintf().
scanops.c Support for formatted input functions e.g. scanf().
sortops.c Support for searching and sorting functions e.g. qsort().
strasmops_arm.s Support for fast string and memory functions e.g. strcpy() (ARM).
strasmops_rv.s Support for fast string and memory functions e.g. strcpy() (RISC-V).
strops.c Support for string and memory functions e.g. strcat().
timeops.c Support for time operations e.g. mktime().
utilops.c Support for common functions used in emRun.
wconvops.c Support for conversion between binary and wide strings.
wprinops.c Support for wide formatted output functions e.g. wprintf().
wscanops.c Support for wide formatted input functions e.g. wscanf().
wstrops.c Support for wide string functions e.g. wcscpy().

Additionally, example I/O implementations are provided, only one of which must be compiled into your application or library when using emRun:

File Description
fileops_semi.c Support for complete I/O interface using SEGGER semihosting.
prinops_rtt.c Support for character I/O using SEGGER RTT.
prinops_semi.c Support for character I/O using SEGGER semihosting.
prinops_uart.c Support for character I/O using a UART.

A customized version of the SEGGER real-time heap is provided:

File Description
__SEGGER_RTL_RTHEAP.h Real-time heap interface.
__SEGGER_RTL_RTHEAP_Conf.h Real-time heap configuration.
__SEGGER_RTL_RTHEAP_ConfDefaults.h Real-time heap configuration defaults.
__SEGGER_RTL_RTHEAP.c Real-time heap implementation.

General configuration

All source files should be added to the project and the following preprocessor symbols set correctly to select the particular variant of the library:

The configuration of emRun is defined by the content of __SEGGER_RTL_Conf.h which is included by all C and assembly language source files. The example configuration files that ship with emRun are described in the following sections.

The following preprocessor symbol definitions affect how the library is compiled and the features that are implemented:

Symbol Description
__SEGGER_RTL_OPTIMIZE Prefer size-optimized or speed-optimized code.
__SEGGER_RTL_FORMAT_INT_WIDTH Support for int, long, and long long in printf() and scanf() functions.
__SEGGER_RTL_FORMAT_FLOAT_WIDTH Support float in printf() and scanf() functions.
__SEGGER_RTL_FORMAT_WIDTH_PRECISION Support width and precision in printf() and scanf() functions.
__SEGGER_RTL_FORMAT_CHAR_CLASS Support character classes in scanf() functions.
__SEGGER_RTL_FORMAT_WCHAR Support wide character output in printf() and scanf() functions.
__SEGGER_RTL_STDOUT_BUFFER_LEN Configuration of buffer capacity for standard output stream.
__SEGGER_RTL_ATEXIT_COUNT The maximum number of registered atexit() functions.
__SEGGER_RTL_SCALED_INTEGER Selection of scaled-integer floating-point algorithms.
__SEGGER_RTL_NO_BUILTIN Prevent optimizations that cause incorrect code generation when compiling at high optimization levels.

Source-level optimization

Default

#ifndef   __SEGGER_RTL_OPTIMIZE
  #define __SEGGER_RTL_OPTIMIZE                 0
#endif

Description

Define the preprocessor symbol __SEGGER_RTL_OPTIMIZE to select size-optimized implementations for both C and assembly language code.

If this preprocessor symbol is undefined (the default) the library is configured to select balanced implementations.

Value Description
-2 Favor size at the expense of speed.
-1 Favor size over speed.
0 Balanced.
+1 Favor speed over size.
+2 Favor speed at the expense of size.

Integer I/O capability selection

Default

#define __WIDTH_INT                             0
#define __WIDTH_LONG                            1
#define __WIDTH_LONG_LONG                       2

#ifndef   __SEGGER_RTL_FORMAT_INT_WIDTH
  #define __SEGGER_RTL_FORMAT_INT_WIDTH         __WIDTH_LONG_LONG
#endif

Description

To select the level of printf() and scanf() support, set this preprocessor symbol as follows:

Value Description
0 Support only int, do not support long or long long.
1 Support int and long, do not support long long.
2 Support int, long, and long long.

Floating I/O capability selection

Default

#define __WIDTH_NONE                            0
#define __WIDTH_FLOAT                           1
#define __WIDTH_DOUBLE                          2

#ifndef   __SEGGER_RTL_FORMAT_FLOAT_WIDTH
  #define __SEGGER_RTL_FORMAT_FLOAT_WIDTH       __WIDTH_DOUBLE
#endif

Description

Set this preprocessor symbol to include floating-point support in printf() and scanf() as follows:

Value Description
0 Eliminate all formatted floating point support.
1 Support output of float values, no doubles.
2 Support output of float, double, and long double values.

Wide character I/O support

Default

#ifndef   __SEGGER_RTL_FORMAT_WCHAR
  #define __SEGGER_RTL_FORMAT_WCHAR             1
#endif

Description

Set this preprocessor symbol to include wide character support in printf() and scanf() as follows:

Value Description
0 Eliminate all wide character support.
1 Support formatted input and output of wide characters.

Input character class support selection

Default

#ifndef   __SEGGER_RTL_FORMAT_CHAR_CLASS
  #define __SEGGER_RTL_FORMAT_CHAR_CLASS        1
#endif

Description

Set this preprocessor symbol to include character class support in scanf() as follows:

Value Description
0 Eliminate all character class support.
1 Support formatted input with character classes.

Width and precision specification selection

Default

#ifndef   __SEGGER_RTL_FORMAT_WIDTH_PRECISION
  #define __SEGGER_RTL_FORMAT_WIDTH_PRECISION   1
#endif

Description

Set this preprocessor symbol to include width and precision support in printf() and scanf() as follows:

Value Description
0 Eliminate all width and precision support.
1 Support formatted input and output with width and precision.

Standard output stream buffering

Default

#ifndef   __SEGGER_RTL_STDOUT_BUFFER_LEN
  #define __SEGGER_RTL_STDOUT_BUFFER_LEN        64
#endif

Description

Set this preprocessor symbol to set the internal size of the formatting buffer, in characters, used when printing to the standard output stream. By default it is 64.

Registration of exit cleanup functions

Default

#ifndef   __SEGGER_RTL_ATEXIT_COUNT
  #define __SEGGER_RTL_ATEXIT_COUNT             1
#endif

Description

Set this preprocessor symbol to the maximum number of registered atexit() functions to support. The registered functions can be executed when main()) returns by calling __SEGGER_RTL_execute_at_exit_fns(), typically as part of the startup code.

Scaled-integer algorithm selection

Default

#ifndef   __SEGGER_RTL_SCALED_INTEGER
  #define __SEGGER_RTL_SCALED_INTEGER           0
#endif

Description

Define the preprocessor symbol __SEGGER_RTL_SCALED_INTEGER to select scaled-intger algorithms over standard floating-point algorithms.

Value Description
0 Algorithms use C-language floating-point arithmetic.
1 IEEE single-precision functions use scaled integer arithmetic if there is a scaled-integer implementation of the function.
+2 IEEE single-precision and double-precision functions use scaled integer arithmetic if there is a scaled-integer implementation of the function.

Note that selecting scaled-integer arithmetic does not reduce the range or accuracy of the function as seen by the user. Scaled-integer arithmetic runs quickly on integer-only processors and delivers results that are correctly rounded in more cases as 31 bits or 63 bits of precision are retained internally whereas using IEEE aritmetic retains only 24 or 53 bits of precision.

Scaled-integer algorithms are faster than standard algorithms using the floating-point emulator, but can be significantly larger depending upon compiler optimization settings.

Optimization prevention

Default

None; this must be specifically configured for compiler and architecture. The defaults for Arm and RISC-V are:

  #if defined(__clang__)
    #define __SEGGER_RTL_NO_BUILTIN
  #elif defined(__GNUC__)
    #define __SEGGER_RTL_NO_BUILTIN \
      __attribute__((optimize("-fno-tree-loop-distribute-patterns")))
  #endif

Description

Define the preprocessor symbol __SEGGER_RTL_NO_BUILTIN to prevent GCC from applying incorrect optimizations at high optimization levels.

Specifically, at high optimization GCC will:

This definition prevents GCC from identifying a loop copy in the implementation of memcpy() and replacing it with a call to memcpy(), thereby introducing infinite recursion.

GCC has been observed to make the following transformations:

Clang has been observed to make the following transformations:

Unfortunately it is not possible to prevent these optimizations using a per-function optimization attribute. These optimizations may be disabled by using the GCC command-line option -fno-builtins or -ffreestanding, but you are advised to check the subject compiler for adherence.

To prevent the transformation of malloc() followed by memset(), emRun works around this by a volatile store to the allocated memory (if successfully allocated with nonzero size).

To prevent user programs from suffering optimization of sin() and cos() to sincos(), an implementations of POSIX.1 sincos(), sincosf(), and sincosl() are provided. The implementation of the sincos() family does not suffer this misoptimization as emRun does not directly call the sin() and cos() functions.

To prevent user programs from suffering optimization of exp(10, x), implementations of exp10(), exp10f(), and exp10l() are provided. The implementation of the exp10() family does not suffer this misoptimization as emRun does not directly call the exp() functions.

Configuring for Arm

This section provides a walkthrough of the library configuration supplied in __SEGGER_RTL_Arm_Conf.h for Arm processors.

The library is configured for execution on Arm targets by querying the environment. The example configuration assumes that the compiler supports the Arm C Language Extensions (ACLE) standard.

In many cases the library can can be configured automatically. For ARM the default configuration of the library is derived from these preprocessor symbols:

Symbol Description
Compiler identification
__GNUC__ Compiler is GNU C.
__clang__ Compiler is Clang.
Target instruction set
__thumb__ Target the Thumb instruction set (as opposed to ARM).
__thumb2__ Target the Thumb-2 instruction set.
ACLE definitions
__ARM_ARCH Arm target architecture version.
__ARM_ARCH_PROFILE Arm architecture profile, if applicable.
__ARM_ARCH_ISA_ARM Processor implements AArch32 instruction set.
__ARM_ARCH_ISA_THUMB Processor implements Thumb instruction set.
__ARM_BIG_ENDIAN Byte order is big endian.
__ARM_PCS Functions use standard Arm PCS calling convention.
__ARM_PCS_VFP Functions use Arm VFP calling convention.
__ARM_FP Arm floating-point hardware availability.
__ARM_FEATURE_CLZ Indicates existence of CLZ instruction.
__ARM_FEATURE_IDIV Indicates existence of integer division instructions.

Target instruction set

Default

#define __SEGGER_RTL_ISA_T16                    0
#define __SEGGER_RTL_ISA_T32                    1
#define __SEGGER_RTL_ISA_ARM                    2

#if defined(__thumb__) && !defined(__thumb2__)
  #define __SEGGER_RTL_TARGET_ISA               __SEGGER_RTL_ISA_T16
#elif defined(__thumb2__)
  #define __SEGGER_RTL_TARGET_ISA               __SEGGER_RTL_ISA_T32
#else
  #define __SEGGER_RTL_TARGET_ISA               __SEGGER_RTL_ISA_ARM
#endif

Description

These definitions are used by assembly language files to check the instruction set being compiled for. The preprocessor symbol __thumb__ is defined when compiling for cores that support 16-bit Thumb instructions but not Thumb-2 instructions; the preprocessor symbol __thumb2__ is defined when compiling for cores that support the 32-bit Thumb-2 instructions. If neither of these symbols is defined, the core supports the AArch32 Arm instruction set.

Arm AEABI

Default

#if defined(__GNUC__) || defined(__clang__)
  #define __SEGGER_RTL_INCLUDE_AEABI_API        2
#endif

Description

Implementation of the ARM AEABI functions are required by all AEABI-conforming C compilers. This definition can be set to 1, in which case C-coded generic implementations of AEABI functions are compiled into the library; or it can be set to 2, in which case assembly-coded implementations are compiled into the library and is the preferred option.

Processor byte order

Default

#if defined(__ARM_BIG_ENDIAN) && (__ARM_BIG_ENDIAN == 1)
  #define __SEGGER_RTL_BYTE_ORDER               (+1)
#else
  #define __SEGGER_RTL_BYTE_ORDER               (-1)
#endif

Description

The ACLE symbol __ARM_BIG_ENDIAN is queried to determine whether the target core runs in litte-endian or big-endian mode and configures the library for that byte ordering.

Maximal data type alignment

Default

#define __SEGGER_RTL_MAX_ALIGN                  8

Description

This sets the maximal type alignment required for any type. For 64-bit double data loaded by LDRD or VLDR, it is best to align data on 64-bit boundaries.

ABI type set

Default

#define __SEGGER_RTL_TYPESET                    32

Description

All Arm targets use a 32-bit ILP32 ABI, and this is not configurable otherwise for the library.

Static branch probability

Default

#if defined(__GNUC__) || defined(__clang__)
  #define __SEGGER_RTL_UNLIKELY(X)              __builtin_expect((X), 0)
#endif

Description

The preprocessor macro __SEGGER_RTL_UNLIKELY is configured to indicate that the expression X is unlikely to occur. This enables the compiler to use this information to configure the condition of branch instructions to place exceptional code off the hot trace and not incur branch penalties for the likely execution path.

This definition is specific to the GNU and Clang compilers; configure this to whatever your compiler supports or, if not supported at all, leave __SEGGER_RTL_UNLIKELY undefined.

Thread-local storage

Default

#if defined(__GNUC__) || defined(__clang__)
  #define __SEGGER_RTL_THREAD                   __thread
#endif

Description

The preprocessor symbol __SEGGER_RTL_THREAD can be defined to the storage class specifier for thread-local data, if your compiler supports thread-local storage. For Arm processors, thread-local storage is accessed using the __aeabi_read_tp function which is dependent upon the target operating system and whether an operating system is present.

The library has a number of file-scope and external variables that benefit from thread-local storage, such as the implementation of errno.

If your compiler does not support thread-local storage class specifiers or your target does not run an operating system, leave __SEGGER_RTL_THREAD undefined.

Function inlining control

Default

#if (defined(__GNUC__) || defined(__clang__))
  #ifndef   __SEGGER_RTL_NEVER_INLINE
    #if defined(__clang__)
      #define __SEGGER_RTL_NEVER_INLINE   __attribute__((__noinline__))
    #else
      #define __SEGGER_RTL_NEVER_INLINE   __attribute__((__noinline__, __noclone__))
    #endif
  #endif
  //
  #ifndef   __SEGGER_RTL_ALWAYS_INLINE
    #define __SEGGER_RTL_ALWAYS_INLINE    __inline__ __attribute__((__always_inline__))
  #endif
  //
  #ifndef   __SEGGER_RTL_REQUEST_INLINE
    #define __SEGGER_RTL_REQUEST_INLINE   __inline__
  #endif
  //
#endif

Description

The preprocessor symbols __SEGGER_RTL_NEVER_INLINE, __SEGGER_RTL_ALWAYS_INLINE, and __SEGGER_RTL_REQUEST_INLINE are configured indicate to the compiler the benefit of inlining.

__SEGGER_RTL_NEVER_INLINE should be configured to disable inlining of a function in all cases.

__SEGGER_RTL_ALWAYS_INLINE should be configured to encourage inlining of a function in all cases.

__SEGGER_RTL_REQUEST_INLINE should be configured to indicate that a function benefits from inlining but it is not essential to inline this function. Typically this is used to inline a function when compiling to maximize execution speed and not inline a function when compiling to minimize code size.

The above definitions work for the GNU and clang compilers when targeting Arm. If your compiler is different, configure thsse symbols to suit.

Public API indication

Default

#if defined(__GNUC__) || defined(__clang__)
  #define __SEGGER_RTL_PUBLIC_API               __attribute__((__weak__)) 
#endif

Description

Every function in the library that forms part of the API is labeled using __SEGGER_RTL_PUBLIC_API. For GCC and Clang compilers, all API entry points are defined as weak ELF symbols. You can customize this for your particular compiler or, if compiling the library as part of your project, you can leave this undefined in order to have strong definitions of each library symbol.

Floating-point ABI

Default

#if defined(__ARM_PCS_VFP) && (__ARM_PCS_VFP == 1)
  //
  // PCS uses hardware registers for passing parameters.  For VFP
  // with only single-precision operations, parameters are still
  // passed in floating registers.
  //
  #define __SEGGER_RTL_FP_ABI                   2
  //
#elif defined(__ARM_PCS) && (__ARM_PCS == 1)
  //
  // PCS is standard integer PCS.
  //
  #define __SEGGER_RTL_FP_ABI                   0
  //
#else
  #error Unable to determine floating-point ABI used
#endif

Description

Configuration of the floating-point ABI in use is determined from the ACLE symbols __ARM_PCS_VFP and __ARM_PCS.

__SEGGER_RTL_FP_ABI must be set to 0 if float and double parameters are passed using integer registes, to 1 if float parameters are passed using floating registers and double parameters are passed using integer registers, and to 2 if both float and double parameters are passed using floating registers.

The ACLE symbol __ARM_PCS_VFP being set to 1 indicates that floating-point arguments are passed using floating-point registers; the ACLE symbol __ARM_PCS being set to 1 indicates that floating-point arguments are passed in integer registers. From these definitions, __SEGGER_RTL_FP_ABI is set appropriately.

Note that for cores that have only single-precision (32-bit) floating-point, double precision (64-bit) arguments are passed in two single-precision floating-point registers and not in integer registers.

Floating-point hardware

Default

#if defined(__ARM_FP) && (__ARM_FP & 0x08)
  #define __SEGGER_RTL_FP_HW                    2
#elif defined(__ARM_FP) && (__ARM_FP & 0x04)
  #define __SEGGER_RTL_FP_HW                    1
#else
  #define __SEGGER_RTL_FP_HW                    0
#endif

// Clang gets __ARM_FP wrong for the T16 target ISA indicating
// that floating-point instructions exist in this ISA -- which
// they don't.  Patch that definition up here.
#if __ARM_ARCH_ISA_THUMB == 1
  #undef  __SEGGER_RTL_FP_HW
  #define __SEGGER_RTL_FP_HW                    0
  #undef  __SEGGER_RTL_FP_ABI
  #define __SEGGER_RTL_FP_ABI                   0
#endif

Description

Floating-point hardware support is configured separately from the floating-point calling convention. Even if floating-point parameters are passed in integer registers, it is still possible that floating-point instructions operate on those parameters in the called function.

The ACLE symbol __ARM_FP is queried to determine the target core’s floating-point ability and set __SEGGER_RTL_FP_HW appropriately.

__SEGGER_RTL_FP_HW is set to 0 to indicate that no floating-point hardware exists, to 1 to indicate that hardware exists to support float arithmetic, and to 2 to to indicate that hardware exists to support double arithmetic.

Unfortunately, a fix-up is required for Clang when tageting the 16-bit Thumb instruction set.

Half-precision floating-point type

Default

#define __SEGGER_RTL_FLOAT16                    _Float16

Description

The GNU and clang compilers support 16-bit floating-point data in IEEE format. This configures the emRun type that implements 16-bit floating-point. Some compilers use __fp16 as type name, but _Float16 is the standard C name for such a type.

Multiply-subtract instruction availability

Default

#if (__ARM_ARCH >= 6) && (__SEGGER_RTL_TARGET_ISA != __SEGGER_RTL_ISA_T16)
  #define __SEGGER_RTL_CORE_HAS_MLS             1
#else
  #define __SEGGER_RTL_CORE_HAS_MLS             0
#endif

Description

Assembly-language source files use the preprocessor symbol __SEGGER_RTL_CORE_HAS_MLS to conditionally assemble MLS instructions. The ACLE symbol __ARM_ARCH is queried to determine whether the target architecture offers a MLS instruction and then __SEGGER_RTL_TARGET_ISA is checked to ensure that it is offered in the selected instruction set.

Long multiply instruction availability

Default

#if __SEGGER_RTL_TARGET_ISA == __SEGGER_RTL_ISA_T16
  //
  // T16 ISA has no extended multiplication at all.
  //
  #define __SEGGER_RTL_CORE_HAS_EXT_MUL         0
  //
#elif __ARM_ARCH >= 6
  //
  // ARMv6 and above have no restrictions on their input
  // and output registers, so assembly-level inserts with
  // constraints to guide the compiler are acceptable.
  //
  #define __SEGGER_RTL_CORE_HAS_EXT_MUL         1
  //
#elif (__ARM_ARCH == 5) && defined(__clang__)
  //
  // Take Arm at its word and disable restrictions on input
  // and output registers.
  //
  #define __SEGGER_RTL_CORE_HAS_EXT_MUL         1
  //
#else 
  //
  // ARMv5TE and lower have restrictions on their input
  // and output registers, therefore do not enable extended
  // multiply inserts.
  //
  #define __SEGGER_RTL_CORE_HAS_EXT_MUL         0
  //
#endif

Description

Assembly-language source files use the preprocessor symbol __SEGGER_RTL_CORE_HAS_EXT_MUL to conditionally compile and assemble long-multiply instructions. This symbol must be set to 1 to indicate that long multiply instructions are supported in the target instruction set, and to zero otherwise.

In the ARM Architecture Reference Manual, DDI 01001, Arm states the following for the SMULL and UMULL instructions:

Note

“Specifying the same register for either RdHi and Rm, or RdLo and Rm, was previously described as producing UNPREDICTABLE results. There is no restriction in ARMv6, and it is believed all relevant ARMv4 and ARMv5 implementations do not require this restriction either, because high performance multipliers read all their operands prior to writing back any results.”

Unfortunately, the GNU assembler enforces this restriction which means that assembly-level long-multiply inserts will not work for ARMv4 and ARMv5 even though there is no indication that they fail in practice. For the clang compiler, no such restriction is enforced.

The default configuration is deliberately conservative; you may configure this differently for your specific compiler, assembler, and target processor.

Count-leading-zeros instruction availability

Default

#if defined(__ARM_FEATURE_CLZ) && (__ARM_FEATURE_CLZ == 1)
  #define __SEGGER_RTL_CORE_HAS_CLZ             1
#else
  #define __SEGGER_RTL_CORE_HAS_CLZ             0
#endif

#if __SEGGER_RTL_CORE_HAS_CLZ
  //
  // For ACLE-conforming C compilers that declare the architecture or
  // profile has a CLZ instruction, use that CLZ instruction.
  //
  #define __SEGGER_RTL_CLZ_U32(X)               __builtin_clz(X)
#endif

// Clang gets __ARM_FEATURE_CLZ wrong for v8M.Baseline, indicating
// that CLZ is available in this ISA  -- which it isn't.  Patch that
// definition up here.
#if (__ARM_ARCH == 8) && (__SEGGER_RTL_TARGET_ISA == __SEGGER_RTL_ISA_T16)
  #undef  __SEGGER_RTL_CORE_HAS_CLZ
  #define __SEGGER_RTL_CORE_HAS_CLZ             0
#endif

// GCC gets __ARM_FEATURE_CLZ wrong for v5TE compiling for Thumb,
// indicating that CLZ is available in this ISA -- which it isn't.
// Patch that definition up here.
#if (__ARM_ARCH == 5) && (__SEGGER_RTL_TARGET_ISA == __SEGGER_RTL_ISA_T16)
  #undef  __SEGGER_RTL_CORE_HAS_CLZ
  #define __SEGGER_RTL_CORE_HAS_CLZ             0
#endif

Description

The library benefits from the availablity of a count-leading-zero instruction. The ACLE symbol __ARM_FEATURE_CLZ is set to 1 to indicate that the target architecture provides a CLZ instruction. This definition works for ACLE-conforming compilers.

The preprocessor symbol __SEGGER_RTL_CLZ_U32 is defined to expand to a way to use the CLZ instruction when the core is known to have one.

Unfortunately, although GNU and Clang compilers conform to the ACLE, they disagree on the availability of the CLZ instruction and provide an incorrect definition of __ARM_FEATURE_CLZ for some architectures. Therefore the fixups above are applied for these known cases.

SIMD media instruction availability

Default

#if defined(__ARM_ARCH) && (__ARM_ARCH >= 6) && (__SEGGER_RTL_TARGET_ISA != __SEGGER_RTL_ISA_T32)
  #define __SEGGER_RTL_CORE_HAS_MEDIA           1
#else
  #define __SEGGER_RTL_CORE_HAS_MEDIA           0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_MEDIA must be set to 1 if the target instruction set has the DSP media instructions, and 0 otherwise.

The library uses the media instructions to accelerate string processing functions such as strlen() and strcmp().

Bit-reverse instruction availability

Default

#if defined(__ARM_ARCH) && (__ARM_ARCH >= 7)
  #define __SEGGER_RTL_CORE_HAS_REV             1
#else
  #define __SEGGER_RTL_CORE_HAS_REV             0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_REV must be set to 1 if the target instruction set offers the REV instruction, and 0 otherwise.

And/subtract-word instruction availability

Default

#if (__ARM_ARCH >= 7) && (__SEGGER_RTL_TARGET_ISA == __SEGGER_RTL_ISA_T32)
  #define __SEGGER_RTL_CORE_HAS_ADDW_SUBW       1   // ARMv8A/R only has ADDW in Thumb mode
#else
  #define __SEGGER_RTL_CORE_HAS_ADDW_SUBW       0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_ADDW_SUBW must be set to 1 if the target instruction set offers the ADDW and SUBW instructions, and 0 otherwise.

Move-word instruction availability

Default

#if __ARM_ARCH >= 7
  #define __SEGGER_RTL_CORE_HAS_MOVW_MOVT       1
#else
  #define __SEGGER_RTL_CORE_HAS_MOVW_MOVT       0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_MOVW_MOVT must be set to 1 if the target instruction set offers the MOVW and MOVT instructions, and 0 otherwise.

Integer-divide instruction availability

Default

#if defined(__ARM_FEATURE_IDIV) && __ARM_FEATURE_IDIV
  #define __SEGGER_RTL_CORE_HAS_IDIV            1
#else
  #define __SEGGER_RTL_CORE_HAS_IDIV            0
#endif

// Unfortunately the ACLE specifies "__ARM_FEATURE_IDIV is defined to 1 if the target
// has hardware support for 32-bit integer division in all available instruction sets."
// For v7R, there is typically no divide in the Arm instruction set but there is
// support for divide in the Thumb instruction set, so provide an exception here
// when targeting v7R in Thumb mode.
#if (__ARM_ARCH_PROFILE == 'R') && (__SEGGER_RTL_TARGET_ISA == __SEGGER_RTL_ISA_T32)
  #undef  __SEGGER_RTL_CORE_HAS_IDIV
  #define __SEGGER_RTL_CORE_HAS_IDIV            1
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_IDIV must be set to 1 if the target instruction set offers integer divide instructions, and 0 otherwise. Note the ACLE inquiry above, if not adjusted for the specific v7R instruction set, leads to suboptimal code.

Zero-branch instruction availability

Default

#if (__ARM_ARCH >= 7) && (__SEGGER_RTL_TARGET_ISA != __SEGGER_RTL_ISA_ARM)
  #define __SEGGER_RTL_CORE_HAS_CBZ_CBNZ        1
#else
  #define __SEGGER_RTL_CORE_HAS_CBZ_CBNZ        0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_CBZ_CBNZ must be set to 1 if the target architecture offers CBZ and CBNZ instructions, and to 0 otherwise.

Table-branch instruction availability

Default

#if (__ARM_ARCH >= 7) && (__SEGGER_RTL_TARGET_ISA == __SEGGER_RTL_ISA_T32)
  #define __SEGGER_RTL_CORE_HAS_TBB_TBH         1
#else
  #define __SEGGER_RTL_CORE_HAS_TBB_TBH         0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_TBB_TBH must be set to 1 if the target architecture offers TBB and TBH instructions, and to 0 otherwise.

Sign/zero-extension instruction availability

Default

#if __ARM_ARCH >= 6
  #define __SEGGER_RTL_CORE_HAS_UXT_SXT         1
#else
  #define __SEGGER_RTL_CORE_HAS_UXT_SXT         0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_UXT_SXT must be set to 1 if the target architecture offers UXT and SXT instructions, and to 0 otherwise.

Bitfield instruction availability

Default

#if (__SEGGER_RTL_TARGET_ISA == __SEGGER_RTL_ISA_T32) || (__ARM_ARCH >= 7)
  #define __SEGGER_RTL_CORE_HAS_BFC_BFI_BFX     1
#else
  #define __SEGGER_RTL_CORE_HAS_BFC_BFI_BFX     0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_BFC_BFI_BFX must be set to 1 if the target architecture offers BFC, BFI, and BFX instructions, and to 0 otherwise.

BLX-to-register instruction availability

Default

#if __ARM_ARCH >= 5
  #define __SEGGER_RTL_CORE_HAS_BLX_REG         1
#else
  #define __SEGGER_RTL_CORE_HAS_BLX_REG         0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_BLX_REG must be set to 1 if the target architecture offers BLX using a register, and to 0 otherwise.

Long shift-count availability

Default

#if (__ARM_ARCH >= 6) && (__SEGGER_RTL_TARGET_ISA == __SEGGER_RTL_ISA_T32)
  #define __SEGGER_RTL_CORE_HAS_LONG_SHIFT      1
#else
  #define __SEGGER_RTL_CORE_HAS_LONG_SHIFT      0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_LONG_SHIFT must be set to 1 if the target architecture offers correct shifting of registers when the bitcount is greater than 32.

Configuring for RISC-V

This section provides a walkthrough of the library configuration supplied in __SEGGER_RTL_RISCV_Conf.h for RV32 processors.

The library is configured for execution on RISC-V targets by querying the environment. The example configuration assumes that the compiler supports the preprocessor symbols definied for the RISC-V architecture as follows:

Symbol Description
__riscv Target is RISC-V.
__riscv_abi_rve Target RV32E base instruction set.
__riscv_compressed Target has C extension.
__riscv_float_abi_soft Target has neither F nor D extension.
__riscv_float_abi_single Target has F extension.
__riscv_float_abi_double Target has D and F extensions.
__riscv_mul Target has M extension.
__riscv_muldiv Target has M extension with divide support.
__riscv_div Target has M extension with divide support.
__riscv_dsp Target has P (packed SIMD) extension.
__riscv_zba Target has Zba (shift-add) extension.
__riscv_zbb Target has Zbb (CLZ, negated logic) extension.
__riscv_zbs Target has Zbs (bt manipulation) extension.
__riscv_xlen Register width.
__riscv_flen Floating-point register width.
__nds_v5 Andes Performance Extension support.

Base instruction set architecture

Default

#if defined(__riscv_abi_rve)
  #define __SEGGER_RTL_CORE_HAS_ISA_RVE                1
#else
  #define __SEGGER_RTL_CORE_HAS_ISA_RVE                0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_ISA_RVE must be set to 1 if the base instruction set is RV32E and to 0 if the base instruction set is RV32I.

GNU libgcc API

Default

#if defined(__GNUC__) || defined(__clang__)
  #if __riscv_xlen == 32
    #define __SEGGER_RTL_INCLUDE_GNU_API  2
  #else
    #define __SEGGER_RTL_INCLUDE_GNU_API  1
  #endif
#endif

Description

The GNU and clang compilers both use the standard GNU libgcc API for runtime services. The following settings to select the GNU libgcc API are supported:

Setting Description
0 GNU libgcc API is eliminated.
1 GNU libgcc API uses all C-coded functions.
2 GNU libgcc API uses a combination of C-coded functions and assembly language acceleration functions.

Note: Assembly-language acceleration is only supported for RV32E and RV32I architectures.

GNU libgcc 16-bit float API

Default

#define __SEGGER_RTL_INCLUDE_GNU_FP16_API       1

Description

The GNU and clang compilers support 16-bit floating-point data in IEEE format. This configures emRun support for GCC on RISC-V.

The following settings to select the GNU libgcc API are supported:

Setting Description
0 GNU libgcc 16-bit float API is eliminated.
1 GNU libgcc 16-bit float API is present.

Note that __SEGGER_RTL_FLOAT16 must also be configured if runtime support for 16-bit floating-point types is configured.

Half-precision floating-point type

Default

#define __SEGGER_RTL_FLOAT16                    _Float16

Description

The GNU and clang compilers support 16-bit floating-point data in IEEE format. This configures the emRun type that implements 16-bit floating-point. Some compilers use __fp16 as type name, but _Float16 is the standard C name for such a type.

ABI type set

Default

#define __SEGGER_RTL_TYPESET                    32

Description

All RV32 targets use a 32-bit ILP32 ABI, and this is not configurable otherwise for the library.

Processor byte order

Default

#define __SEGGER_RTL_BYTE_ORDER                 (-1)

Description

Only little-endian RISC-V processors are supported at this time, and this preprocessor symbol cannot be configured any other way.

Minimum stack alignment

Default

#ifndef   __SEGGER_RTL_STACK_ALIGN   
  #define __SEGGER_RTL_STACK_ALIGN              16
#endif

Description

The compiler provides correct stack alignment for the RISC-V ABI selected for compilation. However, assembly language files must also know the intended stack alignment of the system and ensure that alignment constraints are respected.

At the time of writing, there is an ongoing discussion in the RISC-V community as to the minimum stack alignment for RV32I and RV32E ABIs. As such, this definition is conservative and works for both RV32I and RV32E.

Static branch probability

Default

#if defined(__GNUC__) || defined(__clang__)
  #define __SEGGER_RTL_UNLIKELY(X)              __builtin_expect((X), 0)
#endif

Description

The preprocessor macro __SEGGER_RTL_UNLIKELY is configured to indicate that the expression X is unlikely to occur. This enables the compiler to use this information to configure the condition of branch instructions to place exceptional code off the hot trace and not incur branch penalties for the likely execution path.

This definition is specific to the GNU and Clang compilers; configure this to whatever your compiler supports or, if not supported at all, leave __SEGGER_RTL_UNLIKELY undefined.

Thread-local storage

Default

#if defined(__GNUC__) || defined(__clang__)
  #define __SEGGER_RTL_THREAD                   __thread
#endif

Description

The preprocessor symbol __SEGGER_RTL_THREAD can be defined to the storage class specifier for thread-local data, if your compiler supports thread-local storage. There is no standard embedded ABI for RISC-V processors, but for now thread-local storage is accessed using the tp register and is upon the target operating system and whether an operating system is present.

The library has a number of file-scope and external variables that benefit from thread-local storage, such as the implementation of errno.

If your compiler does not support thread-local storage class specifiers or your target does not run an operating system, leave __SEGGER_RTL_THREAD undefined.

Function inlining control

Default

#if (defined(__GNUC__) || defined(__clang__)) && (__SEGGER_RTL_CONFIG_CODE_COVERAGE == 0)
  #ifndef   __SEGGER_RTL_NEVER_INLINE
    #if defined(__clang__)
      #define __SEGGER_RTL_NEVER_INLINE    __attribute__((__noinline__))
    #else
      #define __SEGGER_RTL_NEVER_INLINE    __attribute__((__noinline__, __noclone__))
    #endif
  #endif
  //
  #ifndef   __SEGGER_RTL_ALWAYS_INLINE
    #define __SEGGER_RTL_ALWAYS_INLINE     __inline__ __attribute__((__always_inline__))
  #endif
  //
  #ifndef   __SEGGER_RTL_REQUEST_INLINE
    #define __SEGGER_RTL_REQUEST_INLINE    __inline__
  #endif
  //
#endif

Description

The preprocessor symbols __SEGGER_RTL_NEVER_INLINE, __SEGGER_RTL_ALWAYS_INLINE, and __SEGGER_RTL_REQUEST_INLINE are configured indicate to the compiler the benefit of inlining.

__SEGGER_RTL_NEVER_INLINE should be configured to disable inlining of a function in all cases.

__SEGGER_RTL_ALWAYS_INLINE should be configured to encourage inlining of a function in all cases.

__SEGGER_RTL_REQUEST_INLINE should be configured to indicate that a function benefits from inlining but it is not essential to inline this function. Typically this is used to inline a function when compiling to maximize execution speed and not inline a function when compiling to minimize code size.

The above definitions work for the GNU and clang compilers when targeting Arm. If your compiler is different, configure thsse symbols to suit.

Public API indication

Default

#if defined(__GNUC__) || defined(__clang__)
  #define __SEGGER_RTL_PUBLIC_API               __attribute__((__weak__)) 
#endif

Description

Every function in the library that forms part of the API is labeled using __SEGGER_RTL_PUBLIC_API. For GCC and Clang compilers, all API entry points are defined as weak ELF symbols. You can customize this for your particular compiler or, if compiling the library as part of your project, you can leave this undefined in order to have strong definitions of each library symbol.

Floating-point ABI

Default

#if defined(__riscv_float_abi_soft)
  #define __SEGGER_RTL_FP_ABI                   0
#elif defined(__riscv_float_abi_single)
  #define __SEGGER_RTL_FP_ABI                   1
#elif defined(__riscv_float_abi_double)
  #define __SEGGER_RTL_FP_ABI                   2
#else
  #error Cannot determine RISC-V floating-point ABI
#endif

Description

Configuration of the floating-point ABI in use is determined from the compiler-provided symbols __riscv_float_abi_soft, __riscv_float_abi_single, and __riscv_float_abi_double.

__SEGGER_RTL_FP_ABI must be set to 0 if float and double parameters are passed using integer registes, to 1 if float parameters are passed using floating registers and double parameters are passed using integer registers, and to 2 if both float and double parameters are passed using floating registers.

Floating-point hardware

Default

#if defined(__riscv_flen) && (__riscv_flen == 64)
  #define __SEGGER_RTL_FP_HW                    2
#elif defined(__riscv_flen) && (__riscv_flen == 32)
  #define __SEGGER_RTL_FP_HW                    1
#else
  #define __SEGGER_RTL_FP_HW                    0
#endif

Description

Floating-point hardware support is configured separately from the floating-point calling convention. Even if floating-point parameters are passed in integer registers, it is still possible that floating-point instructions operate on those parameters in the called function.

The ACLE symbol __ARM_FP is queried to determine the target core’s floating-point ability and set __SEGGER_RTL_FP_HW appropriately.

__SEGGER_RTL_FP_HW is set to 0 to indicate that no floating-point hardware exists, to 1 to indicate that hardware exists to support float arithmetic, and to 2 to to indicate that hardware exists to support double arithmetic.

Unfortunately, a fix-up is required:

// Clang gets __ARM_FP wrong for the T16 target ISA indicating
// that floating-point instructions exist in this ISA -- which
// they don't.  Patch that definition up here.
#if __ARM_ARCH_ISA_THUMB == 1
  #undef  __SEGGER_RTL_FP_HW
  #define __SEGGER_RTL_FP_HW                    0
  #undef  __SEGGER_RTL_FP_ABI
  #define __SEGGER_RTL_FP_ABI                   0
#endif

SIMD instruction set extension availability

Default

#if defined(__riscv_dsp)
  #define __SEGGER_RTL_CORE_HAS_ISA_SIMD               1
#else
  #define __SEGGER_RTL_CORE_HAS_ISA_SIMD               0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_ISA_SIMD must be set to 1 if the RISC-V P (packed SIMD) instruction set extension is present, and 0 otherwise.

The assembly-language integer and floating-point implementations benefit significantly in terms of reduced code size and increased execution speed with this instruction set extension.

Andes Performance Extension availability

Default

#if defined(__nds_v5)
  #define __SEGGER_RTL_CORE_HAS_ISA_ANDES_V5           1
#else
  #define __SEGGER_RTL_CORE_HAS_ISA_ANDES_V5           0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_ISA_ANDES_V5 must be set to 1 if the Andes Performance Extension is present, and 0 otherwise.

The assembly-language integer and floating-point implementations benefit in terms of reduced code size and increased execution speed with this instruction set extension.

Multiply instruction availability

Default

#if defined(__riscv_mul)
  #define __SEGGER_RTL_CORE_HAS_MUL_MULH               1
#else
  #define __SEGGER_RTL_CORE_HAS_MUL_MULH               0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_MUL_MULH must be set to 1 if the MUL and MULH instructions are present, and 0 otherwise.

The assembly-language integer and floating-point implementations benefit in terms of reduced code size and increased execution speed with the presence of these instructions.

Divide instruction availability

Default

#if defined(__riscv_div)
  #define __SEGGER_RTL_CORE_HAS_DIV                    1
#else
  #define __SEGGER_RTL_CORE_HAS_DIV                    0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_DIV must be set to 1 if the DIV, DIVU, REM, and REMU instructions are present, and 0 otherwise.

The assembly-language integer and floating-point implementations benefit in terms of reduced code size and increased execution speed with the presence of these instructions.

Count-leading-zeros instruction availability

Default

#if  defined(__riscv_zbb)
  #define __SEGGER_RTL_CORE_HAS_CLZ                    1
#else
  #define __SEGGER_RTL_CORE_HAS_CLZ                    0
#endif

#if defined(__riscv_dsp)
  #define __SEGGER_RTL_CORE_HAS_CLZ32                  1
#else
  #define __SEGGER_RTL_CORE_HAS_CLZ32                  0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_CLZ must be set to 1 if the CLZ instruction from the RISC-V bit-manipulation extension is present, and 0 otherwise.

The preprocessor symbol __SEGGER_RTL_CORE_HAS_CLZ32 must be set to 1 if the SIMD CLZ32 instruction is present, and 0 otherwise.

The assembly-language integer and floating-point implementations benefit in terms of reduced code size and increased execution speed with the presence of these instructions.

The preprocessor symbol __SEGGER_RTL_CLZ_U32 is defined to expand to a way to use the CLZ instruction when the core is known to have one:

#if __SEGGER_RTL_CORE_HAS_CLZ || __SEGGER_RTL_CORE_HAS_CLZ32
  #define __SEGGER_RTL_CLZ_U32(X)        __builtin_clz(X)
#endif

Negated-logic instruction availability

Default

#if defined(__riscv_zbb)
  #define __SEGGER_RTL_CORE_HAS_ANDN_ORN_XORN          1
#else
  #define __SEGGER_RTL_CORE_HAS_ANDN_ORN_XORN          0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_ANDN_ORN_XORN must be set to 1 if the ANDN, ORN, and XORN instructions from the RISC-V bit-manipulation extension are present, and 0 otherwise.

The assembly-language integer and floating-point implementations benefit in terms of reduced code size and increased execution speed with the presence of these instructions.

Bitfield instruction availability

Default

#if defined(__riscv_zbs)
  #define __SEGGER_RTL_CORE_HAS_BSET_BCLR_BINV_BEXT    1
#else
  #define __SEGGER_RTL_CORE_HAS_BSET_BCLR_BINV_BEXT    0
#endif

The preprocessor symbol __SEGGER_RTL_CORE_HAS_BSET_BCLR_BINV_BEXT must be set to 1 if the BSET, BCLR, BINV, and BEXT instructions from the RISC-V bit-manipulation extension are present, and 0 otherwise.

The assembly-language integer and floating-point implementations benefit in terms of reduced code size and increased execution speed with the presence of these instructions.

Shift-and-add instruction availability

Default

#if defined(__riscv_zba)
  #define __SEGGER_RTL_CORE_HAS_SHxADD                 1
#else
  #define __SEGGER_RTL_CORE_HAS_SHxADD                 0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_SHxADD must be set to 1 if the SH1ADD, SH2ADD, and SH3ADD instructions from the RISC-V bit-manipulation extension are present, and 0 otherwise.

The assembly-language integer and floating-point implementations benefit in terms of reduced code size and increased execution speed with the presence of these instructions.

Divide-remainder macro-op fusion availability

Default

#ifndef   __SEGGER_RTL_CORE_HAS_FUSED_DIVREM
  #define __SEGGER_RTL_CORE_HAS_FUSED_DIVREM           0
#endif

Description

The preprocessor symbol __SEGGER_RTL_CORE_HAS_FUSED_DIVREM can be set to 1 if the target supports macro-op fusion of DIV and REM instructions, and 0 otherwise.

As of the time of writing, SEGGER have not seen a core with macro-op fusion of division with remainder and define this to zero unconditionally.

Branch-free code preference

Default

#ifndef   __SEGGER_RTL_PREFER_BRANCH_FREE_CODE
  #define __SEGGER_RTL_PREFER_BRANCH_FREE_CODE         0
#endif

Description

The preprocessor symbol __SEGGER_RTL_PREFER_BRANCH_FREE_CODE must be set to 1 to select branch-free code sequences in preference to branching code sequences.

Whether a target benefits from branch-free code depends upon branch penalties for mispredicted branches and how often these occur in practice. By default this is set to zero, assuming that the branch predictor is more often correct than incorrect, and also reducing overall code size.

For high-performance cores, it may be advantageous to compile using branch-free code.

Runtime support

This section describes how to set up the execution environment for the C library.

Getting to main() and then exit()

Before entering main() the execution environment must be set up such that the C standard library will function correctly.

This section does not describe the compiler or linker support for placing code and data into memory, how to configure any RAM, or how to zero memory required for zero-initialized data. For this, please refer to your toolset compiler and linker documentation.

Nor does this section document how to call constructors and destructors in the correct order. Again, refer to your toolset manuals.

At-exit function support

After returning from main() or by calling exit(), any registered atexit functions must be called to close down. To do this, call __SEGGER_RTL_execute_at_exit_fns() from the runtime startup immdiately after the call to main().

Locale name buffer

For ANSI-correct correct functioning setlocale(), __SEGGER_RTL_set_locale_name_buffer() must be used. If __SEGGER_RTL_set_locale_name_buffer() is not used to set a name buffer, setlocale() will still set the locale but will return NULL rather than the previous locale.

Please refer to setlocale for further information.

Dynamic storage and the heap

emRun provides three heap implementations which you may choose from:

Multithreaded protection for the heap

Heap functions (allocation, reallocation, deallocation) can be protected from reentrancy in a multithreaded environment by implementing lock and unlock functions. By default, these functions do nothing and memory allocation functions are not protected.

See __SEGGER_RTL_X_heap_lock and __SEGGER_RTL_X_heap_unlock.

Setting up the heap

Whichever heap implementation is chosen, the dynamic memory managed by the heap must be initialized by calling __SEGGER_RTL_init_heap() passing the base address of the managed area and its size in bytes.

This initialization is typically carried out as part of system startup, before any constructors are called.

Input and output

The way characters and strings are printed and scanned can be configured in multiple ways. This section describes how a generic implementation works, how to optimize input and output for other technologies such as SEGGER RTT and SEGGER semihosting, and how to optimized for UART-style I/O.

Standard input and output

Standard input and output are performed using the low-level functions __SEGGER_RTL_X_file_read() and __SEGGER_RTL_X_file_write(), These functions are defined in the file __SEGGER_RTL.h as follows:

int __SEGGER_RTL_X_file_read  (__SEGGER_RTL_FILE *stream, char *s, unsigned len);
int __SEGGER_RTL_X_file_write (__SEGGER_RTL_FILE *stream, const char *s, unsigned len);

The type __SEGGER_RTL_FILE and its corresponding standard C version FILE are defined opaqely by __SEGGER_RTL.h as:

typedef struct __SEGGER_RTL_FILE_IMPL __SEGGER_RTL_FILE;
typedef struct __SEGGER_RTL_FILE_IMPL FILE;

This leaves the exact structure of a FILE and the implementation of file I/O to the library integrator. The following are sample implementations for SEGGER RTT, SEGGER Semihosting, and a version that supports only output to a UART.

Using SEGGER RTT for I/O

Complete listing

/*********************************************************************
*                   (c) SEGGER Microcontroller GmbH                  *
*                        The Embedded Experts                        *
*                           www.segger.com                           *
**********************************************************************

-------------------------- END-OF-HEADER -----------------------------
*/

/*********************************************************************
*
*       #include section
*
**********************************************************************
*/

#include "__SEGGER_RTL_Int.h"
#include "stdio.h"
#include "RTT/SEGGER_RTT.h"

/*********************************************************************
*
*       Local types
*
**********************************************************************
*/

struct __SEGGER_RTL_FILE_impl {
  int handle;
};

/*********************************************************************
*
*       Static data
*
**********************************************************************
*/

static FILE __SEGGER_RTL_stdin_file  = { 0 };  // stdin reads from RTT buffer #0
static FILE __SEGGER_RTL_stdout_file = { 0 };  // stdout writes to RTT buffer #0
static FILE __SEGGER_RTL_stderr_file = { 0 };  // stdout writes to RTT buffer #0
static int  __SEGGER_RTL_stdin_ungot = EOF;

/*********************************************************************
*
*       Public data
*
**********************************************************************
*/

FILE *stdin  = &__SEGGER_RTL_stdin_file;
FILE *stdout = &__SEGGER_RTL_stdout_file;
FILE *stderr = &__SEGGER_RTL_stderr_file;

/*********************************************************************
*
*       Static code
*
**********************************************************************
*/

/*********************************************************************
*
*       __SEGGER_RTL_stdin_getc()
*
*  Function description
*    Get character from standard input.
*
*  Return value
*    Character received.
*
*  Additional information
*    This function never fails to deliver a character.
*/
static char __SEGGER_RTL_stdin_getc(void) {
  int  r;
  char c;
  //
  if (__SEGGER_RTL_stdin_ungot != EOF) {
    c = __SEGGER_RTL_stdin_ungot;
    __SEGGER_RTL_stdin_ungot = EOF;
  } else {
    do {
      r = SEGGER_RTT_Read(stdin->handle, &c, 1);
    } while (r == 0);
  }
  //
  return c;
}

/*********************************************************************
*
*       Public code
*
**********************************************************************
*/

/*********************************************************************
*
*       __SEGGER_RTL_X_file_stat()
*
*  Function description
*    Get file status.
*
*  Parameters
*    stream - Pointer to file.
*
*  Additional information
*    Low-overhead test to determine if stream is valid.  If stream
*    is a valid pointer and the stream is open, this function must
*    succeed.  If stream is a valid pointer and the stream is closed,
*    this function must fail.
*
*    The implementation may optionally determine whether stream is
*    a valid pointer: this may not always be possible and is not
*    required, but may assist debugging when clients provide wild
*    pointers.
*
*  Return value
*    <  0 - Failure, stream is not a valid file.
*    >= 0 - Success, stream is a valid file.
*/
int __SEGGER_RTL_X_file_stat(__SEGGER_RTL_FILE *stream) {
  if (stream == stdin || stream == stdout || stream == stderr) {
    return 0;
  } else {
    return EOF;
  }
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_bufsize()
*
*  Function description
*    Get stream buffer size.
*
*  Parameters
*    stream - Pointer to file.
*
*  Additional information
*    Returns the number of characters to use for buffered I/O on
*    the file stream.  The I/O buffer is allocated on the stack
*    for the duration of the I/O call, therefore this value should
*    not be set arbitrarily large.
*
*    For unbuffered I/O, return 1.
*
*  Return value
*    Nonzero number of characters to use for buffered I/O; for
*    unbuffered I/O, return 1.
*/
int __SEGGER_RTL_X_file_bufsize(__SEGGER_RTL_FILE *stream) {
  //
  __SEGGER_RTL_USE_PARA(stream);
  //
  return 64;
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_read()
*
*  Function description
*    Read data from file.
*
*  Parameters
*    stream - Pointer to file to read from.
*    s      - Pointer to object that receives the input.
*    len    - Number of characters to read from file.
*
*  Return value
*    >= 0 - Success.
*    <  0 - Failure.
*
*  Additional information
*    Reading from any stream other than stdin results in an error.
*/
int __SEGGER_RTL_X_file_read(__SEGGER_RTL_FILE * stream,
                             char              * s,
                             unsigned            len) {
  int c;
  //
  if (stream == stdin) {
    c = 0;
    while (len > 0) {
      *s++ = __SEGGER_RTL_stdin_getc();
      --len;
    }
  } else {
    c = EOF;
  }
  //
  return c;
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_flush()
*
*  Function description
*    Flush unwritten data to file.
*
*  Parameters
*    stream - Pointer to file.
*
*  Return value
*    <  0 - Failure, file cannot be flushed or was not successfully flushed.
*    == 0 - Success, unwritten data is flushed.
*/
int __SEGGER_RTL_X_file_flush(__SEGGER_RTL_FILE *stream) {
  //
  __SEGGER_RTL_USE_PARA(stream);
  //
  return 0;
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_write()
*
*  Function description
*    Write data to file.
*
*  Parameters
*    stream - Pointer to file to write to.
*    s      - Pointer to object to write to file.
*    len    - Number of characters to write to the file.
*
*  Return value
*    >= 0 - Success.
*    <  0 - Failure.
*
*  Additional information
*    stdout is directed to RTT buffer #0; stderr is directed to RTT buffer #1;
*    writing to any stream other than stdout or stderr results in an error
*/
int __SEGGER_RTL_X_file_write(__SEGGER_RTL_FILE *stream, const char *s, unsigned len) {
  return SEGGER_RTT_Write(stream->handle, s, len);
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_unget()
*
*  Function description
*    Push character back to stream.
*
*  Parameters
*    stream - Pointer to file to push back to.
*    c      - Character to push back.
*
*  Return value
*    >= 0 - Success.
*    <  0 - Failure.
*
*  Additional information
*    Push-back is only supported for standard input, and
*    only a single-character pushback buffer is implemented.
*/
int __SEGGER_RTL_X_file_unget(__SEGGER_RTL_FILE *stream, int c) {
  if (stream == stdin) {
    if (c != EOF && __SEGGER_RTL_stdin_ungot == EOF) {
      __SEGGER_RTL_stdin_ungot = c;
    } else {
      c = EOF;
    }
  } else {
    c = EOF;
  }
  //
  return c;
}

/*************************** End of file ****************************/

Using SEGGER semihosting for I/O

Complete listing

/*********************************************************************
*                   (c) SEGGER Microcontroller GmbH                  *
*                        The Embedded Experts                        *
*                           www.segger.com                           *
**********************************************************************

-------------------------- END-OF-HEADER -----------------------------
*/

/*********************************************************************
*
*       #include section
*
**********************************************************************
*/

#include "__SEGGER_RTL_Int.h"
#include "stdio.h"
#include "SEMIHOST/SEGGER_SEMIHOST.h"

/*********************************************************************
*
*       Local types
*
**********************************************************************
*/

struct __SEGGER_RTL_FILE_impl {
  int handle;
};

/*********************************************************************
*
*       Static data
*
**********************************************************************
*/

static FILE __SEGGER_RTL_stdin_file  = { SEGGER_SEMIHOST_STDIN  };
static FILE __SEGGER_RTL_stdout_file = { SEGGER_SEMIHOST_STDOUT };
static FILE __SEGGER_RTL_stderr_file = { SEGGER_SEMIHOST_ERROUT };
static int  __SEGGER_RTL_stdin_ungot = EOF;

/*********************************************************************
*
*       Public data
*
**********************************************************************
*/

FILE *stdin  = &__SEGGER_RTL_stdin_file;
FILE *stdout = &__SEGGER_RTL_stdout_file;
FILE *stderr = &__SEGGER_RTL_stderr_file;

/*********************************************************************
*
*       Static code
*
**********************************************************************
*/

/*********************************************************************
*
*       __SEGGER_RTL_X_file_stat()
*
*  Function description
*    Get file status.
*
*  Parameters
*    stream - Pointer to file.
*
*  Additional information
*    Low-overhead test to determine if stream is valid.  If stream
*    is a valid pointer and the stream is open, this function must
*    succeed.  If stream is a valid pointer and the stream is closed,
*    this function must fail.
*
*    The implementation may optionally determine whether stream is
*    a valid pointer: this may not always be possible and is not
*    required, but may assist debugging when clients provide wild
*    pointers.
*
*  Return value
*    <  0 - Failure, stream is not a valid file.
*    >= 0 - Success, stream is a valid file.
*/
int __SEGGER_RTL_X_file_stat(__SEGGER_RTL_FILE *stream) {
  if (stream == stdin || stream == stdout || stream == stderr) {
    return 0;
  } else {
    return EOF;
  }
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_bufsize()
*
*  Function description
*    Get stream buffer size.
*
*  Parameters
*    stream - Pointer to file.
*
*  Additional information
*    Returns the number of characters to use for buffered I/O on
*    the file stream.  The I/O buffer is allocated on the stack
*    for the duration of the I/O call, therefore this value should
*    not be set arbitrarily large.
*
*    For unbuffered I/O, return 1.
*
*  Return value
*    Nonzero number of characters to use for buffered I/O; for
*    unbuffered I/O, return 1.
*/
int __SEGGER_RTL_X_file_bufsize(__SEGGER_RTL_FILE *stream) {
  return 64;
}

/*********************************************************************
*
*       __SEGGER_RTL_stdin_getc()
*
*  Function description
*    Get character from standard input.
*
*  Return value
*    >= 0   - Character read.
*    == EOF - End of stream or error reading.
*
*  Additional information
*    This function never fails to deliver a character.
*/
static int __SEGGER_RTL_stdin_getc(void) {
  int  r;
  char c;
  //
  if (__SEGGER_RTL_stdin_ungot != EOF) {
    c = __SEGGER_RTL_stdin_ungot;
    __SEGGER_RTL_stdin_ungot = EOF;
    r = 0;
  } else {
    r = SEGGER_SEMIHOST_ReadC();
  }
  //
  return r < 0 ? EOF : c;
}

/*********************************************************************
*
*       Public code
*
**********************************************************************
*/

/*********************************************************************
*
*       __SEGGER_RTL_X_file_read()
*
*  Function description
*    Read data from file.
*
*  Parameters
*    stream - Pointer to file to read from.
*    s      - Pointer to object that receives the input.
*    len    - Number of characters to read from file.
*
*  Return value
*    >= 0 - Success.
*    <  0 - Failure.
*
*  Additional information
*    Reading from any stream other than stdin results in an error.
*/
int __SEGGER_RTL_X_file_read(__SEGGER_RTL_FILE * stream,
                             char              * s,
                             unsigned            len) {
  int c;
  //
  if (stream == stdin) {
    c = 0;
    while (len > 0) {
      *s++ = __SEGGER_RTL_stdin_getc();
      --len;
    }
  } else {
    c = SEGGER_SEMIHOST_Read(stream->handle, s, len);
  }
  //
  return c;
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_write()
*
*  Function description
*    Write data to file.
*
*  Parameters
*    stream - Pointer to file to write to.
*    s      - Pointer to object to write to file.
*    len    - Number of characters to write to the file.
*
*  Return value
*    >= 0 - Success.
*    <  0 - Failure.
*/
int __SEGGER_RTL_X_file_write(__SEGGER_RTL_FILE *stream, const char *s, unsigned len) {
  int r;
  //
  r = SEGGER_SEMIHOST_Write(stream->handle, s, len);
  if (r < 0) {
    r = EOF;
  }
  //
  return r;
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_unget()
*
*  Function description
*    Push character back to stream.
*
*  Parameters
*    stream - Pointer to stream to push back to.
*    c      - Character to push back.
*
*  Return value
*    >= 0 - Success.
*    <  0 - Failure.
*
*  Additional information
*    Push-back is only supported for standard input, and
*    only a single-character pushback buffer is implemented.
*/
int __SEGGER_RTL_X_file_unget(__SEGGER_RTL_FILE *stream, int c) {
  if (stream == stdin) {
    if (c != EOF && __SEGGER_RTL_stdin_ungot == EOF) {
      __SEGGER_RTL_stdin_ungot = c;
    } else {
      c = EOF;
    }
  } else {
    c = EOF;
  }
  //
  return c;
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_flush()
*
*  Function description
*    Flush unwritten data to file.
*
*  Parameters
*    stream - Pointer to file.
*
*  Return value
*    <  0 - Failure, file cannot be flushed or was not successfully flushed.
*    == 0 - Success, unwritten data is flushed.
*/
int __SEGGER_RTL_X_file_flush(__SEGGER_RTL_FILE *stream) {
  return 0;
}

/*************************** End of file ****************************/

Using a UART for I/O

Complete listing

/*********************************************************************
*                   (c) SEGGER Microcontroller GmbH                  *
*                        The Embedded Experts                        *
*                           www.segger.com                           *
**********************************************************************

-------------------------- END-OF-HEADER -----------------------------
*/

/*********************************************************************
*
*       #include section
*
**********************************************************************
*/

#include "__SEGGER_RTL_Int.h"
#include "stdio.h"

/*********************************************************************
*
*       Local types
*
**********************************************************************
*/

struct __SEGGER_RTL_FILE_impl {
  int handle;  // At least one field required (but unused) to ensure
               // the three file descriptors have unique addresses.
};

/*********************************************************************
*
*       Prototypes
*
**********************************************************************
*/

#ifdef __cplusplus
extern "C"
#endif
int metal_tty_putc(int c);  // UART output function

/*********************************************************************
*
*       Static data
*
**********************************************************************
*/

static FILE __SEGGER_RTL_stdin  = { 0 };
static FILE __SEGGER_RTL_stdout = { 1 };
static FILE __SEGGER_RTL_stderr = { 2 };

/*********************************************************************
*
*       Public data
*
**********************************************************************
*/

FILE *stdin  = &__SEGGER_RTL_stdin;
FILE *stdout = &__SEGGER_RTL_stdout;
FILE *stderr = &__SEGGER_RTL_stderr;

/*********************************************************************
*
*       Public code
*
**********************************************************************
*/

/*********************************************************************
*
*       __SEGGER_RTL_X_file_stat()
*
*  Function description
*    Get file status.
*
*  Parameters
*    stream - Pointer to file.
*
*  Additional information
*    Low-overhead test to determine if stream is valid.  If stream
*    is a valid pointer and the stream is open, this function must
*    succeed.  If stream is a valid pointer and the stream is closed,
*    this function must fail.
*
*    The implementation may optionally determine whether stream is
*    a valid pointer: this may not always be possible and is not
*    required, but may assist debugging when clients provide wild
*    pointers.
*
*  Return value
*    <  0 - Failure, stream is not a valid file.
*    >= 0 - Success, stream is a valid file.
*/
int __SEGGER_RTL_X_file_stat(__SEGGER_RTL_FILE *stream) {
  if (stream == stdin || stream == stdout || stream == stderr) {
    return 0;
  } else {
    return EOF;
  }
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_bufsize()
*
*  Function description
*    Get stream buffer size.
*
*  Parameters
*    stream - Pointer to file.
*
*  Additional information
*    Returns the number of characters to use for buffered I/O on
*    the file stream.  The I/O buffer is allocated on the stack
*    for the duration of the I/O call, therefore this value should
*    not be set arbitrarily large.
*
*    For unbuffered I/O, return 1.
*
*  Return value
*    Nonzero number of characters to use for buffered I/O; for
*    unbuffered I/O, return 1.
*/
int __SEGGER_RTL_X_file_bufsize(__SEGGER_RTL_FILE *stream) {
  return 1;
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_read()
*
*  Function description
*    Read data from file.
*
*  Parameters
*    stream - Pointer to file to read from.
*    s      - Pointer to object that receives the input.
*    len    - Number of characters to read from file.
*
*  Return value
*    >= 0 - Success.
*    <  0 - Failure.
*
*  Additional information
*    As input from the UART is not supported, this function always fails.
*/
int __SEGGER_RTL_X_file_read(__SEGGER_RTL_FILE * stream,
                             char              * s,
                             unsigned            len) {
  return EOF;
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_write()
*
*  Function description
*    Write data to file.
*
*  Parameters
*    stream - Pointer to file to write to.
*    s      - Pointer to object to write to file.
*    len    - Number of characters to write to the file.
*
*  Return value
*    >= 0 - Success.
*    <  0 - Failure.
*
*  Additional information
*    Writing to any file other than stdout or stderr results in an error.
*/
int __SEGGER_RTL_X_file_write(__SEGGER_RTL_FILE *stream, const char *s, unsigned len) {
  int r;
  //
  if (stream == stdout || stream == stderr) {
    r = len;
    while (len > 0) {
      metal_tty_putc(*s++);
      --len;
    }
  } else {
    r = EOF;
  }
  //
  return r;
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_unget()
*
*  Function description
*    Push character back to stream.
*
*  Parameters
*    stream - Pointer to file to push back to.
*    c      - Character to push back.
*
*  Return value
*    >= 0 - Success.
*    <  0 - Failure.
*
*  Additional information
*    As input from the UART is not supported, this function always fails.
*/
int __SEGGER_RTL_X_file_unget(__SEGGER_RTL_FILE *stream, int c) {
  return EOF;
}

/*********************************************************************
*
*       __SEGGER_RTL_X_file_flush()
*
*  Function description
*    Flush unwritten data to file.
*
*  Parameters
*    stream - Pointer to file.
*
*  Return value
*    <  0 - Failure, file cannot be flushed or was not successfully flushed.
*    == 0 - Success, unwritten data is flushed.
*/
int __SEGGER_RTL_X_file_flush(__SEGGER_RTL_FILE *stream) {
  return 0;
}

/*************************** End of file ****************************/

Thread safety

Functions in emRun are written with varing levels of thread-safe operation. Some functions are inherently re-entrant and thread-safe, some are thread-safe if configured to be so, and some are never thread-safe.

The following section desfribe the various ways that the execution environment for a C or C++ program can be configured.

No threading

In this case there are no separate threads of execution save for interrupt and exception handlers. In this case, emRun will not be required to support thread-local storage and the __SEGGER_RTL_THREAD macro can be defined to be empty and the heap-lock and heap-unlock functions can be empty.

It is the user’s responsibility to ensure there is no conflict in the use of shared data between mainline code and interrupt-handling code.

In this scenario, all functions are inherently thread-safe as there is no threading.

Threading with no RTOS thread-local support

In this case there are separate threads of execution but only a single instance of emRun private data. As such, any function that manipulates emRun private data, directly or indirectly, is thread-unsafe.

Although emRun can be configured this way, it is highly likely that cross-contamination of emRun private data will occur. For instance, errno will be shared between all threads and code such as the following is prone to failure:

errno = 0;
d = strtod(sInput, NULL);
if (errno != 0) { ... }

At first glance, the above code looks entirely reasonable. However, in this configuration a thread could be scheduled between setting and reading errno, potentially corrupting the value of errno for the original thread. Such errors are very hard to track down.

In this configuration, there can be no guarantee made regarding thread-safety of emRun and the “Thread safety” section in each function desciption must be ignored.

Threading with RTOS thread-local support

In this case there are separate threads of execution with each thread receiving its own copy of emRun private data. As such, any function that manipulates private data, directly or indirectly, is thread-safe.

In contrast to the previous configuration, each thread receives its own private copy of errno and cross-contamination of emRun runtime data will not occur inside emRun functions.

Functions that are re-entrant and thread-safe

Functions that only take scalar data (chars, integers, reals) and do not read global state are both re-entrant and thread-safe. For instance, sin() is thread-safe as the floating-point environment is per-thread and sin() does not use any global state variables.

Other functions, such as strcat(), are re-entrant and thread-safe only if the objects they operate on are not shared between threads. For instance, it is not possible for two or more threads to use strcat() to concatenate data into a single array shared between the two threads, such as appending to some in-memory error or trace log.

Functions that are thread-safe if configured

Per-thread global data in emRun is declared using the __SEGGER_RTL_THREAD macro; see Thread-local storage.

errno

The errno macro is thread-safe if both emRun and the underlying RTOS is configured to support thread-local data.

If you have not configured per-thread storage or the RTOS does not support thread-local storage, there will be a single instance of emRun private data shared between all threads and therefore any function mentioned above, or any function that potentially sets errno, directly or indirectly, will write a single instance of it and will not be thread-safe.

String and multi-byte functions

The following functions are thread-safe if both emRun and the underlying RTOS is configured to support thread-local data.

If you have not configured per-thread storage or the RTOS does not support thread-local storage, there will be a single instance of emRun private data shared between all threads and therefore any function mentioned above, or any function that potentially sets uses these directly or indirectly, will write a single instance of emRun private data and will not be thread-safe.

Note that it is well understood that functions maintaining global state are undesirable from a program design and multi-threading perspective. This has been recognized by industry standards bodies, such as The Open Group, and this has led to the introduction of “restartable” functions in, for instance, the POSIX.1 standard. emRun implements restartable functions that appear in POSIX.1, such as strtok_r().

Restartable functions are preferable to multi-threading-enabled versions of the standard functions because they do not introduce a per-thread overhead (where threads that do not use e.g. strtok() still pay to have thread-local state reserved for it) and also because access to thread-local data is more expensive than accessing data provided as an additional parameter to the function.

Locale-aware functions

All functions that use or set a locale are thread-safe if both emRun and the underlying RTOS is configured to support thread-local data. This includes all character type and conversion functions, multibyte functions, and locale maipulation funtions.

Heap functions

Heap functions are thread-safe if and only if the heap-lock and heap-unlock functions __SEGGER_RTL_X_heap_lock() and __SEGGER_RTL_X_heap_unlock() are present and prevent simultaneous use of the shared heap. These two functions ensure that the heap is in use by a single execution context only. If these functions are not provided, the heap is unprotected and is not thread-safe.

Functions that are never thread-safe

All I/O functions that work on streams are never thread safe. A design goal of the C library is to be efficient and, as such, it is not possible to share files and streams between threads. Should this be required, the user is responsible for using an appropriate locking mechanism outside of emRun to ensure no stream is simultaneously in use by two or more threads.

Thread-safety sections

Where applicable, thread-safety relating to a multi-threaded system is described using the following:

C library API

<assert.h>

Assertion functions

Function Description
assert Place assertion.
assert

Description

Place assertion.

Definition

#define assert(e)    ...

Additional information

If NDEBUG is defined as a macro name at the point in the source file where <assert.h> is included, the assert() macro is defined as:

#define assert(ignore) ((void)0)

If NDEBUG is not defined as a macro name at the point in the source file where <assert.h> is included, the assert() macro expands to a void expression that calls __SEGGER_RTL_X_assert().

When such an assert is executed and e is false, assert() calls the function __SEGGER_RTL_X_assert() with information about the particular call that failed: the text of the argument, the name of the source file, and the source line number. These are the stringized expression and the values of the preprocessing macros __FILE__ and __LINE__.

Notes

The assert() macro is redefined according to the current state of NDEBUG each time that <assert.h> is included.

<complex.h>

emRun provides complex math library functions, including all of those required by ISO C99. These functions are implemented to balance performance with correctness. Because producing the correctly rounded result may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 ulp of the correctly rounded result, though there may be cases where there is greater inaccuracy.

Manipulation functions

Function Description
cabs() Compute magnitude, double complex.
cabsf() Compute magnitude, float complex.
cabsl() Compute magnitude, long double complex.
carg() Compute phase, double complex.
cargf() Compute phase, float complex.
cargl() Compute phase, long double complex.
cimag() Imaginary part, double complex.
cimagf() Imaginary part, float complex.
cimagl() Imaginary part, long double complex.
creal() Real part, double complex.
crealf() Real part, float complex.
creall() Real part, long double complex.
cproj() Project, double complex.
cprojf() Project, float complex.
cprojl() Project, long double complex.
conj() Conjugate, double complex.
conjf() Conjugate, float complex.
conjl() Conjugate, long double complex.
cabs()

Description

Compute magnitude, double complex.

Prototype

double cabs(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute magnitude of.

Return value

The magnitude of x, |x|.

Thread safety

Safe.

cabsf()

Description

Compute magnitude, float complex.

Prototype

float cabsf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute magnitude of.

Return value

The magnitude of x, |x|.

Thread safety

Safe.

cabsl()

Description

Compute magnitude, long double complex.

Prototype

long double cabsl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute magnitude of.

Return value

The magnitude of x, |x|.

Thread safety

Safe.

carg()

Description

Compute phase, double complex.

Prototype

double carg(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute phase of.

Return value

The phase of x.

Thread safety

Safe.

cargf()

Description

Compute phase, float complex.

Prototype

float cargf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute phase of.

Return value

The phase of x.

Thread safety

Safe.

cargl()

Description

Compute phase, long double complex.

Prototype

long double cargl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute phase of.

Return value

The phase of x.

Thread safety

Safe.

cimag()

Description

Imaginary part, double complex.

Prototype

double cimag(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

The imaginary part of the complex value.

Thread safety

Safe.

cimagf()

Description

Imaginary part, float complex.

Prototype

float cimagf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

The imaginary part of the complex value.

Thread safety

Safe.

cimagl()

Description

Imaginary part, long double complex.

Prototype

long double cimagl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

The imaginary part of the complex value.

Thread safety

Safe.

creal()

Description

Real part, double complex.

Prototype

double creal(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

The real part of the complex value.

Thread safety

Safe.

crealf()

Description

Real part, float complex.

Prototype

float crealf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

The real part of the complex value.

Thread safety

Safe.

creall()

Description

Real part, long double complex.

Prototype

long double creall(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

The real part of the complex value.

Thread safety

Safe.

cproj()

Description

Project, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX cproj(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to project.

Return value

The projection of x to the Reimann sphere.

Additional information

x projects to x, except that all complex infinities (even those with one infinite part and one NaN part) project to positive infinity on the real axis. If x has an infinite part, then cproj(x) is be equivalent to:

Thread safety

Safe.

cprojf()

Description

Project, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX cprojf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to project.

Return value

The projection of x to the Reimann sphere.

Additional information

x projects to x, except that all complex infinities (even those with one infinite part and one NaN part) project to positive infinity on the real axis. If x has an infinite part, then cproj(x) is be equivalent to:

Thread safety

Safe.

cprojl()

Description

Project, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX cprojl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to project.

Return value

The projection of x to the Reimann sphere.

Additional information

x projects to x, except that all complex infinities (even those with one infinite part and one NaN part) project to positive infinity on the real axis. If x has an infinite part, then cproj(x) is be equivalent to:

Thread safety

Safe.

conj()

Description

Conjugate, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX conj(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to conjugate.

Return value

The complex conjugate of x.

Thread safety

Safe.

conjf()

Description

Conjugate, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX conjf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to conjugate.

Return value

The complex conjugate of x.

Thread safety

Safe.

conjl()

Description

Conjugate, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX conjl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to conjugate.

Return value

The complex conjugate of x.

Thread safety

Safe.

Trigonometric functions

Function Description
csin() Compute sine, double complex.
csinf() Compute sine, float complex.
csinl() Compute sine, long double complex.
ccos() Compute cosine, double complex.
ccosf() Compute cosine, float complex.
ccosl() Compute cosine, long double complex.
ctan() Compute tangent, double complex.
ctanf() Compute tangent, float complex.
ctanl() Compute tangent, long double complex.
casin() Compute inverse sine, double complex.
casinf() Compute inverse sine, float complex.
casinl() Compute inverse sine, long double complex.
cacos() Compute inverse cosine, double complex.
cacosf() Compute inverse cosine, float complex.
cacosl() Compute inverse cosine, long double complex.
catan() Compute inverse tangent, double complex.
catanf() Compute inverse tangent, float complex.
catanl() Compute inverse tangent, long double complex.
csin()

Description

Compute sine, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX csin(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute sine of.

Return value

The sine of x.

Thread safety

Safe.

csinf()

Description

Compute sine, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX csinf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute sine of.

Return value

The sine of x.

Thread safety

Safe.

csinl()

Description

Compute sine, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX csinl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute sine of.

Return value

The sine of x.

Thread safety

Safe.

ccos()

Description

Compute cosine, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX ccos(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute cosine of.

Return value

The cosine of x.

Thread safety

Safe.

ccosf()

Description

Compute cosine, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX ccosf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute cosine of.

Return value

The cosine of x.

Thread safety

Safe.

ccosl()

Description

Compute cosine, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX ccosl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute cosine of.

Return value

The cosine of x.

Thread safety

Safe.

ctan()

Description

Compute tangent, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX ctan(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute tangent of.

Return value

The tangent of x.

Thread safety

Safe.

ctanf()

Description

Compute tangent, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX ctanf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute tangent of.

Return value

The tangent of x.

Thread safety

Safe.

ctanl()

Description

Compute tangent, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX ctanl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute tangent of.

Return value

The tangent of x.

Thread safety

Safe.

casin()

Description

Compute inverse sine, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX casin(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

Inverse sine of x.

Notes

casin(z) = -i casinh(i.z)

Thread safety

Safe.

casinf()

Description

Compute inverse sine, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX casinf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

Inverse sine of x.

Notes

casin(z) = -i casinh(i.z)

Thread safety

Safe.

casinl()

Description

Compute inverse sine, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX casinl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

Inverse sine of x.

Notes

casinl(z) = -i casinhl(i.z)

Thread safety

Safe.

cacos()

Description

Compute inverse cosine, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX cacos(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse cosine of.

Return value

The inverse cosine of x.

Thread safety

Safe.

cacosf()

Description

Compute inverse cosine, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX cacosf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse cosine of.

Return value

The inverse cosine of x.

Thread safety

Safe.

cacosl()

Description

Compute inverse cosine, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX cacosl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse cosine of.

Return value

The inverse cosine of x.

Thread safety

Safe.

catan()

Description

Compute inverse tangent, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX catan(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

Inverse tangent of x.

Notes

catan(z) = -i catanh(i.z)

Thread safety

Safe.

catanf()

Description

Compute inverse tangent, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX catanf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

Inverse tangent of x.

Notes

catan(z) = -i catanh(i.z)

Thread safety

Safe.

catanl()

Description

Compute inverse tangent, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX catanl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Argument.

Return value

Inverse tangent of x.

Notes

catanl(z) = -i catanhl(i.z)

Thread safety

Safe.

Hyperbolic functions

Function Description
csinh() Compute hyperbolic sine, double complex.
csinhf() Compute hyperbolic sine, float complex.
csinhl() Compute hyperbolic sine, long double complex.
ccosh() Compute hyperbolic cosine, double complex.
ccoshf() Compute hyperbolic cosine, float complex.
ccoshl() Compute hyperbolic cosine, long double complex.
ctanh() Compute hyperbolic tangent, double complex.
ctanhf() Compute hyperbolic tangent, float complex.
ctanhl() Compute hyperbolic tangent, long double complex.
casinh() Compute inverse hyperbolic sine, double complex.
casinhf() Compute inverse hyperbolic sine, float complex.
casinhl() Compute inverse hyperbolic sine, long double complex.
cacosh() Compute inverse hyperbolic cosine, double complex.
cacoshf() Compute inverse hyperbolic cosine, float complex.
cacoshl() Compute inverse hyperbolic cosine, long double complex.
catanh() Compute inverse hyperbolic tangent, double complex.
catanhf() Compute inverse hyperbolic tangent, float complex.
catanhl() Compute inverse hyperbolic tangent, long double complex.
csinh()

Description

Compute hyperbolic sine, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX csinh(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute hyperbolic sine of.

Return value

The hyperbolic sine of x according to the following table:

Argument csinh(Argument)
+0 + 0i +0 + 0i
+0 + ∞i ±0 + NaNi, sign of real part unspecified
+0 + NaNi ±0 + NaNi, sign of real part unspecified
a + ∞i NaN + NaNi, for positive finite a
a + NaNi NaN + NaNi, for finite nonzero a
+∞ + 0i +∞ + 0i
+∞ + bi +∞×cos(b) + +∞×sin(b).i for positive finite b
+∞ + ∞i ±∞ + NaNi, sign of real part unspecified
+∞ + NaNi ±∞ + NaNi, sign of real part unspecified
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for all nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

csinhf()

Description

Compute hyperbolic sine, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX csinhf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute hyperbolic sine of.

Return value

The hyperbolic sine of x according to the following table:

Argument csinh(Argument)
+0 + 0i +0 + 0i
+0 + ∞i ±0 + NaNi, sign of real part unspecified
+0 + NaNi ±0 + NaNi, sign of real part unspecified
a + ∞i NaN + NaNi, for positive finite a
a + NaNi NaN + NaNi, for finite nonzero a
+∞ + 0i +∞ + 0i
+∞ + bi +∞×cos(b) + +∞×sin(b).i for positive finite b
+∞ + ∞i ±∞ + NaNi, sign of real part unspecified
+∞ + NaNi ±∞ + NaNi, sign of real part unspecified
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for all nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

csinhl()

Description

Compute hyperbolic sine, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX csinhl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute hyperbolic sine of.

Return value

The hyperbolic sine of x according to the following table:

Argument csinh(Argument)
+0 + 0i +0 + 0i
+0 + ∞i ±0 + NaNi, sign of real part unspecified
+0 + NaNi ±0 + NaNi, sign of real part unspecified
a + ∞i NaN + NaNi, for positive finite a
a + NaNi NaN + NaNi, for finite nonzero a
+∞ + 0i +∞ + 0i
+∞ + bi +∞×cos(b) + +∞×sin(b).i for positive finite b
+∞ + ∞i ±∞ + NaNi, sign of real part unspecified
+∞ + NaNi ±∞ + NaNi, sign of real part unspecified
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for all nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

ccosh()

Description

Compute hyperbolic cosine, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX ccosh(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute hyperbolic cosine of.

Return value

The hyperbolic cosine of x according to the following table:

Argument ccosh(Argument)
+0 + 0i +1 + 0i
+0 + ∞i NaN + ±0i, sign of imaginary part unspecified
+0 + NaNi NaN + ±0i, sign of imaginary part unspecified
a + ∞i NaN + NaNi, for finite nonzero a
a + NaNi NaN + NaNi, for finite nonzero a
+∞ + 0i +∞ + 0i
+∞ + bi +∞×cos(b) + Inf×sin(b).i for finite nonzero b
+∞ + ∞i +∞ + NaNi
+∞ + NaNi +∞ + NaNi
NaN + 0i NaN + ±0i, sign of imaginary part unspecified
NaN + bi NaN + NaNi, for all nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

ccoshf()

Description

Compute hyperbolic cosine, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX ccoshf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute hyperbolic cosine of.

Return value

The hyperbolic cosine of x according to the following table:

Argument ccosh(Argument)
+0 + 0i +1 + 0i
+0 + ∞i NaN + ±0i, sign of imaginary part unspecified
+0 + NaNi NaN + ±0i, sign of imaginary part unspecified
a + ∞i NaN + NaNi, for finite nonzero a
a + NaNi NaN + NaNi, for finite nonzero a
+∞ + 0i +∞ + 0i
+∞ + bi +∞×cos(b) + Inf×sin(b).i for finite nonzero b
+∞ + ∞i +∞ + NaNi
+∞ + NaNi +∞ + NaNi
NaN + 0i NaN + ±0i, sign of imaginary part unspecified
NaN + bi NaN + NaNi, for all nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

ccoshl()

Description

Compute hyperbolic cosine, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX ccoshl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute hyperbolic cosine of.

Return value

The hyperbolic cosine of x according to the following table:

Argument ccosh(Argument)
+0 + 0i +1 + 0i
+0 + ∞i NaN + ±0i, sign of imaginary part unspecified
+0 + NaNi NaN + ±0i, sign of imaginary part unspecified
a + ∞i NaN + NaNi, for finite nonzero a
a + NaNi NaN + NaNi, for finite nonzero a
+∞ + 0i +∞ + 0i
+∞ + bi +∞×cos(b) + Inf×sin(b).i for finite nonzero b
+∞ + ∞i +∞ + NaNi
+∞ + NaNi +∞ + NaNi
NaN + 0i NaN + ±0i, sign of imaginary part unspecified
NaN + bi NaN + NaNi, for all nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

ctanh()

Description

Compute hyperbolic tangent, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX ctanh(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute hyperbolic tangent of.

Return value

The hyperbolic tangent of x according to the following table:

Argument ctanh(Argument)
+0 + 0i +0 + 0i
a + ∞i NaN + NaNi, for finite a
a + NaNi NaN + NaNi, for finite a
+∞ + bi +1 + sin(2b)×0i for positive-signed finite b
+∞ + ∞i +1 + ±0i, sign of imaginary part unspecified
+∞ + NaNi +1 + ±0i, sign of imaginary part unspecified
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for all nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

ctanhf()

Description

Compute hyperbolic tangent, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX ctanhf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute hyperbolic tangent of.

Return value

The hyperbolic tangent of x according to the following table:

Argument ctanh(Argument)
+0 + 0i +0 + 0i
a + ∞i NaN + NaNi, for finite a
a + NaNi NaN + NaNi, for finite a
+∞ + bi +1 + sin(2b)×0i for positive-signed finite b
+∞ + ∞i +1 + ±0i, sign of imaginary part unspecified
+∞ + NaNi +1 + ±0i, sign of imaginary part unspecified
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for all nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

ctanhl()

Description

Compute hyperbolic tangent, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX ctanhl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute hyperbolic tangent of.

Return value

The hyperbolic tangent of x according to the following table:

Argument ctanh(Argument)
+0 + 0i +0 + 0i
a + ∞i NaN + NaNi, for finite a
a + NaNi NaN + NaNi, for finite a
+∞ + bi +1 + sin(2b)×0i for positive-signed finite b
+∞ + ∞i +1 + ±0i, sign of imaginary part unspecified
+∞ + NaNi +1 + ±0i, sign of imaginary part unspecified
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for all nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

casinh()

Description

Compute inverse hyperbolic sine, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX casinh(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic sineof.

Return value

The inverse hyperbolic sine of x according to the following table:

Argument casinh(Argument)
+0 + 0i +0 + 0i
+0 + ∞i +∞ + ½πi
a + NaNi NaN + NaNi
+∞ + bi +∞ + 0i, for positive-signed b
+∞ + ∞i +Pi + 0i
+∞ + NaNi +∞ + NaNi
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for finite nonzero b
NaN + ∞i ±∞ + NaNi, sign of real part unspecified
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

casinhf()

Description

Compute inverse hyperbolic sine, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX casinhf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic sineof.

Return value

The inverse hyperbolic sine of x according to the following table:

Argument casinh(Argument)
+0 + 0i +0 + 0i
+0 + ∞i +∞ + ½πi
a + NaNi NaN + NaNi
+∞ + bi +∞ + 0i, for positive-signed b
+∞ + ∞i +Pi + 0i
+∞ + NaNi +∞ + NaNi
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for finite nonzero b
NaN + ∞i ±∞ + NaNi, sign of real part unspecified
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

casinhl()

Description

Compute inverse hyperbolic sine, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX casinhl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic sineof.

Return value

The inverse hyperbolic sine of x according to the following table:

Argument casinh(Argument)
+0 + 0i +0 + 0i
+0 + ∞i +∞ + ½πi
a + NaNi NaN + NaNi
+∞ + bi +∞ + 0i, for positive-signed b
+∞ + ∞i +Pi + 0i
+∞ + NaNi +∞ + NaNi
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for finite nonzero b
NaN + ∞i ±∞ + NaNi, sign of real part unspecified
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

cacosh()

Description

Compute inverse hyperbolic cosine, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX cacosh(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic cosine of.

Return value

The inverse hyperbolic cosine of x according to the following table:

Argument cacosh(Argument)
±0 + 0i +0 + 0i
a + ∞i +∞ + ½πi, for finite a
a + NaNi NaN + NaNi, for finite a
-∞ + bi +∞ + πi, for positive-signed finite b
+∞ + bi +∞ + 0i, for positive-signed finite b
-∞ + ∞i ±∞ + ¾πi
+∞ + ∞i ±∞ + ¼πi
±∞ + NaNi +∞ + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + ∞i +∞ + NaNi
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

cacoshf()

Description

Compute inverse hyperbolic cosine, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX cacoshf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic cosine of.

Return value

The inverse hyperbolic cosine of x according to the following table:

Argument cacosh(Argument)
±0 + 0i +0 + 0i
a + ∞i +∞ + ½πi, for finite a
a + NaNi NaN + NaNi, for finite a
-∞ + bi +∞ + πi, for positive-signed finite b
+∞ + bi +∞ + 0i, for positive-signed finite b
-∞ + ∞i ±∞ + ¾πi
+∞ + ∞i ±∞ + ¼πi
±∞ + NaNi +∞ + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + ∞i +∞ + NaNi
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

cacoshl()

Description

Compute inverse hyperbolic cosine, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX cacoshl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic cosine of.

Return value

The inverse hyperbolic cosine of x according to the following table:

Argument cacosh(Argument)
±0 + 0i +0 + 0i
a + ∞i +∞ + ½πi, for finite a
a + NaNi NaN + NaNi, for finite a
-∞ + bi +∞ + πi, for positive-signed finite b
+∞ + bi +∞ + 0i, for positive-signed finite b
-∞ + ∞i ±∞ + ¾πi
+∞ + ∞i ±∞ + ¼πi
±∞ + NaNi +∞ + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + ∞i +∞ + NaNi
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

catanh()

Description

Compute inverse hyperbolic tangent, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX catanh(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic tangent of.

Return value

The inverse hyperbolic tangent of x according to the following table:

Argument catanh(Argument)
+0 + 0i +0 + 0i
+0 + NaNi +0 + NaNi
+1 + 0i +∞ + 0i
a + ∞i +0 + ½πi for positive-signed a
a + NaNi NaN + NaNi, for nonzero finite a
+∞ + bi +0 + ½πi for positive-signed b
+∞ + ∞i +0 + ½πi
+∞ + NaNi +0 + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

catanhf()

Description

Compute inverse hyperbolic tangent, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX catanhf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic tangent of.

Return value

The inverse hyperbolic tangent of x according to the following table:

Argument catanh(Argument)
+0 + 0i +0 + 0i
+0 + NaNi +0 + NaNi
+1 + 0i +∞ + 0i
a + ∞i +0 + ½πi for positive-signed a
a + NaNi NaN + NaNi, for nonzero finite a
+∞ + bi +0 + ½πi for positive-signed b
+∞ + ∞i +0 + ½πi
+∞ + NaNi +0 + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

catanhl()

Description

Compute inverse hyperbolic tangent, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX catanhl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic tangent of.

Return value

The inverse hyperbolic tangent of x according to the following table:

Argument catanh(Argument)
+0 + 0i +0 + 0i
+0 + NaNi +0 + NaNi
+1 + 0i +∞ + 0i
a + ∞i +0 + ½πi for positive-signed a
a + NaNi NaN + NaNi, for nonzero finite a
+∞ + bi +0 + ½πi for positive-signed b
+∞ + ∞i +0 + ½πi
+∞ + NaNi +0 + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

For arguments with a negative real component, use the equality:

Thread safety

Safe.

Power and absolute value

Function Description
cabs() Compute magnitude, double complex.
cabsf() Compute magnitude, float complex.
cabsl() Compute magnitude, long double complex.
cpow() Power, double complex.
cpowf() Power, float complex.
cpowl() Power, long double complex.
csqrt() Square root, double complex.
csqrtf() Square root, float complex.
csqrtl() Square root, long double complex.
cabs()

Description

Compute magnitude, double complex.

Prototype

double cabs(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute magnitude of.

Return value

The magnitude of x, |x|.

Thread safety

Safe.

cabsf()

Description

Compute magnitude, float complex.

Prototype

float cabsf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute magnitude of.

Return value

The magnitude of x, |x|.

Thread safety

Safe.

cabsl()

Description

Compute magnitude, long double complex.

Prototype

long double cabsl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute magnitude of.

Return value

The magnitude of x, |x|.

Thread safety

Safe.

cpow()

Description

Power, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX cpow(__SEGGER_RTL_FLOAT64_C_COMPLEX x,
                                    __SEGGER_RTL_FLOAT64_C_COMPLEX y);

Parameters

Parameter Description
x Base.
y Power.

Return value

Return x raised to the power of y.

Thread safety

Safe.

cpowf()

Description

Power, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX cpowf(__SEGGER_RTL_FLOAT32_C_COMPLEX x,
                                     __SEGGER_RTL_FLOAT32_C_COMPLEX y);

Parameters

Parameter Description
x Base.
y Power.

Return value

Return x raised to the power of y.

Thread safety

Safe.

cpowl()

Description

Power, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX cpowl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x,
                                     __SEGGER_RTL_LDOUBLE_C_COMPLEX y);

Parameters

Parameter Description
x Base.
y Power.

Return value

Return x raised to the power of y.

Thread safety

Safe.

csqrt()

Description

Square root, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX csqrt(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute squate root of.

Return value

The square root of x according to the following table:

Argument csqrt(Argument)
±0 + 0i +0 + 0i
a + ∞i +∞ + ∞i, for all a
a + NaNi +NaN + NaNi, for finite a
-∞ + bi +0 + ∞i for finite positive-signed b
+∞ + bi +∞ + 0i, for finite positive-signed b
+∞ + ∞i +∞ + ¼πi
-∞ + NaNi +NaN + +/∞i, sign of imaginary part unspecified
+∞ + NaNi +∞ + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + ∞i +∞ + ∞i
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

csqrtf()

Description

Square root, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX csqrtf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute squate root of.

Return value

The square root of x according to the following table:

Argument csqrt(Argument)
±0 + 0i +0 + 0i
a + ∞i +∞ + ∞i, for all a
a + NaNi +NaN + NaNi, for finite a
-∞ + bi +0 + ∞i for finite positive-signed b
+∞ + bi +∞ + 0i, for finite positive-signed b
+∞ + ∞i +∞ + ¼πi
-∞ + NaNi +NaN + +/∞i, sign of imaginary part unspecified
+∞ + NaNi +∞ + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + ∞i +∞ + ∞i
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

csqrtl()

Description

Square root, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX csqrtl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute squate root of.

Return value

The square root of x according to the following table:

Argument csqrt(Argument)
±0 + 0i +0 + 0i
a + ∞i +∞ + ∞i, for all a
a + NaNi +NaN + NaNi, for finite a
-∞ + bi +0 + ∞i for finite positive-signed b
+∞ + bi +∞ + 0i, for finite positive-signed b
+∞ + ∞i +∞ + ¼πi
-∞ + NaNi +NaN + +/∞i, sign of imaginary part unspecified
+∞ + NaNi +∞ + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + ∞i +∞ + ∞i
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

Exponential and logarithm functions

Function Description
clog() Compute natural logarithm, double complex.
clogf() Compute natural logarithm, float complex.
clogl() Compute natural logarithm, long double complex.
cexp() Compute base-e exponential, double complex.
cexpf() Compute base-e exponential, float complex.
cexpl() Compute base-e exponential, long double complex.
clog()

Description

Compute natural logarithm, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX clog(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

The natural logarithm of x according to the following table:

Argument clog(Argument)
-0 + 0i -∞ + πi
+0 + 0i -∞ + 0i
a + ∞i +∞ + ½πi, for finite a
a + NaNi NaN + NaNi, for finite a
-∞ + bi +∞ + πi, for finite positive b
+∞ + bi +∞ + 0i, for finite positive b
-∞ + ∞i +∞ + ¾πi
+∞ + ∞i +∞ + ¼πi
±∞ + NaNi +∞ + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + ∞i +∞ + NaNi
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

clogf()

Description

Compute natural logarithm, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX clogf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

The natural logarithm of x according to the following table:

Argument clog(Argument)
-0 + 0i -∞ + πi
+0 + 0i -∞ + 0i
a + ∞i +∞ + ½πi, for finite a
a + NaNi NaN + NaNi, for finite a
-∞ + bi +∞ + πi, for finite positive b
+∞ + bi +∞ + 0i, for finite positive b
-∞ + ∞i +∞ + ¾πi
+∞ + ∞i +∞ + ¼πi
±∞ + NaNi +∞ + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + ∞i +∞ + NaNi
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

clogl()

Description

Compute natural logarithm, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX clogl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

The natural logarithm of x according to the following table:

Argument clog(Argument)
-0 + 0i -∞ + πi
+0 + 0i -∞ + 0i
a + ∞i +∞ + ½πi, for finite a
a + NaNi NaN + NaNi, for finite a
-∞ + bi +∞ + πi, for finite positive b
+∞ + bi +∞ + 0i, for finite positive b
-∞ + ∞i +∞ + ¾πi
+∞ + ∞i +∞ + ¼πi
±∞ + NaNi +∞ + NaNi
NaN + bi NaN + NaNi, for finite b
NaN + ∞i +∞ + NaNi
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality:

Thread safety

Safe.

cexp()

Description

Compute base-e exponential, double complex.

Prototype

__SEGGER_RTL_FLOAT64_C_COMPLEX cexp(__SEGGER_RTL_FLOAT64_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute exponential of.

Return value

The base-e exponential of x=a+bi according to the following table:

Argument cexp(Argument)
-/-0 + 0i +1 + 0i
a + ∞i NaN + NaNi, for finite a
a + NaNi NaN + NaNi, for finite a
+∞ + 0i +∞ + 0i, for finite positive b
-∞ + bi +0 cis(b) for finite b
+∞ + bi +∞ cis(b) for finite nonzero b
-∞ + ∞i ±∞ + ±0i, signs unspecified
+∞ + ∞i ±∞ + i.NaN, sign of real part unspecified
-∞ + NaNi ±0 + ±0i, signs unspecified
+∞ + NaNi ±∞ + NaNi, sign of real part unspecified
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality

Thread safety

Safe.

cexpf()

Description

Compute base-e exponential, float complex.

Prototype

__SEGGER_RTL_FLOAT32_C_COMPLEX cexpf(__SEGGER_RTL_FLOAT32_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute exponential of.

Return value

The base-e exponential of x=a+bi according to the following table:

Argument cexp(Argument)
-/-0 + 0i +1 + 0i
a + ∞i NaN + NaNi, for finite a
a + NaNi NaN + NaNi, for finite a
+∞ + 0i +∞ + 0i, for finite positive b
-∞ + bi +0 cis(b) for finite b
+∞ + bi +∞ cis(b) for finite nonzero b
-∞ + ∞i ±∞ + ±0i, signs unspecified
+∞ + ∞i ±∞ + i.NaN, sign of real part unspecified
-∞ + NaNi ±0 + ±0i, signs unspecified
+∞ + NaNi ±∞ + NaNi, sign of real part unspecified
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality

Thread safety

Safe.

cexpl()

Description

Compute base-e exponential, long double complex.

Prototype

__SEGGER_RTL_LDOUBLE_C_COMPLEX cexpl(__SEGGER_RTL_LDOUBLE_C_COMPLEX x);

Parameters

Parameter Description
x Value to compute exponential of.

Return value

The base-e exponential of x=a+bi according to the following table:

Argument cexp(Argument)
-/-0 + 0i +1 + 0i
a + ∞i NaN + NaNi, for finite a
a + NaNi NaN + NaNi, for finite a
+∞ + 0i +∞ + 0i, for finite positive b
-∞ + bi +0 cis(b) for finite b
+∞ + bi +∞ cis(b) for finite nonzero b
-∞ + ∞i ±∞ + ±0i, signs unspecified
+∞ + ∞i ±∞ + i.NaN, sign of real part unspecified
-∞ + NaNi ±0 + ±0i, signs unspecified
+∞ + NaNi ±∞ + NaNi, sign of real part unspecified
NaN + 0i NaN + 0i
NaN + bi NaN + NaNi, for nonzero b
NaN + NaNi NaN + NaNi

For arguments with a negative imaginary component, use the equality

Thread safety

Safe.

<ctype.h>

Classification functions

Function Description
isascii() Is character a 7-bit ASCII code?
isascii_l() Is character a 7-bit ASCII code, per locale (POSIX.
iscntrl() Is character a control?
iscntrl_l() Is character a control, per locale? (POSIX.1).
isblank() Is character a blank?
isblank_l() Is character a blank, per locale? (POSIX.1).
isspace() Is character a whitespace character?
isspace_l() Is character a whitespace character, per locale? (POSIX.1).
ispunct() Is character a punctuation mark?
ispunct_l() Is character a punctuation mark, per locale? (POSIX.1).
isdigit() Is character a decimal digit?
isdigit_l() Is character a decimal digit, per locale? (POSIX.
isxdigit() Is character a hexadecimal digit?
isxdigit_l() Is character a hexadecimal digit, per locale? (POSIX.1).
isalpha() Is character alphabetic?
isalpha_l() Is character alphabetic, per locale? (POSIX.1).
isalnum() Is character alphanumeric?
isalnum_l() Is character alphanumeric, per locale? (POSIX.1).
isupper() Is character an uppercase letter?
isupper_l() Is character an uppercase letter, per locale? (POSIX.1).
islower() Is character a lowercase letter?
islower_l() Is character a lowercase letter, per locale? (POSIX.1).
isprint() Is character printable?
isprint_l() Is character printable, per locale? (POSIX.1).
isgraph() Is character any printing character?
isgraph_l() Is character any printing character, per locale? (POSIX.1).
isascii()

Description

Is character a 7-bit ASCII code?

Prototype

int isascii(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) if and only if the value of the argument has an ASCII code between 0 and 127 in the current locale.

Thread safety

Safe.

isascii_l()

Description

Is character a 7-bit ASCII code, per locale (POSIX.1)?

Prototype

int isascii_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) if and only if the value of the argument has an ASCII code between 0 and 127 in the locale loc.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

iscntrl()

Description

Is character a control?

Prototype

int iscntrl(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) if and only if the value of the argument c is a control character in the current locale.

Thread safety

Safe [if configured].

iscntrl_l()

Description

Is character a control, per locale? (POSIX.1).

Prototype

int iscntrl_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) if and only if the value of the argument c is a control character in the locale loc.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

isblank()

Description

Is character a blank?

Prototype

int isblank(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) if and only if the value of the argument c is either a space character or tab character in the current locale.

Thread safety

Safe [if configured].

isblank_l()

Description

Is character a blank, per locale? (POSIX.1).

Prototype

int isblank_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) if and only if the value of the argument c is either a space character or the tab character in locale loc.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

isspace()

Description

Is character a whitespace character?

Prototype

int isspace(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) if and only if the value of the argument c is a standard white-space character in the current locale. The standard white-space characters are space, form feed, new-line, carriage return, horizontal tab, and vertical tab.

Thread safety

Safe [if configured].

isspace_l()

Description

Is character a whitespace character, per locale? (POSIX.1).

Prototype

int isspace_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) if and only if the value of the argument c is a standard white-space character in the locale loc.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

ispunct()

Description

Is character a punctuation mark?

Prototype

int ispunct(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) for every printing character for which neither isspace() nor isalnum() is true in the current locale.

Thread safety

Safe [if configured].

ispunct_l()

Description

Is character a punctuation mark, per locale? (POSIX.1).

Prototype

int ispunct_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) for every printing character for which neither isspace() nor isalnum() is true in the locale loc.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

isdigit()

Description

Is character a decimal digit?

Prototype

int isdigit(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) if and only if the value of the argument c is a digit in the current locale.

Thread safety

Safe [if configured].

isdigit_l()

Description

Is character a decimal digit, per locale? (POSIX.1)

Prototype

int isdigit_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) if and only if the value of the argument c is a digit in the locale loc.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

isxdigit()

Description

Is character a hexadecimal digit?

Prototype

int isxdigit(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) if and only if the value of the argument c is a hexadecimal digit in the current locale.

Thread safety

Safe [if configured].

isxdigit_l()

Description

Is character a hexadecimal digit, per locale? (POSIX.1).

Prototype

int isxdigit_l(int c,
                   locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) if and only if the value of the argument c is a hexadecimal digit in the current locale.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

isalpha()

Description

Is character alphabetic?

Prototype

int isalpha(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns true if the character c is alphabetic in the current locale. That is, any character for which isupper() or islower() returns true is considered alphabetic in addition to any of the locale-specific set of alphabetic characters for which none of iscntrl(), isdigit(), ispunct(), or isspace() is true.

In the C locale, isalpha() returns nonzero (true) if and only if isupper() or islower() return true for value of the argument c.

Thread safety

Safe [if configured].

isalpha_l()

Description

Is character alphabetic, per locale? (POSIX.1).

Prototype

int isalpha_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns true if the character c is alphabetic in the locale loc. That is, any character for which isupper() or islower() returns true is considered alphabetic in addition to any of the locale-specific set of alphabetic characters for which none of iscntrl_l(), isdigit_l(), ispunct_l(), or isspace_l() is true in the locale loc.

In the C locale, isalpha_l() returns nonzero (true) if and only if isupper_l() or islower_l() return true for value of the argument c.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

isalnum()

Description

Is character alphanumeric?

Prototype

int isalnum(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) if and only if the value of the argument c is an alphabetic or numeric character in the current locale.

Thread safety

Safe [if configured].

isalnum_l()

Description

Is character alphanumeric, per locale? (POSIX.1).

Prototype

int isalnum_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) if and only if the value of the argument c is an alphabetic or numeric character in the locale loc.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

isupper()

Description

Is character an uppercase letter?

Prototype

int isupper(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) if and only if the value of the argument c is an uppercase letter in the current locale.

Thread safety

Safe [if configured].

isupper_l()

Description

Is character an uppercase letter, per locale? (POSIX.1).

Prototype

int isupper_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) if and only if the value of the argument c is an uppercase letter in the locale loc.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

islower()

Description

Is character a lowercase letter?

Prototype

int islower(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) if and only if the value of the argument c is a lowercase letter in the current locale.

Thread safety

Safe [if configured].

islower_l()

Description

Is character a lowercase letter, per locale? (POSIX.1).

Prototype

int islower_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) if and only if the value of the argument c is a lowercase letter in the locale loc.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

isprint()

Description

Is character printable?

Prototype

int isprint(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) if and only if the value of the argument c is any printing character including space in the current locale.

Thread safety

Safe [if configured].

isprint_l()

Description

Is character printable, per locale? (POSIX.1).

Prototype

int isprint_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) if and only if the value of the argument c is any printing character including space in the locale loc.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

isgraph()

Description

Is character any printing character?

Prototype

int isgraph(int c);

Parameters

Parameter Description
c Character to test.

Return value

Returns nonzero (true) if and only if the value of the argument c is any printing character except space in the current locale.

Thread safety

Safe [if configured].

isgraph_l()

Description

Is character any printing character, per locale? (POSIX.1).

Prototype

int isgraph_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to test.
loc Locale used to test c.

Return value

Returns nonzero (true) if and only if the value of the argument c is any printing character except space in the locale loc.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

Conversion functions

Function Description
toupper() Convert lowercase character to uppercase.
toupper_l() Convert lowercase character to uppercase, per locale (POSIX.1).
tolower() Convert uppercase character to lowercase.
tolower_l() Convert uppercase character to lowercase, per locale (POSIX.1).
toupper()

Description

Convert lowercase character to uppercase.

Prototype

int toupper(int c);

Parameters

Parameter Description
c Character to convert.

Return value

Converted character.

Additional information

Converts a lowercase letter to a corresponding uppercase letter.

If the argument c is a character for which islower() is true and there are one or more corresponding characters, as specified by the current locale, for which isupper() is true, toupper() returns one of the corresponding characters (always the same one for any given locale); otherwise, the argument is returned unchanged.

Notes

Even though islower() can return true for some characters, toupper() may return that lowercase character unchanged as there are no corresponding uppercase characters in the locale.

Thread safety

Safe [if configured].

toupper_l()

Description

Convert lowercase character to uppercase, per locale (POSIX.1).

Prototype

int toupper_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to convert.
loc Locale used to convert c.

Return value

Converted character.

Additional information

Converts a lowercase letter to a corresponding uppercase letter in locale loc. If the argument c is a character for which islower_l() is true in locale loc, tolower_l() returns the corresponding uppercase letter; otherwise, the argument is returned unchanged.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

tolower()

Description

Convert uppercase character to lowercase.

Prototype

int tolower(int c);

Parameters

Parameter Description
c Character to convert.

Return value

Converted character.

Additional information

Converts an uppercase letter to a corresponding lowercase letter.

If the argument c is a character for which isupper() is true and there are one or more corresponding characters, as specified by the current locale, for which islower() is true, the tolower() function returns one of the corresponding characters (always the same one for any given locale); otherwise, the argument is returned unchanged.

Notes

Even though isupper() can return true for some characters, tolower() may return that uppercase character unchanged as there are no corresponding lowercase characters in the locale.

Thread safety

Safe [if configured].

tolower_l()

Description

Convert uppercase character to lowercase, per locale (POSIX.1).

Prototype

int tolower_l(int c,
                  locale_t loc);

Parameters

Parameter Description
c Character to convert.
loc Locale used to convert c.

Return value

Converted character.

Additional information

Converts an uppercase letter to a corresponding lowercase letter in locale loc. If the argument is a character for which isupper_l() is true in locale loc, tolower_l() returns the corresponding lowercase letter; otherwise, the argument is returned unchanged.

Notes

Conforms to POSIX.1-2017.

Thread safety

Safe.

<errno.h>

Errors

Error names

Description

Symbolic error names for raised errors.

Definition

#define EDOM      0x01
#define EILSEQ    0x02
#define ERANGE    0x03
#define EHEAP     0x04
#define ENOMEM    0x05
#define EINVAL    0x06
#define ESPIPE    0x07

Symbols

Definition Description
EDOM Domain error
EILSEQ Illegal multibyte sequence in conversion
ERANGE Range error
EHEAP Heap is corrupt
ENOMEM Out of memory
EINVAL Invalid parameter
ESPIPE Invalid seek (POSIX.1)
errno

Description

Macro returning the current error.

Definition

#define errno    (*__SEGGER_RTL_X_errno_addr())

Additional information

The value in errno is significant only when the return value of the call indicated an error. A function that succeeds is allowed to change errno. The value of errno is never set to zero by a library function.

<fenv.h>

Floating-point exceptions

Function Description
feclearexcept() Clear floating-point exceptions.
feraiseexcept() Raise floating-point exceptions.
fegetexceptflag() Get floating-point exceptions.
fesetexceptflag() Set floating-point exceptions.
fetestexcept() Test floating-point exceptions.
feclearexcept()

Description

Clear floating-point exceptions.

Prototype

int feclearexcept(int excepts);

Parameters

Parameter Description
excepts Bitmask of floating-point exceptions to clear.

Return value

= 0 Floating-point exceptions successfully cleared.
≠ 0 Floating-point exceptions not cleared or not supported.

Additional information

This function attempts to clear the floating-point exceptions indicated by excepts.

Notes

This function has no return value in ISO C (1999) and an integer return value in ISO C (2008).

Thread safety

Safe [if configured].

feraiseexcept()

Description

Raise floating-point exceptions.

Prototype

int feraiseexcept(int excepts);

Parameters

Parameter Description
excepts Bitmask of floating-point exceptions to raise.

Return value

= 0 All floating-point exceptions successfully raised.
≠ 0 Floating-point exceptions not successuly raised or not supported.

Additional information

This function attempts to raise the floating-point exceptions indicated by excepts.

Notes

This function has no return value in ISO C (1999) and an integer return value in ISO C (2008).

Thread safety

Safe [if configured].

fegetexceptflag()

Description

Get floating-point exceptions.

Prototype

int fegetexceptflag(fexcept_t * flagp,
                    int         excepts);

Parameters

Parameter Description
flagp Pointer to object that receives the floating-point exception state.
excepts Bitmask of floating-point exceptions to store.

Return value

= 0 Floating-point exceptions correctly stored.
≠ 0 Floating-point exceptions not correctly stored.

Additional information

This function attempts to save the floating-point exceptions indicated by excepts to the object pointed to by flagp.

Thread safety

Safe [if configured].

See also

fesetexceptflag().

fesetexceptflag()

Description

Set floating-point exceptions.

Prototype

int fesetexceptflag(const fexcept_t * flagp,
                          int         excepts);

Parameters

Parameter Description
flagp Pointer to object containing a previously-stored floating-point exception state.
excepts Bitmask of floating-point exceptions to restore.

Return value

= 0 Floating-point exceptions correctly restored.
≠ 0 Floating-point exceptions not correctly restored.

Additional information

This function attempts to restore the floating-point exceptions indicated by excepts from the object pointed to by flagp. The exceptions to restore as indicated by excepts must have at least been specified when storing the exceptions using fegetexceptflag().

Thread safety

Safe [if configured].

See also

fegetexceptflag().

fetestexcept()

Description

Test floating-point exceptions.

Prototype

int fetestexcept(int excepts);

Parameters

Parameter Description
excepts Bitmask of floating-point exceptions to test.

Return value

The bitmask of all floating-point exceptions that are currently set and are specified in excepts.

Additional information

This function determines which of the floating-point exceptions indicated by excepts are currently set.

Thread safety

Safe [if configured].

Floating-point rounding mode

Function Description
fegetround() Get floating-point rounding mode.
fesetround() Set floating-point rounding mode.
fegetround()

Description

Get floating-point rounding mode.

Prototype

int fegetround(void);

Return value

≥ 0 Current floating-point rounding mode.
< 0 Floating-point rounding mode cannot be determined.

Additional information

This function attempts to read the current floating-point rounding mode.

Thread safety

Safe [if configured].

See also

fesetround().

fesetround()

Description

Set floating-point rounding mode.

Prototype

int fesetround(int round);

Parameters

Parameter Description
round Rounding mode to set.

Return value

= 0 Current floating-point rounding mode is set to round.
≠ 0 Requested floating-point rounding mode cannot be set.

Additional information

This function attempts to set the current floating-point rounding mode to round.

Thread safety

Safe [if configured].

See also

fegetround().

Floating-point environment

Function Description
fegetenv() Get floating-point environment.
fesetenv() Set floating-point environment.
feupdateenv() Restore floating-point environment and reraise exceptions.
feholdexcept() Save floating-point environment and set non-stop mode.
fegetenv()

Description

Get floating-point environment.

Prototype

int fegetenv(fenv_t * envp);

Parameters

Parameter Description
envp Pointer to object that receives the floating-point environment.

Return value

= 0 Current floating-point environment successfully stored.
≠ 0 Floating-point environment cannot be stored.

Additional information

This function attempts to store the current floating-point environment to the object pointed to by envp.

Notes

This function has no return value in ISO C (1999) and an integer return value in ISO C (2008).

Thread safety

Safe [if configured].

See also

fesetenv().

fesetenv()

Description

Set floating-point environment.

Prototype

int fesetenv(const fenv_t * envp);

Parameters

Parameter Description
envp Pointer to object containing previously-stored floating-point environment.

Return value

= 0 Current floating-point environment successfully restored.
≠ 0 Floating-point environment cannot be restored.

Additional information

This function attempts to restore the floating-point environment from the object pointed to by envp.

Notes

This function has no return value in ISO C (1999) and an integer return value in ISO C (2008).

Thread safety

Safe [if configured].

See also

fegetenv().

feupdateenv()

Description

Restore floating-point environment and reraise exceptions.

Prototype

int feupdateenv(const fenv_t * envp);

Parameters

Parameter Description
envp Pointer to object containing previously-stored floating-point environment.

Return value

= 0 Environment restored and exceptions raised successfully.
≠ 0 Failed to restore environment and raise exceptions.

Additional information

This function attempts to save the currently raised floating-point exceptions, restore the floating-point environment from the object pointed to by envp, and raise the saved exceptions.

Notes

This function has no return value in ISO C (1999) and an integer return value in ISO C (2008).

Thread safety

Safe [if configured].

feholdexcept()

Description

Save floating-point environment and set non-stop mode.

Prototype

int feholdexcept(fenv_t * envp);

Parameters

Parameter Description
envp Pointer to object that receives the floating-point environment.

Return value

= 0 Environment stored and non-stop mode set successfully.
≠ 0 Failed to store environment or set non-stop mode.

Additional information

This function function saves the current floating-point environment to the object pointed to by envp, clears the floating-point status flags, and then installs a non-stop mode for all floating-point exceptions

Thread safety

Safe [if configured].

<float.h>

Floating-point constants

Common parameters

Description

Applies to single-precision and double-precision formats.

Definition

#define FLT_ROUNDS         1
#define FLT_EVAL_METHOD    0
#define FLT_RADIX          2
#define DECIMAL_DIG        17

Symbols

Definition Description
FLT_ROUNDS Rounding mode of floating-point addition is round to nearest.
FLT_EVAL_METHOD All operations and constants are evaluated to the range and precision of the type.
FLT_RADIX Radix of the exponent representation.
DECIMAL_DIG Number of decimal digits that can be rounded to a floating-point number without change to the value.
Float parameters

Description

IEEE 32-bit single-precision floating format parameters.

Definition

#define FLT_MANT_DIG      24
#define FLT_EPSILON       1.19209290E-07f
#define FLT_DIG           6
#define FLT_MIN_EXP       -125
#define FLT_MIN           1.17549435E-38f
#define FLT_MIN_10_EXP    -37
#define FLT_MAX_EXP       +128
#define FLT_MAX           3.40282347E+38f
#define FLT_MAX_10_EXP    +38

Symbols

Definition Description
FLT_MANT_DIG Number of base FLT_RADIX digits in the mantissa part of a float.
FLT_EPSILON Minimum positive number such that 1.0f + FLT_EPSILON ≠ 1.0f.
FLT_DIG Number of decimal digits of precision of a float.
FLT_MIN_EXP Minimum value of base FLT_RADIX in the exponent part of a float.
FLT_MIN Minimum value of a float.
FLT_MIN_10_EXP Minimum value in base 10 of the exponent part of a float.
FLT_MAX_EXP Maximum value of base FLT_RADIX in the exponent part of a float.
FLT_MAX Maximum value of a float.
FLT_MAX_10_EXP Maximum value in base 10 of the exponent part of a float.
Double parameters

Description

IEEE 64-bit double-precision floating format parameters.

Definition

#define DBL_MANT_DIG      53
#define DBL_EPSILON       2.2204460492503131E-16
#define DBL_DIG           15
#define DBL_MIN_EXP       -1021
#define DBL_MIN           2.2250738585072014E-308
#define DBL_MIN_10_EXP    -307
#define DBL_MAX_EXP       +1024
#define DBL_MAX           1.7976931348623157E+308
#define DBL_MAX_10_EXP    +308

Symbols

Definition Description
DBL_MANT_DIG Number of base DBL_RADIX digits in the mantissa part of a double.
DBL_EPSILON Minimum positive number such that 1.0 + DBL_EPSILON ≠ 1.0.
DBL_DIG Number of decimal digits of precision of a double.
DBL_MIN_EXP Minimum value of base DBL_RADIX in the exponent part of a double.
DBL_MIN Minimum value of a double.
DBL_MIN_10_EXP Minimum value in base 10 of the exponent part of a double.
DBL_MAX_EXP Maximum value of base DBL_RADIX in the exponent part of a double.
DBL_MAX Maximum value of a double.
DBL_MAX_10_EXP Maximum value in base 10 of the exponent part of a double.

<iso646.h>

The header <iso646.h> defines macros that expand to the corresponding tokens to ease writing C programs with keyboards that do not have keys for frequently-used operators.

Macros

Replacement macros

Description

Standard replacement macros.

Definition

#define and       &&
#define and_eq    &=
#define bitand    &
#define bitor     |
#define compl     ~
#define not       !
#define not_eq    !=
#define or        ||
#define or_eq     |=
#define xor       ^
#define xor_eq    ^=

<limits.h>

Minima and maxima

Character minima and maxima

Description

Minimum and maximum values for character types.

Definition

#define CHAR_BIT     8
#define CHAR_MIN     0
#define CHAR_MAX     255
#define SCHAR_MAX    127
#define SCHAR_MIN    (-128)
#define UCHAR_MAX    255

Symbols

Definition Description
CHAR_BIT Number of bits for smallest object that is not a bit-field (byte).
CHAR_MIN Minimum value of a plain character.
CHAR_MAX Maximum value of a plain character.
SCHAR_MAX Maximum value of a signed character.
SCHAR_MIN Minimum value of a signed character.
UCHAR_MAX Maximum value of an unsigned character.
Short integer minima and maxima

Description

Minimum and maximum values for short integer types.

Definition

#define SHRT_MIN     (-32767 - 1)
#define SHRT_MAX     32767
#define USHRT_MAX    65535

Symbols

Definition Description
SHRT_MIN Minimum value of a short integer.
SHRT_MAX Maximum value of a short integer.
USHRT_MAX Maximum value of an unsigned short integer.
Integer minima and maxima

Description

Minimum and maximum values for integer types.

Definition

#define INT_MIN     (-2147483647 - 1)
#define INT_MAX     2147483647
#define UINT_MAX    4294967295u

Symbols

Definition Description
INT_MIN Minimum value of an integer.
INT_MAX Maximum value of an integer.
UINT_MAX Maximum value of an unsigned integer.
Long integer minima and maxima (32-bit)

Description

Minimum and maximum values for long integer types.

Definition

#define LONG_MIN     (-2147483647L - 1)
#define LONG_MAX     2147483647L
#define ULONG_MAX    4294967295uL

Symbols

Definition Description
LONG_MIN Maximum value of a long integer.
LONG_MAX Minimum value of a long integer.
ULONG_MAX Maximum value of an unsigned long integer.
Long integer minima and maxima (64-bit)

Description

Minimum and maximum values for long integer types.

Definition

#define LONG_MIN     (-9223372036854775807L - 1)
#define LONG_MAX     9223372036854775807L
#define ULONG_MAX    18446744073709551615uL

Symbols

Definition Description
LONG_MIN Minimum value of a long integer.
LONG_MAX Maximum value of a long integer.
ULONG_MAX Maximum value of an unsigned long integer.
Long long integer minima and maxima

Description

Minimum and maximum values for long integer types.

Definition

#define LLONG_MIN     (-9223372036854775807LL - 1)
#define LLONG_MAX     9223372036854775807LL
#define ULLONG_MAX    18446744073709551615uLL

Symbols

Definition Description
LLONG_MIN Minimum value of a long long integer.
LLONG_MAX Maximum value of a long long integer.
ULLONG_MAX Maximum value of an unsigned long long integer.
Multibyte characters

Description

Maximum number of bytes in a multi-byte character.

Definition

#define MB_LEN_MAX    4

Symbols

Definition Description
MB_LEN_MAX Maximum

Additional information

The maximum number of bytes in a multi-byte character for any supported locale. Unicode (ISO 10646) characters between 0x000000 and 0x10FFFF inclusive are supported which convert to a maximum of four bytes in the UTF-8 encoding.

<locale.h>

Data types

__SEGGER_RTL_lconv

Type definition

typedef struct {
  char * decimal_point;
  char * thousands_sep;
  char * grouping;
  char * int_curr_symbol;
  char * currency_symbol;
  char * mon_decimal_point;
  char * mon_thousands_sep;
  char * mon_grouping;
  char * positive_sign;
  char * negative_sign;
  char   int_frac_digits;
  char   frac_digits;
  char   p_cs_precedes;
  char   p_sep_by_space;
  char   n_cs_precedes;
  char   n_sep_by_space;
  char   p_sign_posn;
  char   n_sign_posn;
  char   int_p_cs_precedes;
  char   int_n_cs_precedes;
  char   int_p_sep_by_space;
  char   int_n_sep_by_space;
  char   int_p_sign_posn;
  char   int_n_sign_posn;
} __SEGGER_RTL_lconv;

Structure members

Member Description
decimal_point Decimal point separator.
thousands_sep Separators used to delimit groups of digits to the left of the decimal point for non-monetary quantities.
grouping Specifies the amount of digits that form each of the groups to be separated by thousands_sep separator for non-monetary quantities.
int_curr_symbol International currency symbol.
currency_symbol Local currency symbol.
mon_decimal_point Decimal-point separator used for monetary quantities.
mon_thousands_sep Separators used to delimit groups of digits to the left of the decimal point for monetary quantities.
mon_grouping Specifies the amount of digits that form each of the groups to be separated by mon_thousands_sep separator for monetary quantities.
positive_sign Sign to be used for nonnegative (positive or zero) monetary quantities.
negative_sign Sign to be used for negative monetary quantities.
int_frac_digits Amount of fractional digits to the right of the decimal point for monetary quantities in the international format.
frac_digits Amount of fractional digits to the right of the decimal point for monetary quantities in the local format.
p_cs_precedes Whether the currency symbol should precede nonnegative (positive or zero) monetary quantities.
p_sep_by_space Whether a space should appear between the currency symbol and nonnegative (positive or zero) monetary quantities.
n_cs_precedes Whether the currency symbol should precede negative monetary quantities.
n_sep_by_space Whether a space should appear between the currency symbol and negative monetary quantities.
p_sign_posn Position of the sign for nonnegative (positive or zero) monetary quantities.
n_sign_posn Position of the sign for negative monetary quantities.
int_p_cs_precedes Whether int_curr_symbol precedes or succeeds the value for a nonnegative internationally formatted monetary quantity.
int_n_cs_precedes Whether int_curr_symbol precedes or succeeds the value for a negative internationally formatted monetary quantity.
int_p_sep_by_space Value indicating the separation of the int_curr_symbol, the sign string, and the value for a nonnegative internationally formatted monetary quantity.
int_n_sep_by_space Value indicating the separation of the int_curr_symbol, the sign string, and the value for a negative internationally formatted monetary quantity.
int_p_sign_posn Value indicating the positioning of the positive_sign for a nonnegative internationally formatted monetary quantity.
int_n_sign_posn Value indicating the positioning of the positive_sign for a negative internationally formatted monetary quantity.

Locale management

Function Description
setlocale() Set locale.
localeconv() Get current locale data.
setlocale()

Description

Set locale.

Prototype

char *setlocale(      int    category,
                const char * loc);

Parameters

Parameter Description
category Category of locale to set, see below.
loc Pointer to name of locale to set or, if NULL, the current locale.

Return value

Returns the name of the current locale if a locale name buffer has been set using __SEGGER_RTL_set_locale_name_buffer(), else returns NULL.

Additional information

For ISO-correct operation, a local name buffer needs to be set using __SEGGER_RTL_set_locale_name_buffer() when the name of the current or global locale can be encoded. In many cases the previous locale’s name is not required, yet would take static storage on a global or per-thread basis. In order to avoid this, the standard operation of setlocale() in this library is to return NULL and not require any static data. If the previous locale’s name is required, at runtime startup or before calling setlocale(), use __SEGGER_RTL_set_locale_name_buffer() to set the address of the object to use where the locale name can be encoded. To make this thread-safe, the object where the locale name is stored must be local to the thread.

The category parameter can have the following values:

Value Description
LC_ALL Entire locale.
LC_COLLATE Affects strcoll() and strxfrm().
LC_CTYPE Affects character handling.
LC_MONETARY Affects monetary formatting information.
LC_NUMERIC Affects decimal-point character in I/O and string formatting operations.
LC_TIME Affects strftime().

Thread safety

Safe [if configured].

localeconv()

Description

Get current locale data.

Prototype

 localeconv(void);

Return value

Returns a pointer to a structure of type lconv with the corresponding values for the current locale filled in.

Thread safety

Safe [if configured].

<math.h>

Exponential and logarithm functions

Function Description
sqrt() Compute square root, double.
sqrtf() Compute square root, float.
sqrtl() Compute square root, long double.
cbrt() Compute cube root, double.
cbrtf() Compute cube root, float.
cbrtl() Compute cube root, long double.
rsqrt() Compute reciprocal square root, double.
rsqrtf() Compute reciprocal square root, float.
rsqrtl() Compute reciprocal square root, long double.
exp() Compute base-e exponential, double.
expf() Compute base-e exponential, float.
expl() Compute base-e exponential, long double.
expm1() Compute base-e exponential, modified, double.
expm1f() Compute base-e exponential, modified, float.
expm1l() Compute base-e exponential, modified, long double.
exp2() Compute base-2 exponential, double.
exp2f() Compute base-2 exponential, float.
exp2l() Compute base-2 exponential, long double.
exp10() Compute base-10 exponential, double.
exp10f() Compute base-10 exponential, float.
exp10l() Compute base-10 exponential, long double.
frexp() Split to significand and exponent, double.
frexpf() Split to significand and exponent, float.
frexpl() Split to significand and exponent, long double.
hypot() Compute magnitude of complex, double.
hypotf() Compute magnitude of complex, float.
hypotl() Compute magnitude of complex, long double.
log() Compute natural logarithm, double.
logf() Compute natural logarithm, float.
logl() Compute natural logarithm, long double.
log2() Compute base-2 logarithm, double.
log2f() Compute base-2 logarithm, float.
log2l() Compute base-2 logarithm, long double.
log10() Compute common logarithm, double.
log10f() Compute common logarithm, float.
log10l() Compute common logarithm, long double.
logb() Radix-indpendent exponent, double.
logbf() Radix-indpendent exponent, float.
logbl() Radix-indpendent exponent, long double.
ilogb() Radix-independent exponent, double.
ilogbf() Radix-independent exponent, float.
ilogbl() Radix-independent exponent, long double.
log1p() Compute natural logarithm plus one, double.
log1pf() Compute natural logarithm plus one, float.
log1pl() Compute natural logarithm plus one, long double.
ldexp() Scale by power of two, double.
ldexpf() Scale by power of two, float.
ldexpl() Scale by power of two, long double.
pow() Raise to power, double.
powf() Raise to power, float.
powl() Raise to power, long double.
scalbn() Scale, double.
scalbnf() Scale, float.
scalbnl() Scale, long double.
scalbln() Scale, double.
scalblnf() Scale, float.
scalblnl() Scale, long double.
sqrt()

Description

Compute square root, double.

Prototype

double sqrt(double x);

Parameters

Parameter Description
x Value to compute square root of.

Return value

Additional information

sqrt() computes the nonnegative square root of x. C90 and C99 require that a domain error occurs if the argument is less than zero, sqrt() deviates and always uses IEC 60559 semantics.

Thread safety

Safe.

sqrtf()

Description

Compute square root, float.

Prototype

float sqrtf(float x);

Parameters

Parameter Description
x Value to compute square root of.

Return value

Additional information

sqrt() computes the nonnegative square root of x. C90 and C99 require that a domain error occurs if the argument is less than zero, sqrt() deviates and always uses IEC 60559 semantics.

Thread safety

Safe.

sqrtl()

Description

Compute square root, long double.

Prototype

long double sqrtl(long double x);

Parameters

Parameter Description
x Value to compute square root of.

Return value

Additional information

sqrtl() computes the nonnegative square root of x. C90 and C99 require that a domain error occurs if the argument is less than zero, sqrtl() deviates and always uses IEC 60559 semantics.

Thread safety

Safe.

cbrt()

Description

Compute cube root, double.

Prototype

double cbrt(double x);

Parameters

Parameter Description
x Value to compute cube root of.

Return value

Thread safety

Safe.

cbrtf()

Description

Compute cube root, float.

Prototype

float cbrtf(float x);

Parameters

Parameter Description
x Value to compute cube root of.

Return value

Thread safety

Safe.

cbrtl()

Description

Compute cube root, long double.

Prototype

long double cbrtl(long double x);

Parameters

Parameter Description
x Value to compute cube root of.

Return value

Thread safety

Safe.

rsqrt()

Description

Compute reciprocal square root, double.

Prototype

double rsqrt(double x);

Parameters

Parameter Description
x Value to compute reciprocal square root of.

Return value

Thread safety

Safe.

rsqrtf()

Description

Compute reciprocal square root, float.

Prototype

float rsqrtf(float x);

Parameters

Parameter Description
x Value to compute reciprocal square root of.

Return value

Thread safety

Safe.

rsqrtl()

Description

Compute reciprocal square root, long double.

Prototype

long double rsqrtl(long double x);

Parameters

Parameter Description
x Value to compute reciprocal square root of.

Return value

Thread safety

Safe.

exp()

Description

Compute base-e exponential, double.

Prototype

double exp(double x);

Parameters

Parameter Description
x Value to compute base-e exponential of.

Return value

Thread safety

Safe.

expf()

Description

Compute base-e exponential, float.

Prototype

float expf(float x);

Parameters

Parameter Description
x Value to compute base-e exponential of.

Return value

Thread safety

Safe.

expl()

Description

Compute base-e exponential, long double.

Prototype

long double expl(long double x);

Parameters

Parameter Description
x Value to compute base-e exponential of.

Return value

Thread safety

Safe.

expm1()

Description

Compute base-e exponential, modified, double.

Prototype

double expm1(double x);

Parameters

Parameter Description
x Value to compute exponential of.

Return value

Thread safety

Safe.

expm1f()

Description

Compute base-e exponential, modified, float.

Prototype

float expm1f(float x);

Parameters

Parameter Description
x Value to compute exponential of.

Return value

Thread safety

Safe.

expm1l()

Description

Compute base-e exponential, modified, long double.

Prototype

long double expm1l(long double x);

Parameters

Parameter Description
x Value to compute exponential of.

Return value

Thread safety

Safe.

exp2()

Description

Compute base-2 exponential, double.

Prototype

double exp2(double x);

Parameters

Parameter Description
x Value to compute base-2 exponential of.

Return value

Thread safety

Safe.

exp2f()

Description

Compute base-2 exponential, float.

Prototype

float exp2f(float x);

Parameters

Parameter Description
x Value to compute base-e exponential of.

Return value

Thread safety

Safe.

exp2l()

Description

Compute base-2 exponential, long double.

Prototype

long double exp2l(long double x);

Parameters

Parameter Description
x Value to compute base-2 exponential of.

Return value

Thread safety

Safe.

exp10()

Description

Compute base-10 exponential, double.

Prototype

double exp10(double x);

Parameters

Parameter Description
x Value to compute base-e exponential of.

Return value

Thread safety

Safe.

exp10f()

Description

Compute base-10 exponential, float.

Prototype

float exp10f(float x);

Parameters

Parameter Description
x Value to compute base-e exponential of.

Return value

Thread safety

Safe.

exp10l()

Description

Compute base-10 exponential, long double.

Prototype

long double exp10l(long double x);

Parameters

Parameter Description
x Value to compute base-e exponential of.

Return value

Thread safety

Safe.

frexp()

Description

Split to significand and exponent, double.

Prototype

double frexp(double   x,
             int    * exp);

Parameters

Parameter Description
x Floating value to operate on.
exp Pointer to integer receiving the power-of-two exponent of x.

Return value

Additional information

Breaks a floating-point number into a normalized fraction and an integral power of two.

Thread safety

Safe.

frexpf()

Description

Split to significand and exponent, float.

Prototype

float frexpf(float   x,
             int   * exp);

Parameters

Parameter Description
x Floating value to operate on.
exp Pointer to integer receiving the power-of-two exponent of x.

Return value

Additional information

Breaks a floating-point number into a normalized fraction and an integral power of two.

Thread safety

Safe.

frexpl()

Description

Split to significand and exponent, long double.

Prototype

long double frexpl(long double   x,
                   int         * exp);

Parameters

Parameter Description
x Floating value to operate on.
exp Pointer to integer receiving the power-of-two exponent of x.

Return value

Additional information

Breaks a floating-point number into a normalized fraction and an integral power of two.

Thread safety

Safe.

hypot()

Description

Compute magnitude of complex, double.

Prototype

double hypot(double x,
             double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Additional information

Computes the square root of the sum of the squares of x and y without undue overflow or underflow. If x and y are the lengths of the sides of a right-angled triangle, then this computes the length of the hypotenuse.

Thread safety

Safe.

hypotf()

Description

Compute magnitude of complex, float.

Prototype

float hypotf(float x,
             float y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Additional information

Computes the square root of the sum of the squares of x and y without undue overflow or underflow. If x and y are the lengths of the sides of a right-angled triangle, then this computes the length of the hypotenuse.

Thread safety

Safe.

hypotl()

Description

Compute magnitude of complex, long double.

Prototype

long double hypotl(long double x,
                   long double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Additional information

Computes the square root of the sum of the squares of x and y without undue overflow or underflow. If x and y are the lengths of the sides of a right-angled triangle, then this computes the length of the hypotenuse.

Thread safety

Safe.

log()

Description

Compute natural logarithm, double.

Prototype

double log(double x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

logf()

Description

Compute natural logarithm, float.

Prototype

float logf(float x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

logl()

Description

Compute natural logarithm, long double.

Prototype

long double logl(long double x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

log2()

Description

Compute base-2 logarithm, double.

Prototype

double log2(double x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

log2f()

Description

Compute base-2 logarithm, float.

Prototype

float log2f(float x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

log2l()

Description

Compute base-2 logarithm, long double.

Prototype

long double log2l(long double x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

log10()

Description

Compute common logarithm, double.

Prototype

double log10(double x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

log10f()

Description

Compute common logarithm, float.

Prototype

float log10f(float x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

log10l()

Description

Compute common logarithm, long double.

Prototype

long double log10l(long double x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

logb()

Description

Radix-indpendent exponent, double.

Prototype

double logb(double x);

Parameters

Parameter Description
x Floating value to operate on.

Return value

Additional information

Calculates the exponent of x, which is the integral part of the FLTRADIX-logarithm of x.

Thread safety

Safe.

logbf()

Description

Radix-indpendent exponent, float.

Prototype

float logbf(float x);

Parameters

Parameter Description
x Floating value to operate on.

Return value

Additional information

Calculates the exponent of x, which is the integral part of the FLTRADIX-logarithm of x.

Thread safety

Safe.

logbl()

Description

Radix-indpendent exponent, long double.

Prototype

long double logbl(long double x);

Parameters

Parameter Description
x Floating value to operate on.

Return value

Additional information

Calculates the exponent of x, which is the integral part of the FLTRADIX-logarithm of x.

Thread safety

Safe.

ilogb()

Description

Radix-independent exponent, double.

Prototype

int ilogb(double x);

Parameters

Parameter Description
x Floating value to operate on.

Return value

Thread safety

Safe.

ilogbf()

Description

Radix-independent exponent, float.

Prototype

int ilogbf(float x);

Parameters

Parameter Description
x Floating value to operate on.

Return value

Thread safety

Safe.

ilogbl()

Description

Radix-independent exponent, long double.

Prototype

int ilogbl(long double x);

Parameters

Parameter Description
x Floating value to operate on.

Return value

Thread safety

Safe.

log1p()

Description

Compute natural logarithm plus one, double.

Prototype

double log1p(double x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

log1pf()

Description

Compute natural logarithm plus one, float.

Prototype

float log1pf(float x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

log1pl()

Description

Compute natural logarithm plus one, long double.

Prototype

long double log1pl(long double x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

Thread safety

Safe.

ldexp()

Description

Scale by power of two, double.

Prototype

double ldexp(double x,
             int    n);

Parameters

Parameter Description
x Value to scale.
n Power of two to scale by.

Return value

Additional information

Multiplies a floating-point number by an integral power of two.

Thread safety

Safe.

See also

scalbn()

ldexpf()

Description

Scale by power of two, float.

Prototype

float ldexpf(float x,
             int   n);

Parameters

Parameter Description
x Value to scale.
n Power of two to scale by.

Return value

Additional information

Multiplies a floating-point number by an integral power of two.

Thread safety

Safe.

See also

scalbnf()

ldexpl()

Description

Scale by power of two, long double.

Prototype

long double ldexpl(long double x,
                   int         n);

Parameters

Parameter Description
x Value to scale.
n Power of two to scale by.

Return value

Additional information

Multiplies a floating-point number by an integral power of two.

Thread safety

Safe.

See also

scalbnl()

pow()

Description

Raise to power, double.

Prototype

double pow(double x,
           double y);

Parameters

Parameter Description
x Base.
y Power.

Return value

Return x raised to the power y.

Thread safety

Safe.

powf()

Description

Raise to power, float.

Prototype

float powf(float x,
           float y);

Parameters

Parameter Description
x Base.
y Power.

Return value

Return x raised to the power y.

Thread safety

Safe.

powl()

Description

Raise to power, long double.

Prototype

long double powl(long double x,
                 long double y);

Parameters

Parameter Description
x Base.
y Power.

Return value

Return x raised to the power y.

Thread safety

Safe.

scalbn()

Description

Scale, double.

Prototype

double scalbn(double x,
              int    n);

Parameters

Parameter Description
x Value to scale.
n Power of DBL_RADIX to scale by.

Return value

Additional information

Multiplies a floating-point number by an integral power of DBL_RADIX.

As floating-point arithmetic conforms to IEC 60559, DBL_RADIX is 2 and scalbn() is (in this implementation) identical to ldexp().

Thread safety

Safe.

See also

ldexp()

scalbnf()

Description

Scale, float.

Prototype

float scalbnf(float x,
              int   n);

Parameters

Parameter Description
x Value to scale.
n Power of FLT_RADIX to scale by.

Return value

Additional information

Multiplies a floating-point number by an integral power of FLT_RADIX.

As floating-point arithmetic conforms to IEC 60559, FLT_RADIX is 2 and scalbnf() is (in this implementation) identical to ldexpf().

Thread safety

Safe.

See also

ldexpf()

scalbnl()

Description

Scale, long double.

Prototype

long double scalbnl(long double x,
                    int         n);

Parameters

Parameter Description
x Value to scale.
n Power of LDBL_RADIX to scale by.

Return value

Additional information

Multiplies a floating-point number by an integral power of LDBL_RADIX.

As floating-point arithmetic conforms to IEC 60559, LDBL_RADIX is 2 and scalbnl() is (in this implementation) identical to ldexpl().

Thread safety

Safe.

See also

ldexpl()

scalbln()

Description

Scale, double.

Prototype

double scalbln(double x,
               long   n);

Parameters

Parameter Description
x Value to scale.
n Power of DBL_RADIX to scale by.

Return value

Additional information

Multiplies a floating-point number by an integral power of DBL_RADIX.

As floating-point arithmetic conforms to IEC 60559, DBL_RADIX is 2 and scalbln() is (in this implementation) identical to ldexp().

Thread safety

Safe.

See also

ldexp()

scalblnf()

Description

Scale, float.

Prototype

float scalblnf(float x,
               long  n);

Parameters

Parameter Description
x Value to scale.
n Power of FLT_RADIX to scale by.

Return value

Additional information

Multiplies a floating-point number by an integral power of FLT_RADIX.

As floating-point arithmetic conforms to IEC 60559, FLT_RADIX is 2 and scalbnf() is (in this implementation) identical to ldexpf().

Thread safety

Safe.

scalblnl()

Description

Scale, long double.

Prototype

long double scalblnl(long double x,
                     long        n);

Parameters

Parameter Description
x Value to scale.
n Power of LDBL_RADIX to scale by.

Return value

Additional information

Multiplies a floating-point number by an integral power of LDBL_RADIX.

As floating-point arithmetic conforms to IEC 60559, LDBL_RADIX is 2 and scalblnl() is (in this implementation) identical to ldexpl().

Thread safety

Safe.

See also

ldexpl()

Trigonometric functions

Function Description
sin() Calculate sine, double.
sinf() Calculate sine, float.
sinl() Calculate sine, long double.
cos() Calculate cosine, double.
cosf() Calculate cosine, float.
cosl() Calculate cosine, long double.
tan() Compute tangent, double.
tanf() Compute tangent, float.
tanl() Compute tangent, long double.
sinh() Compute hyperbolic sine, double.
sinhf() Compute hyperbolic sine, float.
sinhl() Compute hyperbolic sine, long double.
cosh() Compute hyperbolic cosine, double.
coshf() Compute hyperbolic cosine, float.
coshl() Compute hyperbolic cosine, long double.
tanh() Compute hyperbolic tangent, double.
tanhf() Compute hyperbolic tangent, float.
tanhl() Compute hyperbolic tangent, long double.
sincos() Calculate sine and cosine, double.
sincosf() Calculate sine and cosine, float.
sincosl() Calculate sine and cosine, long double.
sin()

Description

Calculate sine, double.

Prototype

double sin(double x);

Parameters

Parameter Description
x Angle to compute sine of, radians.

Return value

Thread safety

Safe.

sinf()

Description

Calculate sine, float.

Prototype

float sinf(float x);

Parameters

Parameter Description
x Angle to compute sine of, radians.

Return value

Thread safety

Safe.

sinl()

Description

Calculate sine, long double.

Prototype

long double sinl(long double x);

Parameters

Parameter Description
x Angle to compute sine of, radians.

Return value

Thread safety

Safe.

cos()

Description

Calculate cosine, double.

Prototype

double cos(double x);

Parameters

Parameter Description
x Angle to compute cosine of, radians.

Return value

Thread safety

Safe.

cosf()

Description

Calculate cosine, float.

Prototype

float cosf(float x);

Parameters

Parameter Description
x Angle to compute cosine of, radians.

Return value

Thread safety

Safe.

cosl()

Description

Calculate cosine, long double.

Prototype

long double cosl(long double x);

Parameters

Parameter Description
x Angle to compute cosine of, radians.

Return value

Thread safety

Safe.

tan()

Description

Compute tangent, double.

Prototype

double tan(double x);

Parameters

Parameter Description
x Angle to compute tangent of, radians.

Return value

Thread safety

Safe.

tanf()

Description

Compute tangent, float.

Prototype

float tanf(float x);

Parameters

Parameter Description
x Angle to compute tangent of, radians.

Return value

Thread safety

Safe.

tanl()

Description

Compute tangent, long double.

Prototype

long double tanl(long double x);

Parameters

Parameter Description
x Angle to compute tangent of, radians.

Return value

Thread safety

Safe.

sinh()

Description

Compute hyperbolic sine, double.

Prototype

double sinh(double x);

Parameters

Parameter Description
x Value to compute hyperbolic sine of.

Return value

Thread safety

Safe.

sinhf()

Description

Compute hyperbolic sine, float.

Prototype

float sinhf(float x);

Parameters

Parameter Description
x Value to compute hyperbolic sine of.

Return value

Thread safety

Safe.

sinhl()

Description

Compute hyperbolic sine, long double.

Prototype

long double sinhl(long double x);

Parameters

Parameter Description
x Value to compute hyperbolic sine of.

Return value

Thread safety

Safe.

cosh()

Description

Compute hyperbolic cosine, double.

Prototype

double cosh(double x);

Parameters

Parameter Description
x Value to compute hyperbolic cosine of.

Return value

Thread safety

Safe.

coshf()

Description

Compute hyperbolic cosine, float.

Prototype

float coshf(float x);

Parameters

Parameter Description
x Value to compute hyperbolic cosine of.

Return value

Thread safety

Safe.

coshl()

Description

Compute hyperbolic cosine, long double.

Prototype

long double coshl(long double x);

Parameters

Parameter Description
x Value to compute hyperbolic cosine of.

Return value

Thread safety

Safe.

tanh()

Description

Compute hyperbolic tangent, double.

Prototype

double tanh(double x);

Parameters

Parameter Description
x Value to compute hyperbolic tangent of.

Return value

Thread safety

Safe.

tanhf()

Description

Compute hyperbolic tangent, float.

Prototype

float tanhf(float x);

Parameters

Parameter Description
x Value to compute hyperbolic tangent of.

Return value

Thread safety

Safe.

tanhl()

Description

Compute hyperbolic tangent, long double.

Prototype

long double tanhl(long double x);

Parameters

Parameter Description
x Value to compute hyperbolic tangent of.

Return value

Thread safety

Safe.

sincos()

Description

Calculate sine and cosine, double.

Prototype

void sincos(double   x,
            double * pSin,
            double * pCos);

Parameters

Parameter Description
x Angle to compute sine and cosine of, radians.
pSin Pointer to object that receives the sine of x.
pCos Pointer to object that receives the cosine of x.

Thread safety

Safe.

sincosf()

Description

Calculate sine and cosine, float.

Prototype

void sincosf(float   x,
             float * pSin,
             float * pCos);

Parameters

Parameter Description
x Angle to compute sine and cosine of, radians.
pSin Pointer to object that receives the sine of x.
pCos Pointer to object that receives the cosine of x.

Thread safety

Safe.

sincosl()

Description

Calculate sine and cosine, long double.

Prototype

void sincosl(long double   x,
             long double * pSin,
             long double * pCos);

Parameters

Parameter Description
x Angle to compute sine and cosine of, radians.
pSin Pointer to object that receives the sine of x.
pCos Pointer to object that receives the cosine of x.

Thread safety

Safe.

Inverse trigonometric functions

Function Description
asin() Compute inverse sine, double.
asinf() Compute inverse sine, float.
asinl() Compute inverse sine, long double.
acos() Compute inverse cosine, double.
acosf() Compute inverse cosine, float.
acosl() Compute inverse cosine, long double.
atan() Compute inverse tangent, double.
atanf() Compute inverse tangent, float.
atanl() Compute inverse tangent, long double.
atan2() Compute inverse tangent, with quadrant, double.
atan2f() Compute inverse tangent, with quadrant, float.
atan2l() Compute inverse tangent, with quadrant, long double.
asinh() Compute inverse hyperbolic sine, double.
asinhf() Compute inverse hyperbolic sine, float.
asinhl() Compute inverse hyperbolic sine, long double.
acosh() Compute inverse hyperbolic cosine, double.
acoshf() Compute inverse hyperbolic cosine, float.
acoshl() Compute inverse hyperbolic cosine, long double.
atanh() Compute inverse hyperbolic tangent, double.
atanhf() Compute inverse hyperbolic tangent, float.
atanhl() Compute inverse hyperbolic tangent, long double.
asin()

Description

Compute inverse sine, double.

Prototype

double asin(double x);

Parameters

Parameter Description
x Value to compute inverse sine of.

Return value

Additional information

Calculates the principal value, in radians, of the inverse circular sine of x. The principal value lies in the interval [-Pi/2, Pi/2] radians.

Thread safety

Safe.

asinf()

Description

Compute inverse sine, float.

Prototype

float asinf(float x);

Parameters

Parameter Description
x Value to compute inverse sine of.

Return value

Additional information

Calculates the principal value, in radians, of the inverse circular sine of x. The principal value lies in the interval [-Pi/2, Pi/2] radians.

Thread safety

Safe.

asinl()

Description

Compute inverse sine, long double.

Prototype

long double asinl(long double x);

Parameters

Parameter Description
x Value to compute inverse sine of.

Return value

Additional information

Calculates the principal value, in radians, of the inverse circular sine of x. The principal value lies in the interval [-Pi/2, Pi/2] radians.

Thread safety

Safe.

acos()

Description

Compute inverse cosine, double.

Prototype

double acos(double x);

Parameters

Parameter Description
x Value to compute inverse cosine of.

Return value

Additional information

Calculates the principal value, in radians, of the inverse circular cosine of x. The principal value lies in the interval [0, Pi] radians.

Thread safety

Safe.

acosf()

Description

Compute inverse cosine, float.

Prototype

float acosf(float x);

Parameters

Parameter Description
x Value to compute inverse cosine of.

Return value

Additional information

Calculates the principal value, in radians, of the inverse circular cosine of x. The principal value lies in the interval [0, Pi] radians.

Thread safety

Safe.

acosl()

Description

Compute inverse cosine, long double.

Prototype

long double acosl(long double x);

Parameters

Parameter Description
x Value to compute inverse cosine of.

Return value

Additional information

Calculates the principal value, in radians, of the inverse circular cosine of x. The principal value lies in the interval [0, Pi] radians.

Thread safety

Safe.

atan()

Description

Compute inverse tangent, double.

Prototype

double atan(double x);

Parameters

Parameter Description
x Value to compute inverse tangent of.

Return value

Additional information

Calculates the principal value, in radians, of the inverse tangent of x. The principal value lies in the interval [-Pi/2, Pi/2] radians.

Thread safety

Safe.

atanf()

Description

Compute inverse tangent, float.

Prototype

float atanf(float x);

Parameters

Parameter Description
x Value to compute inverse tangent of.

Return value

Additional information

Calculates the principal value, in radians, of the inverse tangent of x. The principal value lies in the interval [-Pi/2, Pi/2] radians.

Thread safety

Safe.

atanl()

Description

Compute inverse tangent, long double.

Prototype

long double atanl(long double x);

Parameters

Parameter Description
x Value to compute inverse tangent of.

Return value

Additional information

Calculates the principal value, in radians, of the inverse tangent of x. The principal value lies in the interval [-Pi/2, Pi/2] radians.

Thread safety

Safe.

atan2()

Description

Compute inverse tangent, with quadrant, double.

Prototype

double atan2(double y,
             double x);

Parameters

Parameter Description
y Rise value of angle.
x Run value of angle.

Return value

Inverse tangent of y/x.

Additional information

This calculates the value, in radians, of the inverse tangent of y divided by x using the signs of x and y to compute the quadrant of the return value. The principal value lies in the interval [-Pi, +Pi] radians.

Thread safety

Safe.

atan2f()

Description

Compute inverse tangent, with quadrant, float.

Prototype

float atan2f(float y,
             float x);

Parameters

Parameter Description
y Rise value of angle.
x Run value of angle.

Return value

Inverse tangent of y/x.

Additional information

This calculates the value, in radians, of the inverse tangent of y divided by x using the signs of x and y to compute the quadrant of the return value. The principal value lies in the interval [-Pi, +Pi] radians.

Thread safety

Safe.

atan2l()

Description

Compute inverse tangent, with quadrant, long double.

Prototype

long double atan2l(long double y,
                   long double x);

Parameters

Parameter Description
y Rise value of angle.
x Run value of angle.

Return value

Inverse tangent of y/x.

Additional information

This calculates the value, in radians, of the inverse tangent of y divided by x using the signs of x and y to compute the quadrant of the return value. The principal value lies in the interval [-Pi, +Pi] radians.

Thread safety

Safe.

asinh()

Description

Compute inverse hyperbolic sine, double.

Prototype

double asinh(double x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic sine of.

Return value

Thread safety

Safe.

asinhf()

Description

Compute inverse hyperbolic sine, float.

Prototype

float asinhf(float x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic sine of.

Return value

Additional information

Calculates the inverse hyperbolic sine of x.

Thread safety

Safe.

asinhl()

Description

Compute inverse hyperbolic sine, long double.

Prototype

long double asinhl(long double x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic sine of.

Return value

Thread safety

Safe.

acosh()

Description

Compute inverse hyperbolic cosine, double.

Prototype

double acosh(double x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic cosine of.

Return value

Thread safety

Safe.

acoshf()

Description

Compute inverse hyperbolic cosine, float.

Prototype

float acoshf(float x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic cosine of.

Return value

Thread safety

Safe.

acoshl()

Description

Compute inverse hyperbolic cosine, long double.

Prototype

long double acoshl(long double x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic cosine of.

Return value

Thread safety

Safe.

atanh()

Description

Compute inverse hyperbolic tangent, double.

Prototype

double atanh(double x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic tangent of.

Return value

Thread safety

Safe.

atanhf()

Description

Compute inverse hyperbolic tangent, float.

Prototype

float atanhf(float x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic tangent of.

Return value

Thread safety

Safe.

atanhl()

Description

Compute inverse hyperbolic tangent, long double.

Prototype

long double atanhl(long double x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic tangent of.

Return value

Thread safety

Safe.

Special functions

Function Description
erf() Error function, double.
erff() Error function, float.
erfl() Error function, long double.
erfc() Complementary error function, double.
erfcf() Complementary error function, float.
erfcl() Complementary error function, long double.
lgamma() Log-Gamma function, double.
lgammaf() Log-Gamma function, float.
lgammal() Log-Gamma function, long double.
tgamma() Gamma function, double.
tgammaf() Gamma function, float.
tgammal() Gamma function, long double.
erf()

Description

Error function, double.

Prototype

double erf(double x);

Parameters

Parameter Description
x Argument.

Return value

erf(x).

Thread safety

Safe.

erff()

Description

Error function, float.

Prototype

float erff(float x);

Parameters

Parameter Description
x Argument.

Return value

erf(x).

Thread safety

Safe.

erfl()

Description

Error function, long double.

Prototype

long double erfl(long double x);

Parameters

Parameter Description
x Argument.

Return value

erf(x).

Thread safety

Safe.

erfc()

Description

Complementary error function, double.

Prototype

double erfc(double x);

Parameters

Parameter Description
x Argument.

Return value

erfc(x).

Thread safety

Safe.

erfcf()

Description

Complementary error function, float.

Prototype

float erfcf(float x);

Parameters

Parameter Description
x Argument.

Return value

erfc(x).

Thread safety

Safe.

erfcl()

Description

Complementary error function, long double.

Prototype

long double erfcl(long double x);

Parameters

Parameter Description
x Argument.

Return value

erfc(x).

Thread safety

Safe.

lgamma()

Description

Log-Gamma function, double.

Prototype

double lgamma(double x);

Parameters

Parameter Description
x Argument.

Return value

log(gamma(x)).

Thread safety

Safe.

lgammaf()

Description

Log-Gamma function, float.

Prototype

float lgammaf(float x);

Parameters

Parameter Description
x Argument.

Return value

log(gamma(x)).

Thread safety

Safe.

lgammal()

Description

Log-Gamma function, long double.

Prototype

long double lgammal(long double x);

Parameters

Parameter Description
x Argument.

Return value

log(gamma(x)).

Thread safety

Safe.

tgamma()

Description

Gamma function, double.

Prototype

double tgamma(double x);

Parameters

Parameter Description
x Argument.

Return value

gamma(x).

Thread safety

Safe.

tgammaf()

Description

Gamma function, float.

Prototype

float tgammaf(float x);

Parameters

Parameter Description
x Argument.

Return value

gamma(x).

Thread safety

Safe.

tgammal()

Description

Gamma function, long double.

Prototype

long double tgammal(long double x);

Parameters

Parameter Description
x Argument.

Return value

gamma(x).

Thread safety

Safe.

Rounding and remainder functions

Function Description
ceil() Compute smallest integer not less than, double.
ceilf() Compute smallest integer not less than, float.
ceill() Compute smallest integer not less than, long double.
floor() Compute largest integer not greater than, double.
floorf() Compute largest integer not greater than, float.
floorl() Compute largest integer not greater than, long double.
trunc() Truncate to integer, double.
truncf() Truncate to integer, float.
truncl() Truncate to integer, long double.
rint() Round to nearest integer, double.
rintf() Round to nearest integer, float.
rintl() Round to nearest integer, long double.
lrint() Round to nearest integer, double.
lrintf() Round to nearest integer, float.
lrintl() Round to nearest integer, long double.
llrint() Round to nearest integer, double.
llrintf() Round to nearest integer, float.
llrintl() Round to nearest integer, long double.
round() Round to nearest integer, double.
roundf() Round to nearest integer, float.
roundl() Round to nearest integer, long double.
lround() Round to nearest integer, double.
lroundf() Round to nearest integer, float.
lroundl() Round to nearest integer, long double.
llround() Round to nearest integer, double.
llroundf() Round to nearest integer, float.
llroundl() Round to nearest integer, long double.
nearbyint() Round to nearest integer, double.
nearbyintf() Round to nearest integer, float.
nearbyintl() Round to nearest integer, long double.
fmod() Compute remainder after division, double.
fmodf() Compute remainder after division, float.
fmodl() Compute remainder after division, long double.
modf() Separate integer and fractional parts, double.
modff() Separate integer and fractional parts, float.
modfl() Separate integer and fractional parts, long double.
remainder() Compute remainder after division, double.
remainderf() Compute remainder after division, float.
remainderl() Compute remainder after division, long double.
remquo() Compute remainder after division, double.
remquof() Compute remainder after division, float.
remquol() Compute remainder after division, long double.
ceil()

Description

Compute smallest integer not less than, double.

Prototype

double ceil(double x);

Parameters

Parameter Description
x Value to compute ceiling of.

Return value

Thread safety

Safe.

ceilf()

Description

Compute smallest integer not less than, float.

Prototype

float ceilf(float x);

Parameters

Parameter Description
x Value to compute ceiling of.

Return value

Thread safety

Safe.

ceill()

Description

Compute smallest integer not less than, long double.

Prototype

long double ceill(long double x);

Parameters

Parameter Description
x Value to compute ceiling of.

Return value

Thread safety

Safe.

floor()

Description

Compute largest integer not greater than, double.

Prototype

double floor(double x);

Parameters

Parameter Description
x Value to floor.

Return value

Thread safety

Safe.

floorf()

Description

Compute largest integer not greater than, float.

Prototype

float floorf(float x);

Parameters

Parameter Description
x Value to floor.

Return value

Thread safety

Safe.

floorl()

Description

Compute largest integer not greater than, long double.

Prototype

long double floorl(long double x);

Parameters

Parameter Description
x Value to floor.

Return value

Thread safety

Safe.

trunc()

Description

Truncate to integer, double.

Prototype

double trunc(double x);

Parameters

Parameter Description
x Value to truncate.

Return value

Thread safety

Safe.

truncf()

Description

Truncate to integer, float.

Prototype

float truncf(float x);

Parameters

Parameter Description
x Value to truncate.

Return value

Thread safety

Safe.

truncl()

Description

Truncate to integer, long double.

Prototype

long double truncl(long double x);

Parameters

Parameter Description
x Value to truncate.

Return value

Thread safety

Safe.

rint()

Description

Round to nearest integer, double.

Prototype

double rint(double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

rintf()

Description

Round to nearest integer, float.

Prototype

float rintf(float x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

rintl()

Description

Round to nearest integer, long double.

Prototype

long double rintl(long double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

lrint()

Description

Round to nearest integer, double.

Prototype

long lrint(double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

lrintf()

Description

Round to nearest integer, float.

Prototype

long lrintf(float x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

lrintl()

Description

Round to nearest integer, long double.

Prototype

long lrintl(long double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

llrint()

Description

Round to nearest integer, double.

Prototype

long long llrint(double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

llrintf()

Description

Round to nearest integer, float.

Prototype

long long llrintf(float x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

llrintl()

Description

Round to nearest integer, long double.

Prototype

long long llrintl(long double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

round()

Description

Round to nearest integer, double.

Prototype

double round(double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

roundf()

Description

Round to nearest integer, float.

Prototype

float roundf(float x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

roundl()

Description

Round to nearest integer, long double.

Prototype

long double roundl(long double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

lround()

Description

Round to nearest integer, double.

Prototype

long lround(double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

lroundf()

Description

Round to nearest integer, float.

Prototype

long lroundf(float x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

lroundl()

Description

Round to nearest integer, long double.

Prototype

long lroundl(long double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

llround()

Description

Round to nearest integer, double.

Prototype

long long llround(double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

llroundf()

Description

Round to nearest integer, float.

Prototype

long long llroundf(float x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

llroundl()

Description

Round to nearest integer, long double.

Prototype

long long llroundl(long double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

nearbyint()

Description

Round to nearest integer, double.

Prototype

double nearbyint(double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

nearbyintf()

Description

Round to nearest integer, float.

Prototype

float nearbyintf(float x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

nearbyintl()

Description

Round to nearest integer, long double.

Prototype

long double nearbyintl(long double x);

Parameters

Parameter Description
x Value to compute nearest integer of.

Return value

Thread safety

Safe.

fmod()

Description

Compute remainder after division, double.

Prototype

double fmod(double x,
            double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Additional information

Computes the floating-point remainder of x divided by y, i.e. the value x - i*y for some integer i such that, if y is nonzero, the result has the same sign as x and magnitude less than the magnitude of y.

Thread safety

Safe.

fmodf()

Description

Compute remainder after division, float.

Prototype

float fmodf(float x,
            float y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Additional information

Computes the floating-point remainder of x divided by y, i.e. the value x - i*y for some integer i such that, if y is nonzero, the result has the same sign as x and magnitude less than the magnitude of y.

Thread safety

Safe.

fmodl()

Description

Compute remainder after division, long double.

Prototype

long double fmodl(long double x,
                  long double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Additional information

Computes the floating-point remainder of x divided by y, i.e. the value x - i*y for some integer i such that, if y is nonzero, the result has the same sign as x and magnitude less than the magnitude of y.

Thread safety

Safe.

modf()

Description

Separate integer and fractional parts, double.

Prototype

double modf(double   x,
            double * iptr);

Parameters

Parameter Description
x Value to separate.
iptr Pointer to object that receives the integral part of x.

Return value

The signed fractional part of x.

Additional information

Breaks x into integral and fractional parts, each of which has the same type and sign as x.

The integral part (in floating-point format) is stored in the object pointed to by iptr and modf() returns the signed fractional part of x.

Thread safety

Safe.

modff()

Description

Separate integer and fractional parts, float.

Prototype

float modff(float   x,
            float * iptr);

Parameters

Parameter Description
x Value to separate.
iptr Pointer to object that receives the integral part of x.

Return value

The signed fractional part of x.

Additional information

Breaks x into integral and fractional parts, each of which has the same type and sign as x.

The integral part (in floating-point format) is stored in the object pointed to by iptr and modff() returns the signed fractional part of x.

Thread safety

Safe.

modfl()

Description

Separate integer and fractional parts, long double.

Prototype

long double modfl(long double   x,
                  long double * iptr);

Parameters

Parameter Description
x Value to separate.
iptr Pointer to object that receives the integral part of x.

Return value

The signed fractional part of x.

Additional information

Breaks x into integral and fractional parts, each of which has the same type and sign as x.

The integral part (in floating-point format) is stored in the object pointed to by iptr and modf() returns the signed fractional part of x.

Thread safety

Safe.

remainder()

Description

Compute remainder after division, double.

Prototype

double remainder(double x,
                 double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Additional information

Computes the floating-point remainder of x divided by y, i.e. the value x - i*y for some integer i such that, if y is nonzero, the result has the same sign as x and magnitude less than the magnitude of y.

Thread safety

Safe.

remainderf()

Description

Compute remainder after division, float.

Prototype

float remainderf(float x,
                 float y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Additional information

Computes the floating-point remainder of x divided by y, i.e. the value x - i*y for some integer i such that, if y is nonzero, the result has the same sign as x and magnitude less than the magnitude of y.

Thread safety

Safe.

remainderl()

Description

Compute remainder after division, long double.

Prototype

long double remainderl(long double x,
                       long double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Additional information

Computes the floating-point remainder of x divided by y, i.e. the value x - i*y for some integer i such that, if y is nonzero, the result has the same sign as x and magnitude less than the magnitude of y.

Thread safety

Safe.

remquo()

Description

Compute remainder after division, double.

Prototype

double remquo(double   x,
              double   y,
              int    * quo);

Parameters

Parameter Description
x Value #1.
y Value #2.
quo Pointer to object that receives the integer part of x divided by y.

Return value

Additional information

Computes the floating-point remainder of x divided by y, i.e. the value x - i*y for some integer i such that, if y is nonzero, the result has the same sign as x and magnitude less than the magnitude of y.

Thread safety

Safe.

remquof()

Description

Compute remainder after division, float.

Prototype

float remquof(float   x,
              float   y,
              int   * quo);

Parameters

Parameter Description
x Value #1.
y Value #2.
quo Pointer to object that receives the integer part of x divided by y.

Return value

Additional information

Computes the floating-point remainder of x divided by y, i.e. the value x - i*y for some integer i such that, if y is nonzero, the result has the same sign as x and magnitude less than the magnitude of y.

Thread safety

Safe.

remquol()

Description

Compute remainder after division, long double.

Prototype

long double remquol(long double   x,
                    long double   y,
                    int         * quo);

Parameters

Parameter Description
x Value #1.
y Value #2.
quo Pointer to object that receives the integer part of x divided by y.

Return value

Additional information

Computes the floating-point remainder of x divided by y, i.e. the value x - i*y for some integer i such that, if y is nonzero, the result has the same sign as x and magnitude less than the magnitude of y.

Thread safety

Safe.

Absolute value functions

Function Description
fabs() Compute absolute value, double.
fabsf() Compute absolute value, float.
fabsl() Compute absolute value, long double.
fabs()

Description

Compute absolute value, double.

Prototype

double fabs(double x);

Parameters

Parameter Description
x Value to compute magnitude of.

Return value

Thread safety

Safe.

fabsf()

Description

Compute absolute value, float.

Prototype

float fabsf(float x);

Parameters

Parameter Description
x Value to compute magnitude of.

Return value

Thread safety

Safe.

fabsl()

Description

Compute absolute value, long double.

Prototype

long double fabsl(long double x);

Parameters

Parameter Description
x Value to compute magnitude of.

Return value

Thread safety

Safe.

Fused multiply functions

Function Description
fma() Compute fused multiply-add, double.
fmaf() Compute fused multiply-add, float.
fmal() Compute fused multiply-add, long double.
fma()

Description

Compute fused multiply-add, double.

Prototype

double fma(double x,
           double y,
           double z);

Parameters

Parameter Description
x Multiplicand.
y Multiplier.
z Summand.

Return value

Return (x * y) + z.

Thread safety

Safe.

fmaf()

Description

Compute fused multiply-add, float.

Prototype

float fmaf(float x,
           float y,
           float z);

Parameters

Parameter Description
x Multiplier.
y Multiplicand.
z Summand.

Return value

Return (x * y) + z.

Thread safety

Safe.

fmal()

Description

Compute fused multiply-add, long double.

Prototype

long double fmal(long double x,
                 long double y,
                 long double z);

Parameters

Parameter Description
x Multiplicand.
y Multiplier.
z Summand.

Return value

Return (x * y) + z.

Thread safety

Safe.

Maximum, minimum, and positive difference functions

Function Description
fmin() Compute minimum, double.
fminf() Compute minimum, float.
fminl() Compute minimum, long double.
fmax() Compute maximum, double.
fmaxf() Compute maximum, float.
fmaxl() Compute maximum, long double.
fdim() Positive difference, double.
fdimf() Positive difference, float.
fdiml() Positive difference, long double.
fmin()

Description

Compute minimum, double.

Prototype

double fmin(double x,
            double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Thread safety

Safe.

fminf()

Description

Compute minimum, float.

Prototype

float fminf(float x,
            float y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Thread safety

Safe.

fminl()

Description

Compute minimum, long double.

Prototype

long double fminl(long double x,
                  long double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Thread safety

Safe.

fmax()

Description

Compute maximum, double.

Prototype

double fmax(double x,
            double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Thread safety

Safe.

fmaxf()

Description

Compute maximum, float.

Prototype

float fmaxf(float x,
            float y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Thread safety

Safe.

fmaxl()

Description

Compute maximum, long double.

Prototype

long double fmaxl(long double x,
                  long double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Thread safety

Safe.

fdim()

Description

Positive difference, double.

Prototype

double fdim(double x,
            double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Thread safety

Safe.

fdimf()

Description

Positive difference, float.

Prototype

float fdimf(float x,
            float y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Thread safety

Safe.

fdiml()

Description

Positive difference, long double.

Prototype

long double fdiml(long double x,
                  long double y);

Parameters

Parameter Description
x Value #1.
y Value #2.

Return value

Thread safety

Safe.

Miscellaneous functions

Function Description
nextafter() Next machine-floating value, double.
nextafterf() Next machine-floating value, float.
nextafterl() Next machine-floating value, long double.
nexttoward() Next machine-floating value, double.
nexttowardf() Next machine-floating value, float.
nexttowardl() Next machine-floating value, long double.
nan() Parse NaN, double.
nanf() Parse NaN, float.
nanl() Parse NaN, long double.
copysign() Copy sign, double.
copysignf() Copy sign, float.
copysignl() Copy sign, long double.
nextafter()

Description

Next machine-floating value, double.

Prototype

double nextafter(double x,
                 double y);

Parameters

Parameter Description
x Value to step from.
y Director to step in.

Return value

Next machine-floating value after x in direction of y.

Thread safety

Safe.

nextafterf()

Description

Next machine-floating value, float.

Prototype

float nextafterf(float x,
                 float y);

Parameters

Parameter Description
x Value to step from.
y Director to step in.

Return value

Next machine-floating value after x in direction of y.

Thread safety

Safe.

nextafterl()

Description

Next machine-floating value, long double.

Prototype

long double nextafterl(long double x,
                       long double y);

Parameters

Parameter Description
x Value to step from.
y Director to step in.

Return value

Next machine-floating value after x in direction of y.

Thread safety

Safe.

nexttoward()

Description

Next machine-floating value, double.

Prototype

double nexttoward(double      x,
                  long double y);

Parameters

Parameter Description
x Value to step from.
y Direction to step in.

Return value

Next machine-floating value after x in direction of y.

Thread safety

Safe.

nexttowardf()

Description

Next machine-floating value, float.

Prototype

float nexttowardf(float       x,
                  long double y);

Parameters

Parameter Description
x Value to step from.
y Direction to step in.

Return value

Next machine-floating value after x in direction of y.

Thread safety

Safe.

nexttowardl()

Description

Next machine-floating value, long double.

Prototype

long double nexttowardl(long double x,
                        long double y);

Parameters

Parameter Description
x Value to step from.
y Direction to step in.

Return value

Next machine-floating value after x in direction of y.

Thread safety

Safe.

nan()

Description

Parse NaN, double.

Prototype

double nan(const char * tag);

Parameters

Parameter Description
tag NaN tag.

Return value

Quiet NaN formed from tag.

Thread safety

Safe.

nanf()

Description

Parse NaN, float.

Prototype

float nanf(const char * tag);

Parameters

Parameter Description
tag NaN tag.

Return value

Quiet NaN formed from tag.

Thread safety

Safe.

nanl()

Description

Parse NaN, long double.

Prototype

long double nanl(const char * tag);

Parameters

Parameter Description
tag NaN tag.

Return value

Quiet NaN formed from tag.

Thread safety

Safe.

copysign()

Description

Copy sign, double.

Prototype

double copysign(double x,
                double y);

Parameters

Parameter Description
x Floating value to inject sign into.
y Floating value carrying the sign to inject.

Return value

x with the sign of y.

Thread safety

Safe.

copysignf()

Description

Copy sign, float.

Prototype

float copysignf(float x,
                float y);

Parameters

Parameter Description
x Floating value to inject sign into.
y Floating value carrying the sign to inject.

Return value

x with the sign of y.

Thread safety

Safe.

copysignl()

Description

Copy sign, long double.

Prototype

long double copysignl(long double x,
                      long double y);

Parameters

Parameter Description
x Floating value to inject sign into.
y Floating value carrying the sign to inject.

Return value

x with the sign of y.

Thread safety

Safe.

<setjmp.h>

Function Description
setjmp() Save calling environment for non-local jump.
longjmp() Restores the saved environment.

Non-local flow control

setjmp()

Description

Save calling environment for non-local jump.

Prototype

int setjmp(jmp_buf buf);

Parameters

Parameter Description
buf Buffer to save context into.

Return value

On return from a direct invocation, returns the value zero. On return from a call to the longjmp() function, returns a nonzero value determined by the call to longjmp().

Additional information

Saves its calling environment in env for later use by the longjmp() function.

The environment saved by a call to setjmp () consists of information sufficient for a call to the longjmp() function to return execution to the correct block and invocation of that block, were it called recursively.

Thread safety

Safe.

longjmp()

Description

Restores the saved environment.

Prototype

void longjmp(jmp_buf buf,
             int     val);

Parameters

Parameter Description
buf Buffer to restore context from.
val Value to return to setjmp() call.

Additional information

Restores the environment saved by setjmp() in the corresponding env argument. If there has been no such invocation, or if the function containing the invocation of setjmp() has terminated execution in the interim, the behavior of longjmp() is undefined.

After longjmp() is completed, program execution continues as if the corresponding invocation of setjmp() had just returned the value specified by val.

Objects of automatic storage allocation that are local to the function containing the invocation of the corresponding setjmp() that do not have volatile-qualified type and have been changed between the setjmp() invocation and longjmp() call are indeterminate.

Notes

longjmp() cannot cause setjmp() to return the value 0; if val is 0, setjmp() returns the value 1.

Thread safety

Safe.

<signal.h>

Function Description
signal() Register signal function.
raise() Raise a signal.

Exceptions

signal()

Description

Register signal function.

Prototype

__SEGGER_RTL_SIGNAL_FUNC *signal(int sig,
                                     __SEGGER_RTL_SIGNAL_FUNC *func);

Parameters

Parameter Description
sig Signal being registered.
func Function to call when signal raised.

Return value

Previously-registered signal handler.

Thread safety

Safe.

raise()

Description

Raise a signal.

Prototype

int raise(int sig);

Parameters

Parameter Description
sig Signal to raise.

Return value

Zero if success.

Additional information

Signal handlers are executed in the context of the calling thread, if any. Signal handlers should not access or maniplate thread-local data.

Thread safety

Safe.

<stdbool.h>

Macros

bool

Description

Macros expanding to support the Boolean type.

Definition

#define bool     _Bool
#define true     1
#define false    0

Symbols

Definition Description
bool Underlying boolean type
true Boolean true value
false Boolean false value

<stddef.h>

Macros

NULL

Description

Null-pointer constant.

Definition

#define NULL    0

Symbols

Definition Description
NULL Null pointer
offsetof

Description

Calculate offset of member from start of structure.

Definition

#define offsetof(s,m)    ((size_t)&(((s *)0)->m))

Symbols

Definition Description
offsetof(s,m) Offset of m within s

Types

size_t

Description

Unsigned integral type returned by the sizeof operator.

Type definition

typedef __SEGGER_RTL_SIZE_T size_t;
ptrdiff_t

Description

Signed integral type of the result of subtracting two pointers.

Type definition

typedef __SEGGER_RTL_PTRDIFF_T ptrdiff_t;
wchar_t

Description

Integral type that can hold one wide character.

Type definition

typedef __SEGGER_RTL_WCHAR_T wchar_t;

<stdint.h>

Minima and maxima

Signed integer minima and maxima

Description

Minimum and maximum values for signed integer types.

Definition

#define INT8_MIN     (-128)
#define INT8_MAX     127
#define INT16_MIN    (-32767-1)
#define INT16_MAX    32767
#define INT32_MIN    (-2147483647L-1)
#define INT32_MAX    2147483647L
#define INT64_MIN    (-9223372036854775807LL-1)
#define INT64_MAX    9223372036854775807LL

Symbols

Definition Description
INT8_MIN Minimum value of int8_t
INT8_MAX Maximum value of int8_t
INT16_MIN Minimum value of int16_t
INT16_MAX Maximum value of int16_t
INT32_MIN Minimum value of int32_t
INT32_MAX Maximum value of int32_t
INT64_MIN Minimum value of int64_t
INT64_MAX Maximum value of int64_t
Unsigned integer minima and maxima

Description

Minimum and maximum values for unsigned integer types.

Definition

#define UINT8_MAX     255
#define UINT16_MAX    65535
#define UINT32_MAX    4294967295UL
#define UINT64_MAX    18446744073709551615ULL

Symbols

Definition Description
UINT8_MAX Maximum value of uint8_t
UINT16_MAX Maximum value of uint16_t
UINT32_MAX Maximum value of uint32_t
UINT64_MAX Maximum value of uint64_t
Maximal integer minima and maxima

Description

Minimum and maximum values for signed and unsigned maximal-integer types.

Definition

#define INTMAX_MIN     INT64_MIN
#define INTMAX_MAX     INT64_MAX
#define UINTMAX_MAX    UINT64_MAX

Symbols

Definition Description
INTMAX_MIN Minimum value of intmax_t
INTMAX_MAX Maximum value of intmax_t
UINTMAX_MAX Maximum value of uintmax_t
Least integer minima and maxima

Description

Minimum and maximum values for signed and unsigned least-integer types.

Definition

#define INT_LEAST8_MIN      INT8_MIN
#define INT_LEAST8_MAX      INT8_MAX
#define INT_LEAST16_MIN     INT16_MIN
#define INT_LEAST16_MAX     INT16_MAX
#define INT_LEAST32_MIN     INT32_MIN
#define INT_LEAST32_MAX     INT32_MAX
#define INT_LEAST64_MIN     INT64_MIN
#define INT_LEAST64_MAX     INT64_MAX
#define UINT_LEAST8_MAX     UINT8_MAX
#define UINT_LEAST16_MAX    UINT16_MAX
#define UINT_LEAST32_MAX    UINT32_MAX
#define UINT_LEAST64_MAX    UINT64_MAX

Symbols

Definition Description
INT_LEAST8_MIN Minimum value of int_least8_t
INT_LEAST8_MAX Maximum value of int_least8_t
INT_LEAST16_MIN Minimum value of int_least16_t
INT_LEAST16_MAX Maximum value of int_least16_t
INT_LEAST32_MIN Minimum value of int_least32_t
INT_LEAST32_MAX Maximum value of int_least32_t
INT_LEAST64_MIN Minimum value of int_least64_t
INT_LEAST64_MAX Maximum value of int_least64_t
UINT_LEAST8_MAX Maximum value of uint_least8_t
UINT_LEAST16_MAX Maximum value of uint_least16_t
UINT_LEAST32_MAX Maximum value of uint_least32_t
UINT_LEAST64_MAX Maximum value of uint_least64_t
Fast integer minima and maxima

Description

Minimum and maximum values for signed and unsigned fast-integer types.

Definition

#define INT_FAST8_MIN      INT8_MIN
#define INT_FAST8_MAX      INT8_MAX
#define INT_FAST16_MIN     INT32_MIN
#define INT_FAST16_MAX     INT32_MAX
#define INT_FAST32_MIN     INT32_MIN
#define INT_FAST32_MAX     INT32_MAX
#define INT_FAST64_MIN     INT64_MIN
#define INT_FAST64_MAX     INT64_MAX
#define UINT_FAST8_MAX     UINT8_MAX
#define UINT_FAST16_MAX    UINT32_MAX
#define UINT_FAST32_MAX    UINT32_MAX
#define UINT_FAST64_MAX    UINT64_MAX

Symbols

Definition Description
INT_FAST8_MIN Minimum value of int_fast8_t
INT_FAST8_MAX Maximum value of int_fast8_t
INT_FAST16_MIN Minimum value of int_fast16_t
INT_FAST16_MAX Maximum value of int_fast16_t
INT_FAST32_MIN Minimum value of int_fast32_t
INT_FAST32_MAX Maximum value of int_fast32_t
INT_FAST64_MIN Minimum value of int_fast64_t
INT_FAST64_MAX Maximum value of int_fast64_t
UINT_FAST8_MAX Maximum value of uint_fast8_t
UINT_FAST16_MAX Maximum value of uint_fast16_t
UINT_FAST32_MAX Maximum value of uint_fast32_t
UINT_FAST64_MAX Maximum value of uint_fast64_t
Pointer types minima and maxima

Description

Minimum and maximum values for pointer-related types.

Definition

#define PTRDIFF_MIN    INT64_MIN
#define PTRDIFF_MAX    INT64_MAX
#define SIZE_MAX       INT64_MAX
#define INTPTR_MIN     INT64_MIN
#define INTPTR_MAX     INT64_MAX
#define UINTPTR_MAX    UINT64_MAX

Symbols

Definition Description
PTRDIFF_MIN Minimum value of ptrdiff_t
PTRDIFF_MAX Maximum value of ptrdiff_t
SIZE_MAX Maximum value of size_t
INTPTR_MIN Minimum value of intptr_t
INTPTR_MAX Maximum value of intptr_t
UINTPTR_MAX Maximum value of uintptr_t
PTRDIFF_MIN Minimum value of ptrdiff_t
PTRDIFF_MAX Maximum value of ptrdiff_t
SIZE_MAX Maximum value of size_t
INTPTR_MIN Minimum value of intptr_t
INTPTR_MAX Maximum value of intptr_t
UINTPTR_MAX Maximum value of uintptr_t
Wide integer minima and maxima

Description

Minimum and maximum values for the wint_t type.

Definition

#define WINT_MIN    (-2147483647L-1)
#define WINT_MAX    2147483647L

Symbols

Definition Description
WINT_MIN Minimum value of wint_t
WINT_MAX Maximum value of wint_t

Constant construction macros

Signed integer construction macros

Description

Macros that create constants of type intx_t.

Definition

#define INT8_C(x)     (x)
#define INT16_C(x)    (x)
#define INT32_C(x)    (x)
#define INT64_C(x)    (x##LL)

Symbols

Definition Description
INT8_C(x) Create constant of type int8_t
INT16_C(x) Create constant of type int16_t
INT32_C(x) Create constant of type int32_t
INT64_C(x) Create constant of type int64_t
Unsigned integer construction macros

Description

Macros that create constants of type uintx_t.

Definition

#define UINT8_C(x)     (x##u)
#define UINT16_C(x)    (x##u)
#define UINT32_C(x)    (x##u)
#define UINT64_C(x)    (x##uLL)

Symbols

Definition Description
UINT8_C(x) Create constant of type uint8_t
UINT16_C(x) Create constant of type uint16_t
UINT32_C(x) Create constant of type uint32_t
UINT64_C(x) Create constant of type uint64_t
Maximal integer construction macros

Description

Macros that create constants of type intmax_t and uintmax_t.

Definition

#define INTMAX_C(x)     (x##LL)
#define UINTMAX_C(x)    (x##uLL)

Symbols

Definition Description
INTMAX_C(x) Create constant of type intmax_t
UINTMAX_C(x) Create constant of type uintmax_t

<stdio.h>

Formatted output control strings

The functions in this section that accept a formatted output control string do so according to the specification that follows.

Composition

The format is composed of zero or more directives: ordinary characters (not %, which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments, converting them, if applicable, according to the corresponding conversion specifier, and then writing the result to the output stream.

Each conversion specification is introduced by the character %. After the % the following appear in sequence:

As noted above, a field width, or precision, or both, may be indicated by an asterisk. In this case, an int argument supplies the field width or precision. The arguments specifying field width, or precision, or both, must appear (in that order) before the argument (if any) to be converted. A negative field width argument is taken as a - flag followed by a positive field width. A negative precision argument is taken as if the precision were omitted.

Flag characters

The flag characters and their meanings are:

Flag Description
- The result of the conversion is left-justified within the field. The default, if this flag is not specified, is that the result of the conversion is left-justified within the field.
+ The result of a signed conversion always begins with a plus or minus sign. The default, if this flag is not specified, is that it begins with a sign only when a negative value is converted.
space If the first character of a signed conversion is not a sign, or if a signed conversion results in no characters, a space is prefixed to the result. If the space and + flags both appear, the space flag is ignored.
# The result is converted to an alternative form. For o conversion, it increases the precision, if and only if necessary, to force the first digit of the result to be a zero (if the value and precision are both zero, a single 0 is printed). For x or X conversion, a nonzero result has 0x or 0X prefixed to it. For e, E, f, F, g, and G conversions, the result of converting a floating-point number always contains a decimal-point character, even if no digits follow it. (Normally, a decimal-point character appears in the result of these conversions only if a digit follows it.) For g and F conversions, trailing zeros are not removed from the result. As an extension, when used in p conversion, the results has # prefixed to it. For other conversions, the behavior is undefined.
0 For d, i, o, u, x, X, e, E, f, F, g, and G conversions, leading zeros (following any indication of sign or base) are used to pad to the field width rather than performing space padding, except when converting an infinity or NaN. If the 0 and - flags both appear, the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a precision is specified, the 0 flag is ignored. For other conversions, the behavior is undefined.
Length modifiers

The length modifiers and their meanings are:

Flag Description
hh Specifies that a following d, i, o, u, x, or X conversion specifier applies to a signed char or unsigned char argument (the argument will have been promoted according to the integer promotions, but its value will be converted to signed char or unsigned char before printing); or that a following n conversion specifier applies to a pointer to a signed char argument.
h Specifies that a following d, i, o, u, x, or X conversion specifier applies to a short int or unsigned short int argument (the argument will have been promoted according to the integer promotions, but its value is converted to short int or unsigned short int before printing); or that a following n conversion specifier applies to a pointer to a short int argument.
l Specifies that a following d, i, o, u, x, or X conversion specifier applies to a long int or unsigned long int argument; that a following n conversion specifier applies to a pointer to a long int argument; or has no effect on a following e, E, f, F, g, or G conversion specifier.
ll Specifies that a following d, i, o, u, x, or X conversion specifier applies to a long long int or unsigned long long int argument; that a following n conversion specifier applies to a pointer to a long long int argument.
L Specifies that a following e, E, f, F, g, or G conversion specifier applies to a long double argument.

If a length modifier appears with any conversion specifier other than as specified above, the behavior is undefined.

Conversion specifiers

The conversion specifiers and their meanings are:

Flag Description
d, i The argument is converted to signed decimal in the style [-]dddd. The precision specifies the minimum number of digits to appear; if the value being converted can be represented in fewer digits, it is expanded with leading spaces. The default precision is one. The result of converting a zero value with a precision of zero is no characters.
o, u, x, X The unsigned argument is converted to unsigned octal for o, unsigned decimal for u, or unsigned hexadecimal notation for x or X in the style dddd the letters abcdef are used for x conversion and the letters ABCDEF for X conversion. The precision specifies the minimum number of digits to appear; if the value being converted can be represented in fewer digits, it is expanded with leading spaces. The default precision is one. The result of converting a zero value with a precision of zero is no characters.
f, F A double argument representing a floating-point number is converted to decimal notation in the style [-]ddd.ddd, where the number of digits after the decimal-point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is zero and the # flag is not specified, no decimal-point character appears. If a decimal-point character appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. A double argument representing an infinity is converted to inf. A double argument representing a NaN is converted to nan. The F conversion specifier produces INF or NAN instead of inf or nan, respectively.
e, E A double argument representing a floating-point number is converted in the style [-]d.ddddd, where there is one digit (which is nonzero if the argument is nonzero) before the decimal-point character and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero and the # flag is not specified, no decimal-point character appears. The value is rounded to the appropriate number of digits. The E conversion specifier produces a number with E instead of e introducing the exponent. The exponent always contains at least two digits, and only as many more digits as necessary to represent the exponent. If the value is zero, the exponent is zero. A double argument representing an infinity is converted to inf. A double argument representing a NaN is converted to nan. The E conversion specifier produces INF or NAN instead of inf or nan, respectively.
g, G A double argument representing a floating-point number is converted in style f or e (or in style F or e in the case of a G conversion specifier), with the precision specifying the number of significant digits. If the precision is zero, it is taken as one. The style used depends on the value converted; style e (or E) is used only if the exponent resulting from such a conversion is less than -4 or greater than or equal to the precision. Trailing zeros are removed from the fractional portion of the result unless the # flag is specified; a decimal-point character appears only if it is followed by a digit. A double argument representing an infinity is converted to inf. A double argument representing a NaN is converted to nan. The G conversion specifier produces INF or NAN instead of inf or nan, respectively.
c The argument is converted to an unsigned char, and the resulting character is written.
s The argument is be a pointer to the initial element of an array of character type. Characters from the array are written up to (but not including) the terminating null character. If the precision is specified, no more than that many characters are written. If the precision is not specified or is greater than the size of the array, the array must contain a null character.
p The argument is a pointer to void. The value of the pointer is converted in the same format as the x conversion specifier with a fixed precision of 2*sizeof(void *).
n The argument is a pointer to a signed integer into which is written the number of characters written to the output stream so far by the call to the formatting function. No argument is converted, but one is consumed. If the conversion specification includes any flags, a field width, or a precision, the behavior is undefined.
% A % character is written. No argument is converted.

Note that the C99 width modifier l used in conjunction with the c and s conversion specifiers is not supported and nor are the conversion specifiers a and A.

Formatted input control strings

The format is composed of zero or more directives: one or more white-space characters, an ordinary character (neither % nor a white-space character), or a conversion specification.

Each conversion specification is introduced by the character %. After the %, the following appear in sequence:

The formatted input function executes each directive of the format in turn. If a directive fails, the function returns. Failures are described as input failures (because of the occurrence of an encoding error or the unavailability of input characters), or matching failures (because of inappropriate input).

A directive composed of white-space character(s) is executed by reading input up to the first non-white-space character (which remains unread), or until no more characters can be read.

A directive that is an ordinary character is executed by reading the next characters of the stream. If any of those characters differ from the ones composing the directive, the directive fails and the differing and subsequent characters remain unread. Similarly, if end-of-file, an encoding error, or a read error prevents a character from being read, the directive fails.

A directive that is a conversion specification defines a set of matching input sequences, as described below for each specifier. A conversion specification is executed in the following steps:

Length modifiers

The length modifiers and their meanings are:

Flag Description
hh Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument with type pointer to signed char or pointer to unsigned char.
h Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument with type pointer to short int or unsigned short int.
l Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument with type pointer to long int or unsigned long int; that a following e, E, f, F, g, or G conversion specifier applies to an argument with type pointer to double.
ll Specifies that a following d, i, o, u, x, X, or n conversion specifier applies to an argument with type pointer to long long int or unsigned long long int.
L Specifies that a following e, E, f, F, g, or G conversion specifier applies to an argument with with type pointer to long double.

If a length modifier appears with any conversion specifier other than as specified above, the behavior is undefined. Note that the C99 length modifiers j, z, and t are not supported.

Conversion specifiers
Flag Description
d Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence of the strtol() function with the value 10 for the base argument. The corresponding argument must be a pointer to signed integer.
i Matches an optionally signed integer, whose format is the same as expected for the subject sequence of the strtol() function with the value zero for the base argument. The corresponding argument must be a pointer to signed integer.
o Matches an optionally signed octal integer, whose format is the same as expected for the subject sequence of the strtol() function with the value 18 for the base argument. The corresponding argument must be a pointer to signed integer.
u Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence of the strtoul() function with the value 10 for the base argument. The corresponding argument must be a pointer to unsigned integer.
x Matches an optionally signed hexadecimal integer, whose format is the same as expected for the subject sequence of the strtoul() function with the value 16 for the base argument. The corresponding argument must be a pointer to unsigned integer.
e, f, g Matches an optionally signed floating-point number whose format is the same as expected for the subject sequence of the strtod() function. The corresponding argument shall be a pointer to floating.
c Matches a sequence of characters of exactly the number specified by the field width (one if no field width is present in the directive). The corresponding argument must be a pointer to the initial element of a character array large enough to accept the sequence. No null character is added.
s Matches a sequence of non-white-space characters The corresponding argument must be a pointer to the initial element of a character array large enough to accept the sequence and a terminating null character, which will be added automatically.
[ Matches a nonempty sequence of characters from a set of expected characters (the scanset). The corresponding argument must be a pointer to the initial element of a character array large enough to accept the sequence and a terminating null character, which will be added automatically. The conversion specifier includes all subsequent characters in the format string, up to and including the matching right bracket ]. The characters between the brackets (the scanlist) compose the scanset, unless the character after the left bracket is a circumflex ^, in which case the scanset contains all characters that do not appear in the scanlist between the circumflex and the right bracket. If the conversion specifier begins with [] or[^], the right bracket character is in the scanlist and the next following right bracket character is the matching right bracket that ends the specification; otherwise the first following right bracket character is the one that ends the specification. If a - character is in the scanlist and is not the first, nor the second where the first character is a ^, nor the last character, it is treated as a member of the scanset.
p Reads a sequence output by the corresponding %p formatted output conversion. The corresponding argument must be a pointer to a pointer to void.
n No input is consumed. The corresponding argument shall be a pointer to signed integer into which is to be written the number of characters read from the input stream so far by this call to the formatted input function. Execution of a %n directive does not increment the assignment count returned at the completion of execution of the fscanf function. No argument is converted, but one is consumed. If the conversion specification includes an assignment-suppressing character or a field width, the behavior is undefined.
% Matches a single % character; no conversion or assignment occurs.

Note that the C99 width modifier l used in conjunction with the c, s, and [ conversion specifiers is not supported and nor are the conversion specifiers a and A.

File functions

Function Description
fopen() Open file.
freopen() Reopen file.
fread() Read from file.
fwrite() Write to file.
fclose() Close file.
feof() Test end-of-file indicator.
ferror() Test error indicator.
fflush() Flush file.
clearerr() Clear error and end-of-file indicator on file.
fsetpos() Set file position.
fgetpos() Get file position.
fseek() Set file position.
ftell() Get file position.
rewind() Rewind file.
rename() Rename file.
remove() Remove file.
tmpnam() Generate name for temporary file.
tmpfile() Generate temporary file.
fopen()

Description

Open file.

Prototype

FILE *fopen(const char * filename,
            const char * mode);

Parameters

Parameter Description
filename Pointer to zero-terminated file name.
mode Pointer to zero-terminated file mode.

Return value

= NULL File not opened.
NULL File opened.

Thread safety

Unsafe.

freopen()

Description

Reopen file.

Prototype

FILE *freopen(const char * filename,
              const char * mode,
                    FILE * stream);

Parameters

Parameter Description
filename Pointer to zero-terminated file name.
mode Pointer to zero-terminated file mode.
stream Pointer to file to reopen.

Return value

= NULL File not reopened.
NULL File reopened.

Thread safety

Unsafe.

fread()

Description

Read from file.

Prototype

size_t fread(void   * ptr,
                      size_t size,
             size_t   nmemb,
             FILE   * stream);

Parameters

Parameter Description
ptr Pointer to object to write to.
size Size of each element to read.
nmemb Number of elements to read.
stream Pointer to file to read from.

Return value

The number of elements successfully read, which may be less than nmemb if a read error or end-of-file is encountered.

Additional information

If size or nmemb is zero, fread() returns zero and the contents of the array and the state of the stream remain unchanged.

Thread safety

Unsafe.

fwrite()

Description

Write to file.

Prototype

size_t fwrite(const void   * ptr,
                             size_t size,
                    size_t   nmemb,
                    FILE   * stream);

Parameters

Parameter Description
ptr Pointer to data to write.
size Size of each element to write.
nmemb Number of elements to write.
stream Pointer to file to write to.

Return value

The number of elements successfully written, which may be less than nmemb if a read error or end-of-file is encountered.

Additional information

If size or nmemb is zero, fwrite() returns zero and the contents of the array and the state of the stream remain unchanged.

Thread safety

Unsafe.

fclose()

Description

Close file.

Prototype

int fclose(FILE * stream);

Parameters

Parameter Description
stream Pointer to file to close.

Return value

0 File successfully closed.
EOF File did not successfully close.

Thread safety

Unsafe.

feof()

Description

Test end-of-file indicator.

Prototype

int feof(FILE * stream);

Parameters

Parameter Description
stream Pointer to file to test.

Return value

= 0 No end-of-file on file.
≠ 0 End-of-file on file.

Thread safety

Unsafe.

ferror()

Description

Test error indicator.

Prototype

int ferror(FILE * stream);

Parameters

Parameter Description
stream Pointer to file to test.

Return value

= 0 No error on file.
≠ 0 Error on file.

Thread safety

Unsafe.

fflush()

Description

Flush file.

Prototype

int fflush(FILE * stream);

Parameters

Parameter Description
stream Pointer to file to flush, or NULL, indicating all files.

Return value

= 0 File (or all files) successfully flushed.
≠ EOF Error flushing one or more files.

Additional information

If stream points to file in write or update mode where the most-recent operation was not input, any unwritten data for that file is delivered to the host environment to be written; otherwise, the behavior is undefined.

Thread safety

Unsafe.

clearerr()

Description

Clear error and end-of-file indicator on file.

Prototype

void clearerr(FILE * stream);

Parameters

Parameter Description
stream Pointer to file to clear indicators on.

Thread safety

Unsafe.

fsetpos()

Description

Set file position.

Prototype

int fsetpos(      FILE   * stream,
            const fpos_t * pos);

Parameters

Parameter Description
stream Pointer to file to position.
pos Pointer to position.

Return value

= 0 Position set successfully.
≠ 0 Position not set successfully; errno set to ESPIPE.

Additional information

Sets the file position to pos which was previously retrieved using fgetpos().

Thread safety

Unsafe.

fgetpos()

Description

Get file position.

Prototype

int fgetpos(FILE   * stream,
            fpos_t * pos);

Parameters

Parameter Description
stream Pointer to file to position.
pos Pointer to object that receives the position.

Return value

= 0 Position retrieved successfully.
≠ 0 Position not retrieved successfully; errno set to ESPIPE.

Thread safety

Unsafe.

fseek()

Description

Set file position.

Prototype

int fseek(FILE * stream,
          long   offset,
          int    whence);

Parameters

Parameter Description
stream Pointer to file to position.
offset Offset relative to anchor specified by whence.
whence Where offset is relative to.

Return value

= 0 Position is set.
≠ 0 Position is not set.

Thread safety

Unsafe.

ftell()

Description

Get file position.

Prototype

long ftell(FILE * stream);

Parameters

Parameter Description
stream Pointer to file.

Return value

= 0 Position set successfully.
≠ 0 Position not set successfully; errno set to ESPIPE.

Additional information

Sets the file position to pos which was previously retrieved using fgetpos().

Thread safety

Unsafe.

rewind()

Description

Rewind file.

Prototype

void rewind(FILE * stream);

Parameters

Parameter Description
stream Pointer to file to rewind.

Additional information

Sets the file position to start of file.

Thread safety

Unsafe.

rename()

Description

Rename file.

Prototype

int rename(const char * oldname,
           const char * newname);

Parameters

Parameter Description
oldname Pointer to string denoting old file name.
newname Pointer to string denoting new file name.

Return value

= 0 Rename succeeded.
≠ 0 Rename failed.

Thread safety

Unsafe.

remove()

Description

Remove file.

Prototype

int remove(const char * filename);

Parameters

Parameter Description
filename Pointer to string denoting file name to remove.

Return value

= 0 Remove succeeded.
≠ 0 Remove failed.

Thread safety

Unsafe.

tmpnam()

Description

Generate name for temporary file.

Prototype

char *tmpnam(char * s);

Parameters

Parameter Description
s Pointer to object that receives the temporary file name, or NULL indicating that a (shared) internal buffer is used for the temporary name.

Return value

= NULL Cannot generate a unique temporary name.
NULL Pointer to temporary name generated.

Thread safety

Unsafe.

tmpfile()

Description

Generate temporary file.

Prototype

FILE *tmpfile(void);

Return value

= NULL Cannot generate a unique temporary file.
NULL Pointer to temporary file.

Thread safety

Unsafe.

Character and string I/O functions

Function Description
getc() Read character from stream.
fgetc() Read character from file.
getchar() Read character from standard input.
gets() Read string from standard input.
fgets() Read string from stream.
putc() Write character to file.
fputc() Write character to file.
putchar() Write character to standard output.
puts() Write string to standard output.
fputs() Write string to standard output.
ungetc() Push character back to file.
getc()

Description

Read character from stream.

Prototype

int getc(FILE * stream);

Parameters

Parameter Description
stream Pointer to file to read from.

Return value

If the stream is at end-of-file or a read error occurs, returns EOF, otherwise a nonnegative value.

Additional information

Reads a single character from a stream.

Thread safety

Unsafe.

fgetc()

Description

Read character from file.

Prototype

int fgetc(FILE * stream);

Parameters

Parameter Description
stream Pointer to file to read from.

Return value

If the end-of-file indicator for the stream is set, or if the stream is at end of file, the end-of-file indicator for the file is set and the fgetc function returns EOF. Otherwise, return the next character from the file pointed to by stream. If a read error occurs, the error indicator for the stream is set and return EOF.

Additional information

If the end-of-file indicator for the input stream pointed to by stream is not set and a next character is present, obtain that character as an unsigned char converted to an int and advance the associated file position.

Thread safety

Unsafe.

getchar()

Description

Read character from standard input.

Prototype

int getchar(void);

Return value

If the stream is at end-of-file or a read error occurs, returns EOF, otherwise a nonnegative value.

Additional information

Reads a single character from the standard input stream.

Thread safety

Unsafe.

gets()

Description

Read string from standard input.

Prototype

char *gets(char * s);

Parameters

Parameter Description
s Pointer to object that receives the string.

Return value

Returns s if successful. If end-of-file is encountered and no characters have been read into the array, the contents of the array remain unchanged and a null pointer is returned. If a read error occurs during the operation, the array contents are indeterminate and a null null pointer is return.

Additional information

This function reads characters from standard input into the array pointed to by s until end-of-file is encountered or a newline character is read. Any newline character is discarded, and a null character is written immediately after the last character read into the array.

Thread safety

Unsafe.

fgets()

Description

Read string from stream.

Prototype

char *fgets(char * s,
            int    n,
            FILE * stream);

Parameters

Parameter Description
s Pointer to object to write to.
n Number of bytes to read.
stream Pointer to file to read from.

Return value

Returns s if successful. If end-of-file is encountered and no characters have been read into the array, the contents of the array remain unchanged and a null pointer is returned. If a read error occurs during the operation, the array contents are indeterminate and a null pointer is returned.

Additional information

Reads at most one less than the number of characters specified by n from the file pointed to by stream into the array pointed to by s. No additional characters are read after a newline character (which is retained) or after end of file. A null character is written immediately after the last character read into the array.

Thread safety

Unsafe.

putc()

Description

Write character to file.

Prototype

int putc(int    c,
         FILE * stream);

Parameters

Parameter Description
c Character to write.
stream Pointer to stream to write to.

Return value

If no error, the character written. If a write error occurs, returns EOF.

Additional information

Writes the character c to stream.

Thread safety

Unsafe.

fputc()

Description

Write character to file.

Prototype

int fputc(int