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:
- Clean ISO/ANSI C source code.
- Fast assembly language floating point support.
- Conforms to standard runtime ABIs for the Arm and RISC-V architectures.
- Simple configuration.
- Royalty free.
Recommended project structure
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:
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. |
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:
- Replace a repeated-fill loop with a call to memset().
- Replace a repeated-copy loop with a call to memcpy().
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:
- Replace exp(10, x) with a call to exp10(x).
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 |
|---|
|
| __GNUC__ | Compiler is GNU C. |
| __clang__ | Compiler is Clang. |
|
| __thumb__ | Target the Thumb instruction set (as opposed to ARM). |
| __thumb2__ | Target the Thumb-2 instruction set. |
|
| __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.
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.
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:
- A real-time heap where allocation and deallocation have O(1) performance,
provided in heapops_realtime.c and __SEGGER_RTL_RTHEAP.c.
- A low-overhead best-fit heap where allocation and deallocation have very
little internal fragmentation, provided in heapops_basic.c. This
implementation has no support for aligned_alloc().
- An allocate-only heap where deallocation and reallocation are not
implemented, provided in heapops_minimal.c. This implementation
only supports malloc() and calloc().
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.
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 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.
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:
- Unsafe: This function is never safe to use in a multi-threaded
environment and requires callers to ensure only a single thread of execution
uses this function.
- Safe [if configured]: This function is safe to use in a
multi-threaded system only if emRun is configured to be thread-safe
in co-operation with the underlying RTOS. Typically this relates to the
heap and any function that uses per-thread (thread-local) data as described
in previous sections.
- Safe: This function is always safe to use in a multi-threaded
system. Typically this relates to state-free functions such as sin() and
div(). This function is also safe to use between threads if the objects
pointed to by any user-supplied pointers are in use by a single thread
only. Typically this relates to functions such as strcat() which are
thread-safe only if the objects passed into the function are not shared
between threads.
- Not applicable: Thread-safety does not apply to this function as it
is not intended for execution in a threading environment. Typically this relates
to runtime functions that initialize to deinitialize the runtime system.
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:
- INFINITY + I * copysign(0.0, cimag(x))
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:
- INFINITY + I * copysign(0.0, cimag(x))
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:
- INFINITY + I * copysignl(0.0, cimagl(x))
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:
- csinh(conj(z)) = conj(csinh(z)).
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:
- csinh(conj(z)) = conj(csinh(z)).
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:
- csinh(conj(z)) = conj(csinh(z)).
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:
- ccosh(conj(z)) = conj(ccosh(z)).
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:
- ccosh(conj(z)) = conj(ccosh(z)).
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:
- ccosh(conj(z)) = conj(ccosh(z)).
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:
- ctanh(conj(z)) = conj(ctanh(z)).
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:
- ctanhf(conj(z)) = conj(ctanhf(z)).
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:
- ctanh(conj(z)) = conj(ctanh(z)).
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:
- casinh(conj(z)) = conj(casinh(z)).
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:
- casinh(conj(z)) = conj(casinh(z)).
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:
- casinh(conj(z)) = conj(casinh(z)).
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:
- cacosh(conj(z)) = conj(cacosh(z)).
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:
- cacosh(conj(z)) = conj(cacosh(z)).
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:
- cacosh(conj(z)) = conj(cacosh(z)).
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:
- catanh(conj(z)) = conj(catanh(z)).
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:
- catanh(conj(z)) = conj(catanh(z)).
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:
- catanh(conj(z)) = conj(catanh(z)).
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:
- csqrt(conj(z)) = conj(csqrt(z)).
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:
- csqrt(conj(z)) = conj(csqrt(z)).
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:
- csqrt(conj(z)) = conj(csqrt(z)).
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:
- clog(conj(z)) = conj(clog(z)).
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:
- clog(conj(z)) = conj(clog(z)).
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:
- clog(conj(z)) = conj(clog(z)).
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
- cexp(conj(x)) = conj(cexp(x)).
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
- cexp(conj(x)) = conj(cexp(x)).
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
- cexp(conj(x)) = conj(cexp(x)).
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
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
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
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- If x < 0, return NaN.
- Else, return square root of x.
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- If x < 0, return NaN.
- Else, return square root of x.
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- If x < 0, return NaN.
- Else, return square root of x.
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return cube root of x.
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return cube root of x.
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return cube root of x.
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
- If x is +/-zero, return +/-infinity.
- If x is positively infinite, return 0.
- If x is NaN, return x.
- If x < 0, return NaN.
- Else, return reciprocal square root of x.
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
- If x is +/-zero, return +/-infinity.
- If x is positively infinite, return 0.
- If x is NaN, return x.
- If x < 0, return NaN.
- Else, return reciprocal square root of x.
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
- If x is +/-zero, return +/-infinity.
- If x is positively infinite, return 0.
- If x is NaN, return x.
- If x < 0, return NaN.
- Else, return reciprocal square root of x.
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
- If x is NaN, return x.
- If x is positively infinite, return x.
- If x is negatively infinite, return 0.
- Else, return base-e exponential of x.
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
- If x is NaN, return x.
- If x is positively infinite, return x.
- If x is negatively infinite, return 0.
- Else, return base-e exponential of x.
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
- If x is NaN, return x.
- If x is positively infinite, return x.
- If x is negatively infinite, return 0.
- Else, return base-e exponential of x.
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
- If x is NaN, return x.
- Else, return base-e exponential of x minus 1 (e**x - 1).
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
- If x is NaN, return x.
- Else, return base-e exponential of x minus 1 (e**x - 1).
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
- If x is NaN, return x.
- Else, return base-e exponential of x minus 1 (e**x - 1).
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
- If x is NaN, return x.
- If x is positively infinite, return x.
- If x is negatively infinite, return 0.
- Else, return base-e exponential of x.
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
- If x is NaN, return x.
- If x is positively infinite, return x.
- If x is negatively infinite, return 0.
- Else, return base-e exponential of x.
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
- If x is NaN, return x.
- If x is positively infinite, return x.
- If x is negatively infinite, return 0.
- Else, return base-e exponential of x.
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
- If x is NaN, return x.
- If x is positively infinite, return x.
- If x is negatively infinite, return 0.
- Else, return base-e exponential of x.
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
- If x is NaN, return x.
- If x is positively infinite, return x.
- If x is negatively infinite, return 0.
- Else, return base-e exponential of x.
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
- If x is NaN, return x.
- If x is positively infinite, return x.
- If x is negatively infinite, return 0.
- Else, return base-e exponential of x.
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
- If x is zero, infinite or NaN, return x and store zero into the integer pointed to by exp.
- Else, return the value f, such that f has a magnitude in the interval [0.5, 1) and x equals f * pow(2, *exp)
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
- If x is zero, infinite or NaN, return x and store zero into the integer pointed to by exp.
- Else, return the value f, such that f has a magnitude in the interval [0.5, 1) and x equals f * pow(2, *exp)
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
- If x is zero, infinite or NaN, return x and store zero into the integer pointed to by exp.
- Else, return the value f, such that f has a magnitude in the interval [0.5, 1) and x equals f * pow(2, *exp)
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
- If x or y are infinite, return infinity.
- If x or y is NaN, return NaN.
- Else, return sqrt(x*x + y*y).
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
- If x or y are infinite, return infinity.
- If x or y is NaN, return NaN.
- Else, return sqrt(x*x + y*y).
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
- If x or y are infinite, return infinity.
- If x or y is NaN, return NaN.
- Else, return sqrtl(x*x + y*y).
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return -∞.
- If x is +∞, return +∞.
- ELse, return base-e logarithm of x.
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return negative infinity.
- If x is positively infinite, return infinity.
- ELse, return base-e logarithm of x.
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return -∞.
- If x is +∞, return +∞.
- ELse, return base-e logarithm of x.
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return negative infinity.
- If x is positively infinite, return infinity.
- ELse, return base-10 logarithm of x.
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return negative infinity.
- If x is positively infinite, return infinity.
- ELse, return base-10 logarithm of x.
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return negative infinity.
- If x is positively infinite, return infinity.
- ELse, return base-10 logarithm of x.
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return negative infinity.
- If x is positively infinite, return infinity.
- ELse, return base-10 logarithm of x.
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return negative infinity.
- If x is positively infinite, return infinity.
- ELse, return base-10 logarithm of x.
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return negative infinity.
- If x is positively infinite, return infinity.
- ELse, return base-10 logarithm of x.
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
- If x is zero, return -∞.
- If x is infinite, return +∞.
- If x is NaN, return NaN.
- Else, return integer part of logFLTRADIX(x).
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
- If x is zero, return -∞.
- If x is infinite, return +∞.
- If x is NaN, return NaN.
- Else, return integer part of logFLTRADIX(x).
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
- If x is zero, return -∞.
- If x is infinite, return +∞.
- If x is NaN, return NaN.
- Else, return integer part of logFLTRADIX(x).
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
- If x is zero, return FP_ILOGB0.
- If x is NaN, return FP_ILOGBNAN.
- If x is infinite, return MAX_INT.
- Else, return integer part of logFLTRADIX(x).
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
- If x is zero, return FP_ILOGB0.
- If x is NaN, return FP_ILOGBNAN.
- If x is infinite, return MAX_INT.
- Else, return integer part of logFLTRADIX(x).
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
- If x is zero, return FP_ILOGB0.
- If x is NaN, return FP_ILOGBNAN.
- If x is infinite, return MAX_INT.
- Else, return integer part of logFLTRADIX(x).
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return negative infinity.
- If x is positively infinite, return infinity.
- ELse, return base-e logarithm of x+1.
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return negative infinity.
- If x is positively infinite, return infinity.
- ELse, return base-e logarithm of x+1.
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
- If x = NaN, return x.
- If x < 0, return NaN.
- If x = 0, return negative infinity.
- If x is positively infinite, return infinity.
- ELse, return base-e logarithm of x+1.
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
- If x is ±0, return x;
- If x is ±∞, return x.
- If x is NaN, return x.
- Else, return x * 2 ^ n.
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
- If x is zero, return x;
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return x * 2^n.
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
- If x is ±0, return x;
- If x is ±∞, return x.
- If x is NaN, return x.
- Else, return x * 2 ^ n.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return x * DBL_RADIX ^ n.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return x * FLT_RADIX ^ n.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return x * LDBL_RADIX ^ n.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return x * DBL_RADIX ^ n.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return x * FLT_RADIX ^ n.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return x * LDBL_RADIX ^ n.
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
- If x is NaN, return x.
- If x is infinite, return NaN.
- Else, return circular sine of x.
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
- If x is NaN, return x.
- If x is infinite, return NaN.
- Else, return circular sine of x.
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
- If x is NaN, return x.
- If x is infinite, return NaN.
- Else, return circular sine of x.
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
- If x is NaN, return x.
- If x is infinite, return NaN.
- Else, return circular cosine of x.
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
- If x is NaN, return x.
- If x is infinite, return NaN.
- Else, return circular cosine of x.
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
- If x is NaN, return x.
- If x is infinite, return NaN.
- Else, return circular cosine of x.
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
- If x is zero, return x.
- If x is infinite, return NaN.
- If x is NaN, return x.
- Else, return tangent of x.
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
- If x is zero, return x.
- If x is infinite, return NaN.
- If x is NaN, return x.
- Else, return tangent of x.
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
- If x is zero, return x.
- If x is infinite, return NaN.
- If x is NaN, return x.
- Else, return tangent of x.
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
- If x is NaN, return x.
- If x is infinite, return x.
- Else, return hyperbolic sine of x.
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
- If x is NaN, return x.
- If x is infinite, return x.
- Else, return hyperbolic sine of x.
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
- If x is NaN, return x.
- If x is infinite, return x.
- Else, return hyperbolic sine of x.
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
- If x is NaN, return x.
- If x is infinite, return +∞.
- Else, return hyperbolic cosine of x.
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
- If x is NaN, return x.
- If x is infinite, return +∞.
- Else, return hyperbolic cosine of x.
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
- If x is NaN, return x.
- If x is infinite, return +∞.
- Else, return hyperbolic cosine of x.
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
- If x is NaN, return x.
- Else, return hyperbolic tangent of x.
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
- If x is NaN, return x.
- Else, return hyperbolic tangent of x.
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
- If x is NaN, return x.
- Else, return hyperbolic tangent of x.
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
- If x is NaN, return x.
- If |x| > 1, return NaN.
- Else, return inverse circular sine of x.
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
- If x is NaN, return x.
- If |x| > 1, return NaN.
- Else, return inverse circular sine of x.
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
- If x is NaN, return x.
- If |x| > 1, return NaN.
- Else, return inverse circular sine of x.
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
- If x is NaN, return x.
- If |x| > 1, return NaN.
- Else, return inverse circular cosine of x.
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
- If x is NaN, return x.
- If |x| > 1, return NaN.
- Else, return inverse circular cosine of x.
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
- If x is NaN, return x.
- If |x| > 1, return NaN.
- Else, return inverse circular cosine of x.
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
- If x is NaN, return x.
- Else, return inverse tangent of x.
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
- If x is NaN, return x.
- Else, return inverse tangent of x.
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
- If x is NaN, return x.
- Else, return inverse tangent of x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return inverse hyperbolic sine of x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return inverse hyperbolic sine of x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return inverse hyperbolic sine of x.
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
- If x < 1, return NaN.
- If x is NaN, return x.
- Else, return non-negative inverse hyperbolic cosine of x.
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
- If x < 1, return NaN.
- If x is NaN, return x.
- Else, return non-negative inverse hyperbolic cosine of x.
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
- If x < 1, return NaN.
- If x is NaN, return x.
- Else, return non-negative inverse hyperbolic cosine of x.
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
- If x is NaN, return x.
- If |x| > 1, return NaN.
- If x = +/-1, return +/-infinity.
- Else, return non-negative inverse hyperbolic tangent of x.
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
- If x is NaN, return x.
- If |x| > 1, return NaN.
- If x = +/-1, return +/-infinity.
- Else, return non-negative inverse hyperbolic tangent of x.
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
- If x is NaN, return x.
- If |x| > 1, return NaN.
- If x = +/-1, return +/-infinity.
- Else, return non-negative inverse hyperbolic tangent of x.
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the smallest integer value not greater than x.
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the smallest integer value not greater than x.
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the smallest integer value not greater than x.
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the largest integer value not greater than x.
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the largest integer value not greater than x.
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
- If x is zero, return x.
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the largest integer value not greater than x.
Thread safety
Safe.
trunc()
Description
Truncate to integer, double.
Prototype
double trunc(double x);
Parameters
| Parameter | Description |
|---|
| x | Value to truncate. |
Return value
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return x with fractional part removed.
Thread safety
Safe.
truncf()
Description
Truncate to integer, float.
Prototype
float truncf(float x);
Parameters
| Parameter | Description |
|---|
| x | Value to truncate. |
Return value
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return x with fractional part removed.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return x with fractional part removed.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x, ties away from zero.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x, ties away from zero.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x, ties away from zero.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is infinite, return x.
- If x is NaN, return x.
- Else, return the nearest integer value to x.
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
- If x is NaN, return NaN.
- If x is zero and y is nonzero, return x.
- If x is infinite, return NaN.
- If x is finite and y is infinite, return x.
- If y is NaN, return NaN.
- If y is zero, return NaN.
- Else, return remainder of x divided by y.
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
- If x is NaN, return NaN.
- If x is zero and y is nonzero, return x.
- If x is infinite, return NaN.
- If x is finite and y is infinite, return x.
- If y is NaN, return NaN.
- If y is zero, return NaN.
- Else, return remainder of x divided by y.
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
- If x is NaN, return NaN.
- If x is zero and y is nonzero, return x.
- If x is infinite, return NaN.
- If x is finite and y is infinite, return x.
- If y is NaN, return NaN.
- If y is zero, return NaN.
- Else, return remainder of x divided by y.
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
- If x is NaN, return NaN.
- If x is zero and y is nonzero, return x.
- If x is infinite, return NaN.
- If x is finite and y is infinite, return x.
- If y is NaN, return NaN.
- If y is zero, return NaN.
- Else, return remainder of x divided by y.
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
- If x is NaN, return NaN.
- If x is zero and y is nonzero, return x.
- If x is infinite, return NaN.
- If x is finite and y is infinite, return x.
- If y is NaN, return NaN.
- If y is zero, return NaN.
- Else, return remainder of x divided by y.
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
- If x is NaN, return NaN.
- If x is zero and y is nonzero, return x.
- If x is infinite, return NaN.
- If x is finite and y is infinite, return x.
- If y is NaN, return NaN.
- If y is zero, return NaN.
- Else, return remainder of x divided by y.
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
- If x is NaN, return NaN.
- If x is zero and y is nonzero, return x.
- If x is infinite, return NaN.
- If x is finite and y is infinite, return x.
- If y is NaN, return NaN.
- If y is zero, return NaN.
- Else, return remainder of x divided by y.
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
- If x is NaN, return NaN.
- If x is zero and y is nonzero, return x.
- If x is infinite, return NaN.
- If x is finite and y is infinite, return x.
- If y is NaN, return NaN.
- If y is zero, return NaN.
- Else, return remainder of x divided by y.
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
- If x is NaN, return NaN.
- If x is zero and y is nonzero, return x.
- If x is infinite, return NaN.
- If x is finite and y is infinite, return x.
- If y is NaN, return NaN.
- If y is zero, return NaN.
- Else, return remainder of x divided by y.
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
- If x is NaN, return x.
- Else, absolute value of x.
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
- If x is NaN, return x.
- Else, absolute value of x.
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
- If x is NaN, return x.
- Else, absolute value of x.
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
- If x is NaN, return y.
- If y is NaN, return x.
- Else, return minimum of x and y.
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
- If x is NaN, return y.
- If y is NaN, return x.
- Else, return minimum of x and y.
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
- If x is NaN, return y.
- If y is NaN, return x.
- Else, return minimum of x and y.
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
- If x is NaN, return y.
- If y is NaN, return x.
- Else, return maximum of x and y.
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
- If x is NaN, return y.
- If y is NaN, return x.
- Else, return maximum of x and y.
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
- If x is NaN, return y.
- If y is NaN, return x.
- Else, return maximum of x and y.
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
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
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
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>
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:
- Zero or more flags (in any order) that modify the meaning of the
conversion specification.
- An optional minimum field width. If the converted value has fewer
characters than the field width, it is padded with spaces (by default) on
the left (or right, if the left adjustment flag has been given) to the field
width. The field width takes the form of an asterisk * or a decimal
integer.
- An optional precision that gives the minimum number of digits to appear
for the d, i, o, u, x, and X conversions, the number
of digits to appear after the decimal-point character for e,
E, f, and F conversions, the maximum number of significant
digits for the g and G conversions, or the maximum number
of bytes to be written for s conversions. The precision takes
the form of a period . followed either by an asterisk *
or by an optional decimal integer; if only the period is specified,
the precision is taken as zero. If a precision appears with any other
conversion specifier, the behavior is undefined.
- An optional length modifier that specifies the size of the argument.
- A conversion specifier character that specifies the type of conversion
to be applied.
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.ddde±dd, 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.
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:
- An optional assignment-suppressing character *.
- An optional nonzero decimal integer that specifies the maximum field width
(in characters).
- An optional length modifier that specifies the size of the receiving object.
- A conversion specifier character that specifies the type of conversion
to be applied.
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:
- Input white-space characters (as specified by the isspace() function)
are skipped, unless the specification includes a [, c, or n
specifier.
- An input item is read from the stream, unless the specification includes
an n specifier. An input item is defined as the longest sequence of input
characters which does not exceed any specified field width and which is, or
is a prefix of, a matching input sequence. The first character, if any, after
the input item remains unread. If the length of the input item is zero, the
execution of the directive fails; this condition is a matching failure unless
end-of-file, an encoding error, or a read error prevented input from the stream,
in which case it is an input failure.
- Except in the case of a % specifier, the
input item (or, in the case of a %n directive, the count of input characters)
is converted to a type appropriate to the conversion specifier. If the input
item is not a matching sequence, the execution of the directive fails: this
condition is a matching failure. Unless assignment suppression was indicated
by a *, the result of the conversion is
placed in the object pointed to by the first argument following the format
argument that has not already received a conversion result. If this object
does not have an appropriate type, or if the result of the conversion cannot
be represented in the object, 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, 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
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