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 |
|---|
| atomicops.c | Support for atomic operations. |
| 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(). |
| timeops_x.c | Support for low-level time operations e.g. __SEGGER_RTL_gettimeofday()}. |
| 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 availability 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;
++c;
}
} 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 varying 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.
Atomic datatype support
Athrough compilers will lay down instructions for data declared _Atomic,
some C-level operations will not be able to be achieved atomically.
To support this, emRun provides support for both GCC-defined and Clang-defined
atomic support functions which are implemented in terms of three C functions
that the user must provide:
- SEGGER_RTL_X_atomic_lock()
- SEGGER_RTL_X_atomic_unlock()
- SEGGER_RTL_X_atomic_synchronize()
C library API
This section describes the C library ABI.
Conformance section
Where a conformance section is present, it defined the conformance
of the function to a particular standards.
The non-C standards are:
- POSIX.1-2001: The function or object is defined by POSIX.1-2001,
and is defined in later POSIX.1 versions, unless otherwise indicated.
- POSIX.1-2007: The function or object is defined by POSIX.1-2007,
and is defined in later POSIX.1 versions, unless otherwise indicated.
- POSIX.1-2008: The function or object is defined by POSIX.1-2008,
and is defined in later POSIX.1 versions, unless otherwise indicated.
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.
<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
| Object | Description |
|---|
| errno | Macro returning the current error. |
| errno_t | Type describing errors (C11). |
Error names
Description
Symbolic error names for raised errors.
Definition
#define EHEAP 0x04
#define ENOMEM 0x05
#define EINVAL 0x06
#define ESPIPE 0x07
#define EAGAIN 0x08
#define ECHILD 0x09
#define EMLINK 0x0A
#define ENOENT 0x0B
#define EDOM (__aeabi_EDOM)
#define EILSEQ (__aeabi_EILSEQ)
#define ERANGE (__aeabi_ERANGE)
Symbols
| Definition | Description |
|---|
| EDOM | Internal use. |
| EILSEQ | Internal use. |
| ERANGE | Internal use. |
| EHEAP | Heap is corrupt (emRun) |
| ENOMEM | Out of memory (POSIX.1-2001) |
| EINVAL | Invalid parameter (POSIX.1-2001) |
| ESPIPE | Invalid seek (POSIX.1-2001) |
| EAGAIN | Resource unavailable, try again (POSIX.1-2001) |
| ECHILD | No child processes (POSIX.1-2001) |
| EMLINK | Too many links (POSIX.1-2001) |
| ENOENT | No such file or directory (POSIX.1-2001) Modify for AEABI compliance |
| EDOM | Internal use. |
| EILSEQ | Internal use. |
| ERANGE | Internal use. |
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.
errno_t
Description
Type describing errors (C11).
Type definition
typedef int errno_t;
Additional information
The macro __STDC_WANT_LIB_EXT1__ must be set to 1 before
including <errno.h> to access this type.
This type is used by the C11/C18 bounds-checking functions.
Conformance
ISO/IEC 9899:2011 (C11).
<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) __SEGGER_RTL_OFFSETOF(s, m)
Symbols
| Definition | Description |
|---|
| offsetof(s,m) | Internal use. |
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 c,
FILE * stream);
Parameters
| Parameter | Description |
|---|
| c | Character to write. |
| stream | Pointer to file 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.
putchar()
Description
Write character to standard output.
Prototype
int putchar(int c);
Parameters
| Parameter | Description |
|---|
| c | Character to write. |
Return value
If no error, the character written. If a write error occurs,
returns EOF.
Additional information
Writes the character c to the standard output stream.
Thread safety
Unsafe.
puts()
Description
Write string to standard output.
Prototype
int puts(const char * s);
Parameters
| Parameter | Description |
|---|
| s | Pointer to zero-terminated string. |
Return value
Returns EOF if a write error occurs; otherwise it returns
a nonnegative value.
Additional information
Writes the string pointed to by s to the standard output
stream using putchar() and appends a newline character to
the output. The terminating null character is not written.
Thread safety
Unsafe.
fputs()
Description
Write string to standard output.
Prototype
int fputs(const char * s,
FILE * stream);
Parameters
| Parameter | Description |
|---|
| s | Pointer to zero-terminated string. |
| stream | Pointer to file to write to. |
Return value
Returns EOF if a write error occurs; otherwise returns
a nonnegative value.
Additional information
Write the string pointed to by s to the file pointed to by
stream. The terminating null character is not written.
Thread safety
Unsafe.
ungetc()
Description
Push character back to file.
Prototype
int ungetc(int c,
FILE * stream);
Parameters
| Parameter | Description |
|---|
| c | Character to push back to file. |
| stream | File to push character to. |
Return value
| = EOF | Failed to push character back. |
| ≠ EOF | The character pushed back to the file. |
Additional information
This function pushes the character c back to the file stream so
that it can be read again. If c is EOF, the function fails and
EOF is returned. One character of pushback is guaranteed; if more
than one character is pushed back without an intervening read,
the pushback may fail.
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.
| Function | Description |
|---|
| scanf() | Formatted read from standard input. |
| scanf_l() | Formatted read from standard input, with locale. |
| sscanf() | Formatted read from string. |
| sscanf_l() | Formatted read from string, with locale. |
| vscanf() | Formatted read from standard input, variadic. |
| vscanf_l() | Formatted read from standard input, variadic, with locale. |
| vsscanf() | Formatted read from string, variadic. |
| vsscanf_l() | Formatted read from string, variadic, with local. |
| fscanf() | Formatted read from file. |
| fscanf_l() | Formatted read from file, with locale. |
| vfscanf() | Formatted read from file, variadic. |
| vfscanf_l() | Formatted read from file, variadic, with locale. |
scanf()
Description
Formatted read from standard input.
Prototype
int scanf(const char * format,
...);
Parameters
| Parameter | Description |
|---|
| format | Pointer to zero-terminated format control string. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input items
assigned, which can be fewer than provided for, or even zero, in the
event of an early matching failure.
Additional information
Reads input from standard input under control of the string pointed
to by format that specifies the admissible input sequences and how
they are to be converted for assignment, using subsequent arguments
as pointers to the objects to receive the converted input.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
Thread safety
Unsafe.
scanf_l()
Description
Formatted read from standard input, with locale.
Prototype
int scanf_l( locale_t loc,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input items
assigned, which can be fewer than provided for, or even zero, in the
event of an early matching failure.
Additional information
Reads input from standard input under control of the string pointed
to by format that specifies the admissible input sequences and how
they are to be converted for assignment, using subsequent arguments
as pointers to the objects to receive the converted input.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
Thread safety
Unsafe.
sscanf()
Description
Formatted read from string.
Prototype
int sscanf(const char * s,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| s | Pointer to string to read from. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input
items assigned, which can be fewer than provided for, or even
zero, in the event of an early matching failure.
Additional information
Reads input from the string s under control of the string pointed to
by format that specifies the admissible input sequences and how they
are to be converted for assignment, using subsequent arguments as
pointers to the objects to receive the converted input.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
Thread safety
Safe [if configured].
sscanf_l()
Description
Formatted read from string, with locale.
Prototype
int sscanf_l(const char * s,
locale_t loc,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| s | Pointer to string to read from. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input
items assigned, which can be fewer than provided for, or even
zero, in the event of an early matching failure.
Additional information
Reads input from the string s under control of the string pointed to
by format that specifies the admissible input sequences and how they
are to be converted for assignment, using subsequent arguments as
pointers to the objects to receive the converted input.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
Thread safety
Safe.
vscanf()
Description
Formatted read from standard input, variadic.
Prototype
int vscanf(const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input items
assigned, which can be fewer than provided for, or even zero, in the
event of an early matching failure.
Additional information
Reads input from the standard input stream under control of the
string pointed to by format that specifies the admissible input
sequences and how they are to be converted for assignment, using
subsequent arguments as pointers to the objects to receive the converted
input. Before calling vscanf(), arg must be initialized by the va_start()
macro (and possibly subsequent va_arg() calls). vscanf() does not invoke
the va_end() macro.
If there are insufficient arguments for the format, the behavior is
undefined.
Thread safety
Unsafe.
vscanf_l()
Description
Formatted read from standard input, variadic, with locale.
Prototype
int vscanf_l( locale_t loc,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input items
assigned, which can be fewer than provided for, or even zero, in the
event of an early matching failure.
Additional information
Reads input from the standard input stream under control of the
string pointed to by format that specifies the admissible input
sequences and how they are to be converted for assignment, using
subsequent arguments as pointers to the objects to receive the converted
input. Before calling vscanf(), arg must be initialized by the va_start()
macro (and possibly subsequent va_arg() calls). vscanf() does not invoke
the va_end() macro.
If there are insufficient arguments for the format, the behavior is
undefined.
Thread safety
Unsafe.
vsscanf()
Description
Formatted read from string, variadic.
Prototype
int vsscanf(const char * s,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| s | Pointer to string to read from. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input
items assigned, which can be fewer than provided for, or even
zero, in the event of an early matching failure.
Additional information
Reads input from the standard input stream under control of
the string pointed to by format that specifies the admissible
input sequences and how they are to be converted for assignment,
using subsequent arguments as pointers to the objects to receive
the converted input. Before calling vsscanf(), arg must be
initialized by the va_start() macro (and possibly subsequent
va_arg() calls). vsscanf() does not invoke the va_end() macro.
If there are insufficient arguments for the format, the behavior
is undefined.
Thread safety
Safe [if configured].
vsscanf_l()
Description
Formatted read from string, variadic, with local.
Prototype
int vsscanf_l(const char * s,
locale_t loc,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| s | Pointer to string to read from. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input
items assigned, which can be fewer than provided for, or even
zero, in the event of an early matching failure.
Additional information
Reads input from the standard input stream under control of
the string pointed to by format that specifies the admissible
input sequences and how they are to be converted for assignment,
using subsequent arguments as pointers to the objects to receive
the converted input. Before calling vsscanf(), arg must be
initialized by the va_start() macro (and possibly subsequent
va_arg() calls). vsscanf() does not invoke the va_end() macro.
If there are insufficient arguments for the format, the behavior
is undefined.
Thread safety
Safe [if configured].
fscanf()
Description
Formatted read from file.
Prototype
int fscanf( FILE * stream,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file to read from. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input items
assigned, which can be fewer than provided for, or even zero, in the
event of an early matching failure.
Additional information
Reads input from the file stream under control of the string pointed
to by format that specifies the admissible input sequences and how
they are to be converted for assignment, using subsequent arguments
as pointers to the objects to receive the converted input.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
Thread safety
Unsafe.
fscanf_l()
Description
Formatted read from file, with locale.
Prototype
int fscanf_l( FILE * stream,
locale_t loc,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file to read from. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input items
assigned, which can be fewer than provided for, or even zero, in the
event of an early matching failure.
Additional information
Reads input from the file stream under control of the string pointed
to by format that specifies the admissible input sequences and how
they are to be converted for assignment, using subsequent arguments
as pointers to the objects to receive the converted input.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
Thread safety
Unsafe.
vfscanf()
Description
Formatted read from file, variadic.
Prototype
int vfscanf( FILE * stream,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file to read from. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input items
assigned, which can be fewer than provided for, or even zero, in the
event of an early matching failure.
Additional information
Reads input from the file stream under control of the string pointed
to by format that specifies the admissible input sequences and how
they are to be converted for assignment, using subsequent arguments
as pointers to the objects to receive the converted input.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
Thread safety
Unsafe.
vfscanf_l()
Description
Formatted read from file, variadic, with locale.
Prototype
int vfscanf_l( FILE * stream,
locale_t loc,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file to read from. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, returns the number of input items
assigned, which can be fewer than provided for, or even zero, in the
event of an early matching failure.
Additional information
Reads input from the file stream under control of the string pointed
to by format that specifies the admissible input sequences and how
they are to be converted for assignment, using subsequent arguments
as pointers to the objects to receive the converted input.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
Thread safety
Unsafe.
| Function | Description |
|---|
| printf() | Formatted write to standard output. |
| printf_l() | Formatted write to standard output, with locale. |
| sprintf() | Formatted write to string. |
| sprintf_l() | Formatted write to string, with locale. |
| snprintf() | Formatted write to string, limit length. |
| snprintf_l() | Formatted write to string, limit length, with locale. |
| vprintf() | Formatted write to standard output, variadic. |
| vprintf_l() | Formatted write to standard output, variadic, with locale. |
| vsprintf() | Formatted write to string, variadic. |
| vsprintf_l() | Formatted write to string, variadic, with locale. |
| vsnprintf() | Formatted write to string, limit length, variadic. |
| vsnprintf_l() | Formatted write to string, limit length, variadic, with locale. |
| fprintf() | Formatted write to file. |
| fprintf_l() | Formatted write to file, with locale. |
| vfprintf() | Formatted write to file, variadic. |
| vfprintf_l() | Formatted write to file, variadic, with locale. |
| asprintf() | Print to newly allocated string. |
| asprintf_l() | Print to newly allocated string, with locale. |
| vasprintf() | Print to newly allocated string, variadic. |
| vasprintf_l() | Print to newly allocated string, variadic, with locale. |
printf()
Description
Formatted write to standard output.
Prototype
int printf(const char * format,
...);
Parameters
| Parameter | Description |
|---|
| format | Pointer to zero-terminated format control string. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to the standard output stream under control of the string
pointed to by format that specifies how subsequent arguments are
converted for output.
If there are insufficient arguments for the format, the behavior
is undefined. If the format is exhausted while arguments remain,
the excess arguments are evaluated but are otherwise ignored.
Thread safety
Unsafe.
printf_l()
Description
Formatted write to standard output, with locale.
Prototype
int printf_l( locale_t loc,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to the standard output stream under control of the string
pointed to by format that specifies how subsequent arguments are
converted for output.
If there are insufficient arguments for the format, the behavior
is undefined. If the format is exhausted while arguments remain,
the excess arguments are evaluated but are otherwise ignored.
Thread safety
Unsafe.
sprintf()
Description
Formatted write to string.
Prototype
int sprintf( char * s,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the formatted output. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns number of characters written to s (not counting the
terminating null), or a negative value if an output or encoding
error occurred.
Additional information
Writes to the string pointed to by s under control of the
string pointed to by format that specifies how subsequent
arguments are converted for output. A null character is
written at the end of the characters written; it is not
counted as part of the returned value.
If there are insufficient arguments for the format, the
behavior is undefined. If the format is exhausted while
arguments remain, the excess arguments are evaluated but are
otherwise ignored.
If copying takes place between objects that overlap, the
behavior is undefined.
Thread safety
Safe [if configured].
sprintf_l()
Description
Formatted write to string, with locale.
Prototype
int sprintf_l( char * s,
locale_t loc,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the formatted output. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns number of characters written to s (not counting the
terminating null), or a negative value if an output or encoding
error occurred.
Additional information
Writes to the string pointed to by s under control of the
string pointed to by format that specifies how subsequent
arguments are converted for output. A null character is
written at the end of the characters written; it is not
counted as part of the returned value.
If there are insufficient arguments for the format, the
behavior is undefined. If the format is exhausted while
arguments remain, the excess arguments are evaluated but are
otherwise ignored.
If copying takes place between objects that overlap, the
behavior is undefined.
Thread safety
Safe.
snprintf()
Description
Formatted write to string, limit length.
Prototype
int snprintf( char * s,
size_t n,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the formatted output. |
| n | Maximum number of characters to write to the array pointed to by s. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the number of characters that would have been written
had n been sufficiently large, not counting the terminating
null character, or a negative value if an encoding error occurred. Thus, the
null-terminated output has been completely written if and only if the returned
value is nonnegative and less than n.
Additional information
Writes to the string pointed to by s under control
of the string pointed to by format that specifies how subsequent arguments
are converted for output.
If n is zero, nothing is written, and s can
be a null pointer. Otherwise, output characters beyond count n-1
are discarded rather than being written to the array, and a null character is
written at the end of the characters actually written into the array. A null
character is written at the end of the conversion; it is not counted as part
of the returned value.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
If copying takes place between objects that overlap, the behavior is undefined.
Thread safety
Safe [if configured].
snprintf_l()
Description
Formatted write to string, limit length, with locale.
Prototype
int snprintf_l( char * s,
size_t n,
locale_t loc,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the formatted output. |
| n | Maximum number of characters to write to the array pointed to by s. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the number of characters that would have been written
had n been sufficiently large, not counting the terminating
null character, or a negative value if an encoding error occurred. Thus, the
null-terminated output has been completely written if and only if the returned
value is nonnegative and less than n.
Additional information
Writes to the string pointed to by s under control
of the string pointed to by format that specifies how subsequent arguments
are converted for output.
If n is zero, nothing is written, and s can
be a null pointer. Otherwise, output characters beyond count n-1
are discarded rather than being written to the array, and a null character is
written at the end of the characters actually written into the array. A null
character is written at the end of the conversion; it is not counted as part
of the returned value.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
If copying takes place between objects that overlap, the behavior is undefined.
Thread safety
Safe.
vprintf()
Description
Formatted write to standard output, variadic.
Prototype
int vprintf(const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to the standard output stream using under control of
the string pointed to by format that specifies how subsequent
arguments are converted for output. Before calling vprintf(),
arg must be initialized by the va_start macro (and possibly
subsequent va_arg calls). vprintf() does not invoke the
va_end macro.
Thread safety
Unsafe.
vprintf_l()
Description
Formatted write to standard output, variadic, with locale.
Prototype
int vprintf_l( locale_t loc,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to the standard output stream using under control of
the string pointed to by format that specifies how subsequent
arguments are converted for output. Before calling vprintf(),
arg must be initialized by the va_start macro (and possibly
subsequent va_arg calls). vprintf() does not invoke the
va_end macro.
Thread safety
Unsafe.
vsprintf()
Description
Formatted write to string, variadic.
Prototype
int vsprintf( char * s,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the formatted output. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns number of characters written to s (not counting the
terminating null), or a negative value if an output or encoding
error occurred.
Additional information
Writes to the string pointed to by s under control of the string
pointed to by format that specifies how subsequent arguments are
converted for output. A null character is written at the end of
the characters written; it is not counted as part of the returned
value.
Before calling vsprintf(), arg must be initialized by the va_start macro
(and possibly subsequent va_arg calls). vsprintf() does not invoke the
va_end macro.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
If copying takes place between objects that overlap, the behavior is undefined.
Notes
This is equivalent to sprintf() with the variable argument list replaced by arg.
Thread safety
Safe [if configured].
vsprintf_l()
Description
Formatted write to string, variadic, with locale.
Prototype
int vsprintf_l( char * s,
locale_t loc,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the formatted output. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns number of characters written to s (not counting the
terminating null), or a negative value if an output or encoding
error occurred.
Additional information
Writes to the string pointed to by s under control of the string
pointed to by format that specifies how subsequent arguments are
converted for output. A null character is written at the end of
the characters written; it is not counted as part of the returned
value.
Before calling vsprintf(), arg must be initialized by the va_start macro
(and possibly subsequent va_arg calls). vsprintf() does not invoke the
va_end macro.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
If copying takes place between objects that overlap, the behavior is undefined.
Notes
This is equivalent to sprintf() with the variable argument list replaced by arg.
Thread safety
Safe.
vsnprintf()
Description
Formatted write to string, limit length, variadic.
Prototype
int vsnprintf( char * s,
size_t n,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the formatted output. |
| n | Maximum number of characters to write to the array pointed to by s. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the number of characters that would have been written
had n been sufficiently large, not counting the terminating
null character, or a negative value if an encoding error occurred.
Thus, the null-terminated output has been completely written
if and only if the returned value is nonnegative and less than n.
Additional information
Writes to the string pointed to by s under control
of the string pointed to by format that specifies how subsequent arguments
are converted for output. Before calling vsnprintf(), arg must
be initialized by the va_start macro (and possibly subsequent va_arg() calls).
vsnprintf() does not invoke the va_end macro.
If n is zero, nothing is written, and s can
be a null pointer. Otherwise, output characters beyond count n-1
are discarded rather than being written to the array, and a null character is
written at the end of the characters actually written into the array. A null
character is written at the end of the conversion; it is not counted as part
of the returned value.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
If copying takes place between objects that overlap, the behavior is undefined.
Notes
This is equivalent to snprintf() with the variable argument list replaced
by arg.
Thread safety
Safe [if configured].
vsnprintf_l()
Description
Formatted write to string, limit length, variadic, with locale.
Prototype
int vsnprintf_l( char * s,
size_t n,
locale_t loc,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the formatted output. |
| n | Maximum number of characters to write to the array pointed to by s. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the number of characters that would have been written
had n been sufficiently large, not counting the terminating
null character, or a negative value if an encoding error occurred.
Thus, the null-terminated output has been completely written
if and only if the returned value is nonnegative and less than n.
Additional information
Writes to the string pointed to by s under control
of the string pointed to by format that specifies how subsequent arguments
are converted for output. Before calling vsnprintf(), arg must
be initialized by the va_start macro (and possibly subsequent va_arg() calls).
vsnprintf() does not invoke the va_end macro.
If n is zero, nothing is written, and s can
be a null pointer. Otherwise, output characters beyond count n-1
are discarded rather than being written to the array, and a null character is
written at the end of the characters actually written into the array. A null
character is written at the end of the conversion; it is not counted as part
of the returned value.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
If copying takes place between objects that overlap, the behavior is undefined.
Notes
This is equivalent to snprintf() with the variable argument list replaced
by arg.
Thread safety
Safe.
fprintf()
Description
Formatted write to file.
Prototype
int fprintf( FILE * stream,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file to write to. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to the file stream under control of the string pointed
to by format that specifies how subsequent arguments are
converted for output.
If there are insufficient arguments for the format, the behavior
is undefined. If the format is exhausted while arguments remain,
the excess arguments are evaluated but are otherwise ignored.
Thread safety
Unsafe.
fprintf_l()
Description
Formatted write to file, with locale.
Prototype
int fprintf_l( FILE * stream,
locale_t loc,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file to write to. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to the file stream under control of the string pointed
to by format that specifies how subsequent arguments are
converted for output.
If there are insufficient arguments for the format, the behavior
is undefined. If the format is exhausted while arguments remain,
the excess arguments are evaluated but are otherwise ignored.
Thread safety
Unsafe.
vfprintf()
Description
Formatted write to file, variadic.
Prototype
int vfprintf( FILE * stream,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file to write to. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to the file stream using under control of the string
pointed to by format that specifies how subsequent arguments
are converted for output. Before calling vfprintf(),
arg must be initialized by the va_start macro (and possibly
subsequent va_arg calls). vfprintf() does not invoke the
va_end macro.
Thread safety
Unsafe.
vfprintf_l()
Description
Formatted write to file, variadic, with locale.
Prototype
int vfprintf_l( FILE * stream,
locale_t loc,
const char * format,
va_list arg);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file to write to. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
| arg | Variable parameter list. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to the file stream using under control of the string
pointed to by format that specifies how subsequent arguments
are converted for output. Before calling vfprintf(),
arg must be initialized by the va_start macro (and possibly
subsequent va_arg calls). vfprintf() does not invoke the
va_end macro.
Thread safety
Unsafe.
asprintf()
Description
Print to newly allocated string.
Prototype
int asprintf( char ** strp,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| strp | Pointer to object that receives the pointer to the output string. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to a newly allocated string, using malloc() and realloc()
if necessary, under control of the string pointed to by format that
specifies how subsequent arguments are converted for output.
The pointer to the newly allocated stirng is assigned to the object
pointed to by strp. It is the client’s responsibility to free this
pointer.
If there are insufficient arguments for the format, the behavior
is undefined. If the format is exhausted while arguments remain,
the excess arguments are evaluated but are otherwise ignored.
Notes
Commonly found in Linux, BSD, and GNU C libraries.
Thread safety
Safe [if configured].
asprintf_l()
Description
Print to newly allocated string, with locale.
Prototype
int asprintf_l( char ** strp,
locale_t loc,
const char * format,
...);
Parameters
| Parameter | Description |
|---|
| strp | Pointer to object that receives the pointer to the output string. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to a newly allocated string, using malloc() and realloc()
if necessary, under control of the string pointed to by format that
specifies how subsequent arguments are converted for output.
The pointer to the newly allocated stirng is assigned to the object
pointed to by strp. It is the client’s responsibility to free this
pointer.
If there are insufficient arguments for the format, the behavior
is undefined. If the format is exhausted while arguments remain,
the excess arguments are evaluated but are otherwise ignored.
Notes
Commonly found in Linux, BSD, and GNU C libraries.
Thread safety
Safe.
vasprintf()
Description
Print to newly allocated string, variadic.
Prototype
int vasprintf( char ** strp,
const char * format,
va_list ap);
Parameters
| Parameter | Description |
|---|
| strp | Pointer to object that receives the pointer to the output string. |
| format | Pointer to zero-terminated format control string. |
| ap | Variadic argument list. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to a newly allocated string, using malloc() and realloc()
if necessary, under control of the string pointed to by format that
specifies how subsequent arguments are converted for output.
The pointer to the newly allocated stirng is assigned to the object
pointed to by strp. It is the client’s responsibility to free this
pointer.
If there are insufficient arguments for the format, the behavior
is undefined. If the format is exhausted while arguments remain,
the excess arguments are evaluated but are otherwise ignored.
Notes
Commonly found in Linux, BSD, and GNU C libraries.
Thread safety
Safe [if configured].
vasprintf_l()
Description
Print to newly allocated string, variadic, with locale.
Prototype
int vasprintf_l( char ** strp,
locale_t loc,
const char * format,
va_list ap);
Parameters
| Parameter | Description |
|---|
| strp | Pointer to object that receives the pointer to the output string. |
| loc | Locale to use for conversion. |
| format | Pointer to zero-terminated format control string. |
| ap | Variadic argument list. |
Return value
Returns the number of characters written, or a negative value
if an output or encoding error occurred.
Additional information
Writes to a newly allocated string, using malloc() and realloc()
if necessary, under control of the string pointed to by format that
specifies how subsequent arguments are converted for output.
The pointer to the newly allocated stirng is assigned to the object
pointed to by strp. It is the client’s responsibility to free this
pointer.
If there are insufficient arguments for the format, the behavior
is undefined. If the format is exhausted while arguments remain,
the excess arguments are evaluated but are otherwise ignored.
Notes
Commonly found in Linux, BSD, and GNU C libraries.
Thread safety
Safe.
Miscellaneous functions
| Function | Description |
|---|
| perror() | Print error message to standard error stream. |
perror()
Description
Print error message to standard error stream.
Prototype
void perror(const char * s);
Parameters
| Parameter | Description |
|---|
| s | Pointer to string to prefix error with. May be NULL. |
Thread safety
Unsafe.
<stdlib.h>
Process control functions
| Function | Description |
|---|
| atexit() | Set function to be called on exit. |
| abort() | Abort execution. |
atexit()
Description
Set function to be called on exit.
Prototype
int atexit(__SEGGER_RTL_exit_func fn);
Parameters
| Parameter | Description |
|---|
| fn | Function to register. |
Return value
| = 0 | Success registering function. |
| ≠ 0 | Did not register function. |
Additional information
Registers function fn to be called when the application has
exited. The functions registered with atexit() are executed
in reverse order of their registration.
Thread safety
Unsafe.
abort()
Description
Abort execution.
Prototype
void abort(void);
Additional information
Calls exit() with the exit status EXIT_FAILURE.
Thread safety
Not applicable.
Runtime constraint functions
abort_handler_s()
Description
Abort on runtime constraint violation (C11).
Prototype
void abort_handler_s(const char * msg,
void * ptr,
errno_t error);
Parameters
| Parameter | Description |
|---|
| msg | Pointer to a null-terminated character string describing the constraint violation. |
| ptr | A null pointer or a pointer to an implementation-defined object. This implementation always passes NULL. |
| error | If the function calling the handler has a return type declared as errno_t, the return value of the function is passed. Otherwise, a positive value of type errno_t is passed. |
Additional information
The macro __STDC_WANT_LIB_EXT1__ must be set to 1 before
including <stdlib.h> to access this function.
Conformance
ISO/IEC 9899:2011 (C11).
Thread safety
Not applicable.
ignore_handler_s()
Description
Ignore runtime constraint violations (C11).
Prototype
void ignore_handler_s(const char * msg,
void * ptr,
errno_t error);
Parameters
| Parameter | Description |
|---|
| msg | Pointer to a null-terminated character string describing the constraint violation. |
| ptr | A null pointer or a pointer to an implementation-defined object. This implementation always passes NULL. |
| error | If the function calling the handler has a return type declared as errno_t, the return value of the function is passed. Otherwise, a positive value of type errno_t is passed. |
Additional information
The macro __STDC_WANT_LIB_EXT1__ must be set to 1 before
including <stdlib.h> to access this function.
Conformance
ISO/IEC 9899:2011 (C11).
Thread safety
Safe.
set_constraint_handler_s()
Description
Set runtime constraint handler (C11).
Prototype
constraint_handler_t set_constraint_handler_s(constraint_handler_t handler);
Parameters
| Parameter | Description |
|---|
| handler | Pointer to function that will handle runtime constraint violations. If NULL, the implementation-default abort handler is used. |
Return value
The previously-set constraint handler. If the previous handler was
registered by calling set_constraint_handler() with a null pointer
argument, a pointer to the implementation-default handler is returned
(not NULL).
Additional information
The macro __STDC_WANT_LIB_EXT1__ must be set to 1 before
including <stdlib.h> to access this function.
Conformance
ISO/IEC 9899:2011 (C11).
Thread safety
Unsafe.
Integer arithmetic functions
| Function | Description |
|---|
| abs() | Calculate absolute value, int. |
| labs() | Calculate absolute value, long. |
| llabs() | Calculate absolute value, long long. |
| div() | Divide returning quotient and remainder, int. |
| ldiv() | Divide returning quotient and remainder, long. |
| lldiv() | Divide returning quotient and remainder, long long. |
abs()
Description
Calculate absolute value, int.
Prototype
int abs(int Value);
Parameters
| Parameter | Description |
|---|
| Value | Integer value. |
Return value
The absolute value of the integer argument Value.
Thread safety
Safe.
labs()
Description
Calculate absolute value, long.
Prototype
long int labs(long int Value);
Parameters
| Parameter | Description |
|---|
| Value | Long integer value. |
Return value
The absolute value of the long integer argument Value.
Thread safety
Safe.
llabs()
Description
Calculate absolute value, long long.
Prototype
long long int llabs(long long int Value);
Parameters
| Parameter | Description |
|---|
| Value | Long long integer value. |
Return value
The absolute value of the long long integer argument Value.
Thread safety
Safe.
div()
Description
Divide returning quotient and remainder, int.
Prototype
div_t div(int Numer,
int Denom);
Parameters
| Parameter | Description |
|---|
| Numer | Numerator. |
| Denom | Demoninator. |
Return value
Returns a structure of type div_t comprising both the
quotient and the remainder. The structures contain the members
quot (the quotient) and rem (the remainder), each of which has
the same type as the arguments Numer and Denom. If either part
of the result cannot be represented, the behavior is undefined.
Additional information
This computes Numer divided by Denom and Numer modulo Denom
in a single operation.
Thread safety
Safe.
See also
div_t
ldiv()
Description
Divide returning quotient and remainder, long.
Prototype
ldiv_t ldiv(long Numer,
long Denom);
Parameters
| Parameter | Description |
|---|
| Numer | Numerator. |
| Denom | Demoninator. |
Return value
Returns a structure of type ldiv_t comprising both the
quotient and the remainder. The structures contain the members
quot (the quotient) and rem (the remainder), each of which has
the same type as the arguments Numer and Denom. If either part
of the result cannot be represented, the behavior is undefined.
Additional information
This computes Numer divided by Denom and Numer modulo Denom
in a single operation.
Thread safety
Safe.
See also
ldiv_t
lldiv()
Description
Divide returning quotient and remainder, long long.
Prototype
lldiv_t lldiv(long long Numer,
long long Denom);
Parameters
| Parameter | Description |
|---|
| Numer | Numerator. |
| Denom | Demoninator. |
Return value
Returns a structure of type lldiv_t comprising both the
quotient and the remainder. The structures contain the members
quot (the quotient) and rem (the remainder), each of which has
the same type as the arguments Numer and Denom. If either part
of the result cannot be represented, the behavior is undefined.
Additional information
This computes Numer divided by Denom and Numer modulo Denom
in a single operation.
Thread safety
Safe.
See also
lldiv_t
Pseudo-random sequence generation functions
| Function | Description |
|---|
| rand() | Return next random number in sequence. |
| srand() | Set seed of random number sequence. |
rand()
Description
Return next random number in sequence.
Prototype
int rand(void);
Return value
Returns the computed pseudo-random integer.
Additional information
This computes a sequence of pseudo-random integers in the
range 0 to RAND_MAX.
Thread safety
Safe [if configured].
See also
srand()
srand()
Description
Set seed of random number sequence.
Prototype
void srand(unsigned s);
Parameters
| Parameter | Description |
|---|
| s | New seed value for pseudo-random sequence. |
Additional information
This uses the argument Seed as a seed for a new sequence of
pseudo-random numbers to be returned by subsequent calls to rand().
If srand() is called with the same seed value, the same sequence
of pseudo-random numbers is generated.
If rand() is called before any calls to srand() have been made, a
sequence is generated as if srand() is first called with a seed
value of 1.
Thread safety
Safe [if configured].
See also
rand()
Memory allocation functions
| Function | Description |
|---|
| malloc() | Allocate space for single object. |
| aligned_alloc() | Allocate space for aligned single object. |
| calloc() | Allocate space for multiple objects and zero them. |
| realloc() | Resize or allocate memory space. |
| free() | Free allocated memory for reuse. |
malloc()
Description
Allocate space for single object.
Prototype
void *malloc(size_t sz);
Parameters
| Parameter | Description |
|---|
| sz | Number of characters to allocate for the object. |
Return value
Returns a null pointer if the space for the object cannot be
allocated from free memory; if space for the object can be allocated,
malloc() returns a pointer to the start of the allocated space.
Additional information
Allocates space for an object whose size is specified by sz
and whose value is indeterminate.
Thread safety
Safe [if configured].
aligned_alloc()
Description
Allocate space for aligned single object.
Prototype
void *aligned_alloc(size_t align,
size_t sz);
Parameters
| Parameter | Description |
|---|
| align | Alignment of object. |
| sz | Number of characters to allocate for the object. |
Return value
Returns a null pointer if the space for the object cannot be
allocated from free memory or the alignment cannot be satisfied;
if space for the object can be allocated, aligned_alloc() returns
a pointer to the start of the allocated, aligned space.
Additional information
Allocates space for an object whose size is specified by sz,
whose alignment is align, and whose value is indeterminate.
Thread safety
Safe [if configured].
calloc()
Description
Allocate space for multiple objects and zero them.
Prototype
void *calloc(size_t nobj,
size_t sz);
Parameters
| Parameter | Description |
|---|
| nobj | Number of objects to allocate. |
| sz | Number of characters to allocate per object. |
Return value
Returns a null pointer if the space for the object cannot be
allocated from free memory; if space for the object can be allocated,
calloc() returns a pointer to the start of the allocated space.
Additional information
Allocates space for an array of nobj objects, each of
whose size is sz. The space is initialized to all zero
bits.
Thread safety
Safe [if configured].
realloc()
Description
Resize or allocate memory space.
Prototype
void *realloc(void * ptr,
size_t sz);
Parameters
| Parameter | Description |
|---|
| ptr | Pointer to resize, or NULL to allocate. |
| sz | New size of object. |
Return value
Returns a pointer to the new object (which may have the same
value as a pointer to the old object), or a null pointer if
the new object could not be allocated.
Additional information
Deallocates the old object pointed to by ptr and returns a
pointer to a new object that has the size specified by sz.
The contents of the new object is identical to that of the
old object prior to deallocation, up to the lesser of the
new and old sizes. Any bytes in the new object beyond the
size of the old object have indeterminate values.
If ptr is a null pointer, realloc() behaves like malloc()
for the specified size. If memory for the new object cannot
be allocated, the old object is not deallocated and its value
is unchanged.
If ptr does not match a pointer earlier returned by calloc(),
malloc(), or realloc(), or if the space has been deallocated
by a call to free() or realloc(), the behavior is undefined.
Thread safety
Safe [if configured].
free()
Description
Free allocated memory for reuse.
Prototype
void free(void * ptr);
Parameters
| Parameter | Description |
|---|
| ptr | Pointer to object to free. |
Additional information
Causes the space pointed to by ptr to be deallocated, that
is, made available for further allocation. If ptr is a null
pointer, no action occurs.
If ptr does not match a pointer earlier returned by calloc(),
malloc(), or realloc(), or if the space has been deallocated
by a call to free() or realloc(), the behavior is undefined.
Thread safety
Safe [if configured].
Search and sort functions
qsort()
Description
Sort array.
Prototype
void qsort(void * base,
size_t nmemb,
size_t sz,
int ( *compare)(const void * elem1 , const void * elem2 ));
Parameters
| Parameter | Description |
|---|
| base | Pointer to the start of the array. |
| nmemb | Number of array elements. |
| sz | Number of characters per array element. |
| compare | Pointer to element comparison function. |
Additional information
Sorts the array pointed to by base using the compare function. The
array should have nmemb elements of sz bytes. The compare function
should return a negative value if the first parameter is less than
the second parameter, zero if the parameters are equal, and a
positive value if the first parameter is greater than the second
parameter.
Thread safety
Safe.
bsearch()
Description
Search sorted array.
Prototype
void *bsearch
(const void * key,
const void * base,
size_t nmemb,
size_t sz,
int ( *compare)(const void * elem1 , const void * elem2 ));
Parameters
| Parameter | Description |
|---|
| key | Pointer to object to search for. |
| base | Pointer to the start of the array. |
| nmemb | Number of array elements. |
| sz | Number of characters per array element. |
| compare | Pointer to element comparison function. |
Return value
| = NULL | Key not found. |
| ≠ NULL | Pointer to found object. |
Additional information
Searches the array pointed to by base for the specified key
and returns a pointer to the first entry that matches, or null
if no match. The array should have nmemb elements of sz bytes
and be sorted by the same algorithm as the compare function.
The compare function should return a negative value if the
first parameter is less than second parameter, zero if the
parameters are equal, and a positive value if the first parameter
is greater than the second parameter.
Thread safety
Safe.
Number to string conversions
| Function | Description |
|---|
| itoa() | Convert to string, int. |
| ltoa() | Convert to string, long. |
| lltoa() | Convert to string, long long. |
| utoa() | Convert to string, unsigned. |
| ultoa() | Convert to string, unsigned long. |
| ulltoa() | Convert to string, unsigned long long. |
itoa()
Description
Convert to string, int.
Prototype
char *itoa(int val,
char * buf,
int radix);
Parameters
| Parameter | Description |
|---|
| val | Value to convert. |
| buf | Pointer to array of characters that receives the string. |
| radix | Number base to use for conversion, 2 to 36. |
Return value
Returns buf.
Additional information
Converts val to a string in base radix and places the result in
buf which must be large enough to hold the output. If radix is
greater than 36, the result is undefined.
If val is negative and radix is 10, the string has a leading
minus sign (-); for all other values of radix, value is considered
unsigned and never has a leading minus sign.
Notes
This is a non-standard function. Even though this function is
commonly used by compilers on other platforms, there is no
guarantee that this function will behave the same on all
platforms, in all cases.
Thread safety
Safe.
See also
ltoa(), lltoa(), utoa(), ultoa(), ulltoa()
ltoa()
Description
Convert to string, long.
Prototype
char *ltoa(long val,
char * buf,
int radix);
Parameters
| Parameter | Description |
|---|
| val | Value to convert. |
| buf | Pointer to array of characters that receives the string. |
| radix | Number base to use for conversion, 2 to 36. |
Return value
Returns buf.
Additional information
Converts val to a string in base radix and places the result in
buf which must be large enough to hold the output. If radix is
greater than 36, the result is undefined.
If val is negative and radix is 10, the string has a leading
minus sign (-); for all other values of radix, value is considered
unsigned and never has a leading minus sign.
Notes
This is a non-standard function. Even though this function is
commonly used by compilers on other platforms, there is no
guarantee that this function will behave the same on all
platforms, in all cases.
Thread safety
Safe.
See also
itoa(), lltoa(), utoa(), ultoa(), ulltoa()
lltoa()
Description
Convert to string, long long.
Prototype
char *lltoa(long long val,
char * buf,
int radix);
Parameters
| Parameter | Description |
|---|
| val | Value to convert. |
| buf | Pointer to array of characters that receives the string. |
| radix | Number base to use for conversion, 2 to 36. |
Return value
Returns buf.
Additional information
Converts val to a string in base radix and places the result in
buf which must be large enough to hold the output. If radix is
greater than 36, the result is undefined.
If val is negative and radix is 10, the string has a leading
minus sign (-); for all other values of radix, value is considered
unsigned and never has a leading minus sign.
Notes
This is a non-standard function. Even though this function is
commonly used by compilers on other platforms, there is no
guarantee that this function will behave the same on all
platforms, in all cases.
Thread safety
Safe.
See also
itoa(), ltoa(), utoa(), ultoa(), ulltoa()
utoa()
Description
Convert to string, unsigned.
Prototype
char *utoa(unsigned val,
char * buf,
int radix);
Parameters
| Parameter | Description |
|---|
| val | Value to convert. |
| buf | Pointer to array of characters that receives the string. |
| radix | Number base to use for conversion, 2 to 36. |
Return value
Returns buf.
Additional information
Converts val to a string in base radix and places the result in
buf which must be large enough to hold the output. If radix is
greater than 36, the result is undefined.
Notes
This is a non-standard function. Even though this function is
commonly used by compilers on other platforms, there is no
guarantee that this function will behave the same on all
platforms, in all cases.
Thread safety
Safe.
See also
itoa(), ltoa(), lltoa(), ultoa(), ulltoa()
ultoa()
Description
Convert to string, unsigned long.
Prototype
char *ultoa(unsigned long val,
char * buf,
int radix);
Parameters
| Parameter | Description |
|---|
| val | Value to convert. |
| buf | Pointer to array of characters that receives the string. |
| radix | Number base to use for conversion, 2 to 36. |
Return value
Returns buf.
Additional information
Converts val to a string in base radix and places the result in
buf which must be large enough to hold the output. If radix is
greater than 36, the result is undefined.
Notes
This is a non-standard function. Even though this function is
commonly used by compilers on other platforms, there is no
guarantee that this function will behave the same on all
platforms, in all cases.
Thread safety
Safe.
See also
itoa(), ltoa(), lltoa(), ulltoa(), utoa()
ulltoa()
Description
Convert to string, unsigned long long.
Prototype
char *ulltoa(unsigned long long val,
char * buf,
int radix);
Parameters
| Parameter | Description |
|---|
| val | Value to convert. |
| buf | Pointer to array of characters that receives the string. |
| radix | Number base to use for conversion, 2 to 36. |
Return value
Returns buf.
Additional information
Converts val to a string in base radix and places the result in
buf which must be large enough to hold the output. If radix is
greater than 36, the result is undefined.
Notes
This is a non-standard function. Even though this function is
commonly used by compilers on other platforms, there is no
guarantee that this function will behave the same on all
platforms, in all cases.
Thread safety
Safe.
See also
itoa(), ltoa(), lltoa(), ultoa(), utoa()
String to number conversions
| Function | Description |
|---|
| atoi() | Convert to number, int. |
| atol() | Convert to number, long. |
| atoll() | Convert to number, long long. |
| atof() | Convert to number, double. |
| strtol() | Convert to number, long. |
| strtoll() | Convert to number, long long. |
| strtoul() | Convert to number, unsigned long. |
| strtoull() | Convert to number, unsigned long long. |
| strtof() | Convert to number, float. |
| strtod() | Convert to number, double. |
| strtold() | Convert to number, long double. |
| wcstol() | Convert to number, long. |
| wcstoll() | Convert to number, long long. |
| wcstoul() | Convert to number, unsigned long. |
| wcstoull() | Convert to number, unsigned long long. |
| wcstof() | Convert to number, float. |
| wcstod() | Convert to number, double. |
| wcstold() | Convert to number, long double. |
atoi()
Description
Convert to number, int.
Prototype
int atoi(const char * nptr);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
Return value
Returns the converted value, if any. If the value of the
result cannot be represented, the behavior is undefined.
Additional information
Converts the initial portion of the string pointed to by nptr
to an int representation.
atoi() does not affect the value of errno on an error.
Notes
Except for the behavior on error, atoi() is equivalent to
(int)strtol(nptr, NULL, 10).
Thread safety
Safe.
See also
strtol()
atol()
Description
Convert to number, long.
Prototype
long int atol(const char * nptr);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
Return value
Returns the converted value, if any. If the value of the
result cannot be represented, the behavior is undefined.
Additional information
Converts the initial portion of the string pointed to by nptr
to a long representation.
atol() does not affect the value of errno on an error.
Notes
Except for the behavior on error, atol() is equivalent to
strtol(nptr, NULL, 10).
Thread safety
Safe.
See also
strtol()
atoll()
Description
Convert to number, long long.
Prototype
long long int atoll(const char * nptr);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
Return value
Returns the converted value, if any. If the value of the
result cannot be represented, the behavior is undefined.
Additional information
Converts the initial portion of the string pointed to by nptr
to a long-long representation.
atoll() does not affect the value of errno on an error.
Notes
Except for the behavior on error, atoll() is equivalent to
strtoll(nptr, NULL, 10).
Thread safety
Safe.
See also
strtoll()
atof()
Description
Convert to number, double.
Prototype
double atof(const char * nptr);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
Return value
Returns the converted value, if any. If the value of the
result cannot be represented, the behavior is undefined.
Additional information
Converts the initial portion of the string pointed to by nptr
to an double representation.
atof() does not affect the value of errno on an error.
Notes
Except for the behavior on error, atof() is equivalent to
(int)strtod(nptr, NULL).
Thread safety
Safe.
See also
strtod()
strtol()
Description
Convert to number, long.
Prototype
long strtol(const char * nptr,
char ** endptr,
int base);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
| base | Radix to use for conversion, 2 to 36. |
Return value
Returns the converted value, if any. If no conversion could be
performed, zero is returned. If the correct value is outside
the range of representable values, LONG_MIN or LONG_MAX is
returned according to the sign of the value, if any, and the
value of the macro ERANGE is stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to a long representation.
First, strtol() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling an integer represented in some radix determined
by the value of base, and a final string of one or more unrecognized
characters, including the terminating null character of the input string.
strtol() then attempts to convert the subject sequence to an integer, and
return the result.
When converting, no integer suffix (such as U, L, UL, LL, ULL) is allowed.
If the value of base is zero, the expected form of the subject sequence
is an optional plus or minus sign followed by an integer constant.
If the value of base is between 2 and 36 (inclusive), the expected form
of the subject sequence is an optional plus or minus sign followed by a sequence
of letters and digits representing an integer with the radix specified by base.
The letters from a (or A) through z (or Z) represent the values 10 through 35;
only letters and digits whose ascribed values are less than that of base
are permitted.
If the value of base is 16, the characters “0x” or “0X” may optionally
precede the sequence of letters and digits, following the optional sign.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
If the subject sequence has the expected form and the value of base
is zero, the sequence of characters starting with the first digit is interpreted
as an integer constant. If the subject sequence has the expected form and the
value of base is between 2 and 36, it is used as the base for conversion.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated.
A pointer to the final string is stored in the object pointed to by endptr,
provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
strtoll()
Description
Convert to number, long long.
Prototype
long long strtoll(const char * nptr,
char ** endptr,
int base);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
| base | Radix to use for conversion, 2 to 36. |
Return value
Returns the converted value, if any. If no conversion could be
performed, zero is returned. If the correct value is outside
the range of representable values, LLONG_MIN or LLONG_MAX is
returned according to the sign of the value, if any, and the
value of the macro ERANGE is stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to a long representation.
First, strtoll() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling an integer represented in some radix determined
by the value of base, and a final string of one or more unrecognized
characters, including the terminating null character of the input string.
strtoll() then attempts to convert the subject sequence to an integer, and
return the result.
When converting, no integer suffix (such as U, L, UL, LL, ULL) is allowed.
If the value of base is zero, the expected form of the subject sequence
is an optional plus or minus sign followed by an integer constant.
If the value of base is between 2 and 36 (inclusive), the expected form
of the subject sequence is an optional plus or minus sign followed by a sequence
of letters and digits representing an integer with the radix specified by base.
The letters from a (or A) through z (or Z) represent the values 10 through 35;
only letters and digits whose ascribed values are less than that of base
are permitted.
If the value of base is 16, the characters “0x” or “0X” may optionally
precede the sequence of letters and digits, following the optional sign.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
If the subject sequence has the expected form and the value of base
is zero, the sequence of characters starting with the first digit is interpreted
as an integer constant. If the subject sequence has the expected form and the
value of base is between 2 and 36, it is used as the base for conversion.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated.
A pointer to the final string is stored in the object pointed to by endptr,
provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
strtoul()
Description
Convert to number, unsigned long.
Prototype
unsigned long strtoul(const char * nptr,
char ** endptr,
int base);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
| base | Radix to use for conversion, 2 to 36. |
Return value
strtoul() returns the converted value, if any. If no conversion could
be performed, zero is returned. If the correct value is outside the range of
representable values, ULONG_MAX is and the value of the macro ERANGE is
stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to a long int representation.
First, strtoul() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling an integer represented in some radix determined
by the value of base, and a final string of one or more unrecognized
characters, including the terminating null character of the input string. strtoul()
then attempts to convert the subject sequence to an integer, and return the
result.
When converting, no integer suffix (such as U, L, UL, LL, ULL) is allowed.
If the value of base is zero, the expected form of the subject sequence
is an optional plus or minus sign followed by an integer constant.
If the value of base is between 2 and 36 (inclusive), the expected form
of the subject sequence is an optional plus or minus sign followed by a sequence
of letters and digits representing an integer with the radix specified by base.
The letters from a (or A) through z (or Z) represent the values 10 through 35;
only letters and digits whose ascribed values are less than that of base
are permitted.
If the value of base is 16, the characters “0x” or “0X” may optionally
precede the sequence of letters and digits, following the optional sign.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
If the subject sequence has the expected form and the value of base
is zero, the sequence of characters starting with the first digit is interpreted
as an integer constant. If the subject sequence has the expected form and the
value of base is between 2 and 36, it is used as the base for conversion.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated.
A pointer to the final string is stored in the object pointed to by endptr,
provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
strtoull()
Description
Convert to number, unsigned long long.
Prototype
unsigned long long strtoull(const char * nptr,
char ** endptr,
int base);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
| base | Radix to use for conversion, 2 to 36. |
Return value
strtoull() returns the converted value, if any. If no conversion could
be performed, zero is returned. If the correct value is outside the range of
representable values, ULLONG_MAX is and the value of the macro ERANGE is
stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to a long int representation.
First, strtoull() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling an integer represented in some radix determined
by the value of base, and a final string of one or more unrecognized
characters, including the terminating null character of the input string. strtoull()
then attempts to convert the subject sequence to an integer, and return the
result.
When converting, no integer suffix (such as U, L, UL, LL, ULL) is allowed.
If the value of base is zero, the expected form of the subject sequence
is an optional plus or minus sign followed by an integer constant.
If the value of base is between 2 and 36 (inclusive), the expected form
of the subject sequence is an optional plus or minus sign followed by a sequence
of letters and digits representing an integer with the radix specified by base.
The letters from a (or A) through z (or Z) represent the values 10 through 35;
only letters and digits whose ascribed values are less than that of base
are permitted.
If the value of base is 16, the characters “0x” or “0X” may optionally
precede the sequence of letters and digits, following the optional sign.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
If the subject sequence has the expected form and the value of base
is zero, the sequence of characters starting with the first digit is interpreted
as an integer constant. If the subject sequence has the expected form and the
value of base is between 2 and 36, it is used as the base for conversion.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated.
A pointer to the final string is stored in the object pointed to by endptr,
provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
strtof()
Description
Convert to number, float.
Prototype
float strtof(const char * nptr,
char ** endptr);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
Return value
Returns the converted value, if any. If no conversion could be
performed, zero is returned. If the correct value is outside the
range of representable values, HUGE_VALF is returned according
to the sign of the value, if any, and the value of the macro ERANGE
is stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to float representation.
First, strtof() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling a floating-point constant, and a final string
of one or more unrecognized characters, including the terminating null character
of the input string. strtof() then attempts to convert the subject sequence
to a floating-point number, and return the result.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
The expected form of the subject sequence is an optional plus or minus sign
followed by a nonempty sequence of decimal digits optionally containing a
decimal-point character, then an optional exponent part.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated. A pointer to the final string is stored in the
object pointed to by endptr, provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
See also
strtod()
strtod()
Description
Convert to number, double.
Prototype
double strtod(const char * nptr,
char ** endptr);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
Return value
Returns the converted value, if any. If no conversion could be
performed, zero is returned. If the correct value is outside the
range of representable values, HUGE_VAL is returned according
to the sign of the value, if any, and the value of the macro ERANGE
is stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to double representation.
First, strtod() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling a floating-point constant, and a final string
of one or more unrecognized characters, including the terminating null character
of the input string. strtod() then attempts to convert the subject sequence
to a floating-point number, and return the result.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
The expected form of the subject sequence is an optional plus or minus sign
followed by a nonempty sequence of decimal digits optionally containing a
decimal-point character, then an optional exponent part.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated. A pointer to the final string is stored in the
object pointed to by endptr, provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
See also
strtof()
strtold()
Description
Convert to number, long double.
Prototype
long double strtold(const char * nptr,
char ** endptr);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
Return value
Returns the converted value, if any. If no conversion could be
performed, zero is returned. If the correct value is outside the
range of representable values, HUGE_VAL is returned according
to the sign of the value, if any, and the value of the macro ERANGE
is stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to long double representation.
First, strtold() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling a floating-point constant, and a final string
of one or more unrecognized characters, including the terminating null character
of the input string. strtod() then attempts to convert the subject sequence
to a floating-point number, and return the result.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
The expected form of the subject sequence is an optional plus or minus sign
followed by a nonempty sequence of decimal digits optionally containing a
decimal-point character, then an optional exponent part.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated. A pointer to the final string is stored in the
object pointed to by endptr, provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
See also
strtod()
wcstol()
Description
Convert to number, long.
Prototype
long wcstol(const wchar_t * nptr,
wchar_t ** endptr,
int base);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
| base | Radix to use for conversion, 2 to 36. |
Return value
Returns the converted value, if any. If no conversion could be
performed, zero is returned. If the correct value is outside
the range of representable values, LONG_MIN or LONG_MAX is
returned according to the sign of the value, if any, and the
value of the macro ERANGE is stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to a long representation.
First, wcstol() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling an integer represented in some radix determined
by the value of base, and a final string of one or more unrecognized
characters, including the terminating null character of the input string.
wcstol() then attempts to convert the subject sequence to an integer, and
return the result.
When converting, no integer suffix (such as U, L, UL, LL, ULL) is allowed.
If the value of base is zero, the expected form of the subject sequence
is an optional plus or minus sign followed by an integer constant.
If the value of base is between 2 and 36 (inclusive), the expected form
of the subject sequence is an optional plus or minus sign followed by a sequence
of letters and digits representing an integer with the radix specified by base.
The letters from a (or A) through z (or Z) represent the values 10 through 35;
only letters and digits whose ascribed values are less than that of base
are permitted.
If the value of base is 16, the characters “0x” or “0X” may optionally
precede the sequence of letters and digits, following the optional sign.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
If the subject sequence has the expected form and the value of base
is zero, the sequence of characters starting with the first digit is interpreted
as an integer constant. If the subject sequence has the expected form and the
value of base is between 2 and 36, it is used as the base for conversion.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated.
A pointer to the final string is stored in the object pointed to by endptr,
provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
wcstoll()
Description
Convert to number, long long.
Prototype
long long wcstoll(const wchar_t * nptr,
wchar_t ** endptr,
int base);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
| base | Radix to use for conversion, 2 to 36. |
Return value
Returns the converted value, if any. If no conversion could be
performed, zero is returned. If the correct value is outside
the range of representable values, LLONG_MIN or LLONG_MAX is
returned according to the sign of the value, if any, and the
value of the macro ERANGE is stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to a long representation.
First, wcstoll() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling an integer represented in some radix determined
by the value of base, and a final string of one or more unrecognized
characters, including the terminating null character of the input string.
wcstoll() then attempts to convert the subject sequence to an integer, and
return the result.
When converting, no integer suffix (such as U, L, UL, LL, ULL) is allowed.
If the value of base is zero, the expected form of the subject sequence
is an optional plus or minus sign followed by an integer constant.
If the value of base is between 2 and 36 (inclusive), the expected form
of the subject sequence is an optional plus or minus sign followed by a sequence
of letters and digits representing an integer with the radix specified by base.
The letters from a (or A) through z (or Z) represent the values 10 through 35;
only letters and digits whose ascribed values are less than that of base
are permitted.
If the value of base is 16, the characters “0x” or “0X” may optionally
precede the sequence of letters and digits, following the optional sign.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
If the subject sequence has the expected form and the value of base
is zero, the sequence of characters starting with the first digit is interpreted
as an integer constant. If the subject sequence has the expected form and the
value of base is between 2 and 36, it is used as the base for conversion.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated.
A pointer to the final string is stored in the object pointed to by endptr,
provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
wcstoul()
Description
Convert to number, unsigned long.
Prototype
unsigned long wcstoul(const wchar_t * nptr,
wchar_t ** endptr,
int base);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
| base | Radix to use for conversion, 2 to 36. |
Return value
wcstoul() returns the converted value, if any. If no conversion could
be performed, zero is returned. If the correct value is outside the range of
representable values, ULONG_MAX is and the value of the macro ERANGE is
stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to a long int representation.
First, wcstoul() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling an integer represented in some radix determined
by the value of base, and a final string of one or more unrecognized
characters, including the terminating null character of the input string. wcstoul()
then attempts to convert the subject sequence to an integer, and return the
result.
When converting, no integer suffix (such as U, L, UL, LL, ULL) is allowed.
If the value of base is zero, the expected form of the subject sequence
is an optional plus or minus sign followed by an integer constant.
If the value of base is between 2 and 36 (inclusive), the expected form
of the subject sequence is an optional plus or minus sign followed by a sequence
of letters and digits representing an integer with the radix specified by base.
The letters from a (or A) through z (or Z) represent the values 10 through 35;
only letters and digits whose ascribed values are less than that of base
are permitted.
If the value of base is 16, the characters “0x” or “0X” may optionally
precede the sequence of letters and digits, following the optional sign.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
If the subject sequence has the expected form and the value of base
is zero, the sequence of characters starting with the first digit is interpreted
as an integer constant. If the subject sequence has the expected form and the
value of base is between 2 and 36, it is used as the base for conversion.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated.
A pointer to the final string is stored in the object pointed to by endptr,
provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
wcstoull()
Description
Convert to number, unsigned long long.
Prototype
unsigned long long wcstoull(const wchar_t * nptr,
wchar_t ** endptr,
int base);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
| base | Radix to use for conversion, 2 to 36. |
Return value
wcstoull() returns the converted value, if any. If no conversion could
be performed, zero is returned. If the correct value is outside the range of
representable values, ULLONG_MAX is and the value of the macro ERANGE is
stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to a long int representation.
First, wcstoull() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling an integer represented in some radix determined
by the value of base, and a final string of one or more unrecognized
characters, including the terminating null character of the input string. wcstoull()
then attempts to convert the subject sequence to an integer, and return the
result.
When converting, no integer suffix (such as U, L, UL, LL, ULL) is allowed.
If the value of base is zero, the expected form of the subject sequence
is an optional plus or minus sign followed by an integer constant.
If the value of base is between 2 and 36 (inclusive), the expected form
of the subject sequence is an optional plus or minus sign followed by a sequence
of letters and digits representing an integer with the radix specified by base.
The letters from a (or A) through z (or Z) represent the values 10 through 35;
only letters and digits whose ascribed values are less than that of base
are permitted.
If the value of base is 16, the characters “0x” or “0X” may optionally
precede the sequence of letters and digits, following the optional sign.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
If the subject sequence has the expected form and the value of base
is zero, the sequence of characters starting with the first digit is interpreted
as an integer constant. If the subject sequence has the expected form and the
value of base is between 2 and 36, it is used as the base for conversion.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated.
A pointer to the final string is stored in the object pointed to by endptr,
provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
wcstof()
Description
Convert to number, float.
Prototype
float wcstof(const wchar_t * nptr,
wchar_t ** endptr);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
Return value
Returns the converted value, if any. If no conversion could be
performed, zero is returned. If the correct value is outside the
range of representable values, HUGE_VALF is returned according
to the sign of the value, if any, and the value of the macro ERANGE
is stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to float representation.
First, wcstof() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling a floating-point constant, and a final string
of one or more unrecognized characters, including the terminating null character
of the input string. wcstof() then attempts to convert the subject sequence
to a floating-point number, and return the result.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
The expected form of the subject sequence is an optional plus or minus sign
followed by a nonempty sequence of decimal digits optionally containing a
decimal-point character, then an optional exponent part.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated. A pointer to the final string is stored in the
object pointed to by endptr, provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
See also
wcstod()
wcstod()
Description
Convert to number, double.
Prototype
double wcstod(const wchar_t * nptr,
wchar_t ** endptr);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
Return value
Returns the converted value, if any. If no conversion could be
performed, zero is returned. If the correct value is outside the
range of representable values, HUGE_VAL is returned according
to the sign of the value, if any, and the value of the macro ERANGE
is stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to double representation.
First, wcstod() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling a floating-point constant, and a final string
of one or more unrecognized characters, including the terminating null character
of the input string. wcstod() then attempts to convert the subject sequence
to a floating-point number, and return the result.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
The expected form of the subject sequence is an optional plus or minus sign
followed by a nonempty sequence of decimal digits optionally containing a
decimal-point character, then an optional exponent part.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated. A pointer to the final string is stored in the
object pointed to by endptr, provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
See also
wcstof()
wcstold()
Description
Convert to number, long double.
Prototype
long double wcstold(const wchar_t * nptr,
wchar_t ** endptr);
Parameters
| Parameter | Description |
|---|
| nptr | Pointer to string to convert from. |
| endptr | If nonnull, a pointer to object that receives the pointer to the first unconverted character. |
Return value
Returns the converted value, if any. If no conversion could be
performed, zero is returned. If the correct value is outside the
range of representable values, HUGE_VAL is returned according
to the sign of the value, if any, and the value of the macro ERANGE
is stored in errno.
Additional information
Converts the initial portion of the string pointed to by nptr
to long double representation.
First, wcstold() decomposes the input string into three parts: an initial,
possibly empty, sequence of white-space characters, as specified by isspace(),
a subject sequence resembling a floating-point constant, and a final string
of one or more unrecognized characters, including the terminating null character
of the input string. wcstod() then attempts to convert the subject sequence
to a floating-point number, and return the result.
The subject sequence is defined as the longest initial subsequence of the input
string, starting with the first non-white-space character, that is of the expected
form. The subject sequence contains no characters if the input string is empty
or consists entirely of white space, or if the first non-white-space character
is other than a sign or a permissible letter or digit.
The expected form of the subject sequence is an optional plus or minus sign
followed by a nonempty sequence of decimal digits optionally containing a
decimal-point character, then an optional exponent part.
If the subject sequence begins with a minus sign, the value resulting from
the conversion is negated. A pointer to the final string is stored in the
object pointed to by endptr, provided that endptr is not a null pointer.
If the subject sequence is empty or does not have the expected form, no conversion
is performed, the value of nptr is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Thread safety
Safe.
See also
wcstod()
Multi-byte/wide character functions
| Function | Description |
|---|
| btowc() | Convert single-byte character to wide character. |
| btowc_l() | Convert single-byte character to wide character, per locale, (POSIX.1). |
| mblen() | Count number of bytes in multi-byte character. |
| mblen_l() | Count number of bytes in multi-byte character, per locale (POSIX.1). |
| mbtowc() | Convert multi-byte character to wide character. |
| mbtowc_l() | Convert multi-byte character to wide character, per locale (POSIX.1). |
| mbstowcs() | Convert multi-byte string to wide string. |
| mbstowcs_l() | Convert multi-byte string to wide string, per locale (POSIX.1). |
| mbsrtowcs() | Convert multi-byte string to wide character string, restartable. |
| mbsrtowcs_l() | Convert multi-byte string to wide character string, restartable, per locale (POSIX.1). |
| mbsnrtowcs() | Convert multi-byte string to wide character string, restartable, per locale (POSIX.1). |
| mbsnrtowcs_l() | Convert multi-byte string to wide character string, restartable, per locale (POSIX.1). |
| wctomb() | Convert wide character to multi-byte character. |
| wctomb_l() | Convert wide character to multi-byte character, per locale (POSIX.1). |
| wcstombs() | Convert wide string to multi-byte string. |
| wcstombs_l() | Convert wide string to multi-byte string. |
btowc()
Description
Convert single-byte character to wide character.
Prototype
wint_t btowc(int c);
Parameters
| Parameter | Description |
|---|
| c | Character to convert. |
Return value
Returns WEOF if c has the value EOF or if c, converted to
an unsigned char and in the current locale, does not constitute
a valid single-byte character in the initial shift state.
Additional information
Determines whether c constitutes a valid single-byte character
in the current locale. If c is a valid single-byte character,
btowc() returns the wide character representation of that character.
Thread safety
Safe [if configured].
btowc_l()
Description
Convert single-byte character to wide character, per locale, (POSIX.1).
Prototype
wint_t btowc_l(int c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Character to convert. |
| loc | Locale used for conversion. |
Return value
Returns WEOF if c has the value EOF or if c, converted to
an unsigned char and in the locale loc, does not constitute
a valid single-byte character in the initial shift state.
Additional information
Determines whether c constitutes a valid single-byte character
in the locale loc. If c is a valid single-byte character,
btowc_l() returns the wide character representation of that character.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
mblen()
Description
Count number of bytes in multi-byte character.
Prototype
int mblen(const char * s,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to multi-byte character. |
| n | Maximum number of bytes to examine. |
Return value
If s is a null pointer, returns a nonzero or zero value, if multi-byte
character encodings, respectively, do or do not have state-dependent
encodings.
If s is not a null pointer, either returns 0 (if s points to the
null character), or returns the number of bytes that are contained in the
multi-byte character (if the next n or fewer bytes form a valid multi-byte
character), or returns -1 (if they do not form a valid multi-byte
character).
Additional information
Determines the number of bytes contained in the multi-byte
character pointed to by s in the current locale.
Except that the conversion state of the mbtowc() function is not
affected, it is equivalent to
mbtowc(NULL, s, n);
Thread safety
Safe [if configured].
See also
mblen_l(), mbtowc()
mblen_l()
Description
Count number of bytes in multi-byte character, per locale (POSIX.1).
Prototype
int mblen_l(const char * s,
size_t n,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| s | Pointer to multi-byte character. |
| n | Maximum number of bytes to examine. |
| loc | Locale to use for conversion. |
Return value
If s is a null pointer, returns a nonzero or zero value, if multi-byte
character encodings, respectively, do or do not have state-dependent
encodings in locale loc.
If s is not a null pointer, either returns 0 (if s points to the
null character), or returns the number of bytes that are contained in the
multi-byte character (if the next n or fewer bytes form a valid multi-byte
character), or returns -1 (if they do not form a valid multi-byte
character).
Additional information
Determines the number of bytes contained in the multi-byte
character pointed to by s in the locale loc.
Except that the conversion state of the mbtowc() function is not
affected, it is equivalent to
mbtowc_l(NULL, s, n, loc);
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
See also
mblen(), mbtowc()
mbtowc()
Description
Convert multi-byte character to wide character.
Prototype
int mbtowc( wchar_t * pwc,
const char * s,
size_t n);
Parameters
| Parameter | Description |
|---|
| pwc | Pointer to object that receives the wide character. |
| s | Pointer to multi-byte character string. |
| n | Maximum number of bytes that will be examined. |
Return value
If s is a null pointer, mbtowc() returns a nonzero value if multi-byte
character encodings are state-dependent in the current locale, and
zero otherwise.
If s is not null and the object that s points to is a
wide character null, mbtowc() returns 0.
If s is not null and the object that s points to forms a valid
multi-byte character, mbtowc() returns the length in bytes of the
multi-byte character.
If the object that mbtowc() points to does not form a valid multi-byte
character within the first n characters, it returns -1.
Additional information
Converts a single multi-byte character to a wide character in
the current locale. The wide character, if the multi-byte character
string is converted correctly, is stored into the object pointed
to by pwc.
Thread safety
Safe [if configured].
See also
mbtowc_l().
mbtowc_l()
Description
Convert multi-byte character to wide character, per locale (POSIX.1).
Prototype
int mbtowc_l( wchar_t * pwc,
const char * s,
size_t n,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| pwc | Pointer to object that receives the wide character. |
| s | Pointer to multi-byte character string. |
| n | Maximum number of bytes that will be examined. |
| loc | Locale used to convert the multi-byte character. |
Return value
If s is a null pointer, mbtowc_l() returns a nonzero value if multi-byte
character encodings are state-dependent in locale loc, and
zero otherwise.
If s is not null and the object that s points to is a
wide null character, mbtowc_l() returns 0.
If s is not null and the object that s points to forms a valid
multi-byte character, mbtowc_l() returns the length in bytes of the
multi-byte character.
If the object that mbtowc_l() points to does not form a valid multi-byte
character within the first n characters, it returns -1.
Additional information
Converts a single multi-byte character to a wide character in
the locale loc. The wide character, if the multi-byte character
string is converted correctly, is stored into the object pointed
to by pwc.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
See also
mbtowc()
mbstowcs()
Description
Convert multi-byte string to wide string.
Prototype
size_t mbstowcs( wchar_t * pwcs,
const char * s,
size_t n);
Parameters
| Parameter | Description |
|---|
| pwcs | Pointer to array that receives the wide character string. |
| s | Pointer to array that contains the multi-byte string. |
| n | Maximum number of wide characters to write into pwcs. |
Return value
Returns -1 if an invalid multi-byte character is encountered,
otherwise returns the number of array elements modified (if
any), not including a terminating null wide character.
Additional information
Converts a sequence of multi-byte characters, in the current locale,
that begins in the initial shift state from the array pointed to by
s into a sequence of corresponding wide characters and stores not
more than n wide characters into the array pointed to by pwcs.
No multi-byte characters that follow a null character (which is converted
into a null wide character) will be examined or converted. Each multi-byte
character is converted as if by a call to the mbtowc() function, except
that the conversion state of the mbtowc() function is not affected.
No more than n elements will be modified in the array pointed to by
pwcs. If copying takes place between objects that overlap, the behavior
is undefined.
Thread safety
Safe [if configured].
mbstowcs_l()
Description
Convert multi-byte string to wide string, per locale (POSIX.1).
Prototype
size_t mbstowcs_l( wchar_t * pwcs,
const char * s,
size_t n,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| pwcs | Pointer to array that receives the wide character string. |
| s | Pointer to array that contains the multi-byte string. |
| n | Maximum number of wide characters to write into pwcs. |
| loc | Locale to use for conversion. |
Return value
Returns -1 if an invalid multi-byte character is encountered,
otherwise returns the number of array elements modified (if
any), not including a terminating null wide character.
Additional information
Converts a sequence of multi-byte characters, in the locale loc,
that begins in the initial shift state from the array pointed to by
s into a sequence of corresponding wide characters and stores not
more than n wide characters into the array pointed to by pwcs.
No multi-byte characters that follow a null character (which is converted
into a null wide character) will be examined or converted. Each multi-byte
character is converted as if by a call to the mbtowc() function, except
that the conversion state of the mbtowc() function is not affected.
No more than n elements will be modified in the array pointed to by
pwcs. If copying takes place between objects that overlap, the behavior
is undefined.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
mbsrtowcs()
Description
Convert multi-byte string to wide character string, restartable.
Prototype
size_t mbsrtowcs( wchar_t * dst,
const char ** src,
size_t len,
mbstate_t * ps);
Parameters
| Parameter | Description |
|---|
| dst | Pointer to object that receives the converted wide characters. |
| src | Pointer to pointer to multi-byte character string. |
| len | Maximum number of wide characters that will be written to dst. |
| ps | Pointer to multi-byte conversion state. |
Return value
The number of wide characters written to dst (not including the
eventual terminating null character).
Additional information
Converts a sequence of multi-byte characters, in the current locale,
that begins in the conversion state described by the object pointed
to by ps, from the array indirectly pointed to by src into a sequence
of corresponding wide characters.
If dst is not a null pointer, the converted characters are stored
into the array pointed to by dst. Conversion continues up to and
including a terminating null character, which is also stored.
Conversion stops earlier in two cases: when a sequence of bytes is
encountered that does not form a valid multi-byte character, or
(if dst is not a null pointer) when len wide characters have been
stored into the array pointed to by dst. Each conversion takes place
as if by a call to the mbrtowc() function.
If dst is not a null pointer, the pointer object pointed to by
src is assigned either a null pointer (if conversion stopped due to
reaching a terminating null character) or the address just past the
last multi-byte character converted (if any). If conversion stopped
due to reaching a terminating null character and if dst is not a null
pointer, the resulting state described is the initial conversion state.
Thread safety
Safe [if configured].
See also
mbsrtowcs_l(), mbrtowc()
mbsrtowcs_l()
Description
Convert multi-byte string to wide character string, restartable, per locale (POSIX.1).
Prototype
size_t mbsrtowcs_l( wchar_t * dst,
const char ** src,
size_t len,
mbstate_t * ps,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| dst | Pointer to object that receives the converted wide characters. |
| src | Pointer to pointer to multi-byte character string. |
| len | Maximum number of wide characters that will be written to dst. |
| ps | Pointer to multi-byte conversion state. |
| loc | Locale used for conversion. |
Return value
The number of wide characters written to dst (not including the
eventual terminating null character).
Additional information
Converts a sequence of multi-byte characters, in the locale loc,
that begins in the conversion state described by the object pointed
to by ps, from the array indirectly pointed to by src into a sequence
of corresponding wide characters.
If dst is not a null pointer, the converted characters are stored
into the array pointed to by dst. Conversion continues up to and
including a terminating null character, which is also stored.
Conversion stops earlier in two cases: when a sequence of bytes is
encountered that does not form a valid multi-byte character, or
(if dst is not a null pointer) when len wide characters have been
stored into the array pointed to by dst. Each conversion takes place
as if by a call to the mbrtowc() function.
If dst is not a null pointer, the pointer object pointed to by
src is assigned either a null pointer (if conversion stopped due to
reaching a terminating null character) or the address just past the
last multi-byte character converted (if any). If conversion stopped
due to reaching a terminating null character and if dst is not a null
pointer, the resulting state described is the initial conversion state.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
See also
mbsrtowcs(), mbrtowc()
mbsnrtowcs()
Description
Convert multi-byte string to wide character string, restartable, per locale (POSIX.1).
Prototype
size_t mbsnrtowcs( wchar_t * dst,
const char ** src,
size_t nmc,
size_t len,
mbstate_t * ps);
Parameters
| Parameter | Description |
|---|
| dst | Pointer to object that receives the converted wide characters. |
| src | Pointer to pointer to multi-byte character string. |
| nmc | Maximum number of bytes to be read from src. |
| len | Maximum number of wide characters that will be written to dst. |
| ps | Pointer to multi-byte conversion state. |
Return value
The number of wide characters written to dst (not including the
eventual terminating null character).
Additional information
Converts a sequence of multi-byte characters, in the locale loc,
that begins in the conversion state described by the object pointed
to by ps, from the array indirectly pointed to by src into a sequence
of corresponding wide characters.
If dst is not a null pointer, the converted characters are stored
into the array pointed to by dst. Conversion continues up to and
including a terminating null character, which is also stored.
Conversion stops earlier in two cases: when a sequence of bytes is
encountered that does not form a valid multi-byte character, or
(if dst is not a null pointer) when len wide characters have been
stored into the array pointed to by dst. Each conversion takes place
as if by a call to the mbrtowc() function.
If dst is not a null pointer, the pointer object pointed to by
src is assigned either a null pointer (if conversion stopped due to
reaching a terminating null character) or the address just past the
last multi-byte character converted (if any). If conversion stopped
due to reaching a terminating null character and if dst is not a null
pointer, the resulting state described is the initial conversion state.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe [if configured].
See also
mbsrtowcs(), mbrtowc()
mbsnrtowcs_l()
Description
Convert multi-byte string to wide character string, restartable, per locale (POSIX.1).
Prototype
size_t mbsnrtowcs_l( wchar_t * dst,
const char ** src,
size_t nmc,
size_t len,
mbstate_t * ps,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| dst | Pointer to object that receives the converted wide characters. |
| src | Pointer to pointer to multi-byte character string. |
| nmc | Maximum number of bytes to be read from src. |
| len | Maximum number of wide characters that will be written to dst. |
| ps | Pointer to multi-byte conversion state. |
| loc | Locale used for conversion. |
Return value
The number of wide characters written to dst (not including the
eventual terminating null character).
Additional information
Converts a sequence of multi-byte characters, in the locale loc,
that begins in the conversion state described by the object pointed
to by ps, from the array indirectly pointed to by src into a sequence
of corresponding wide characters.
If dst is not a null pointer, the converted characters are stored
into the array pointed to by dst. Conversion continues up to and
including a terminating null character, which is also stored.
Conversion stops earlier in two cases: when a sequence of bytes is
encountered that does not form a valid multi-byte character, or
(if dst is not a null pointer) when len wide characters have been
stored into the array pointed to by dst. Each conversion takes place
as if by a call to the mbrtowc() function.
If dst is not a null pointer, the pointer object pointed to by
src is assigned either a null pointer (if conversion stopped due to
reaching a terminating null character) or the address just past the
last multi-byte character converted (if any). If conversion stopped
due to reaching a terminating null character and if dst is not a null
pointer, the resulting state described is the initial conversion state.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
See also
mbsrtowcs(), mbrtowc()
wctomb()
Description
Convert wide character to multi-byte character.
Prototype
int wctomb(char * s,
wchar_t wc);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the multi-byte character. |
| wc | Wide character to convert. |
Return value
Returns the number of bytes stored in the array object. When wc is
not a valid wide character, an encoding error occurs: wctomb() stores
the value of the macro EILSEQ in errno and returns (size_t)(-1); the
conversion state is unspecified.
Additional information
If s is a null pointer, wctomb() is equivalent to the call
wcrtomb(buf, 0, ps) where buf is an internal buffer.
If s is not a null pointer, wctomb() determines the number of bytes needed
to represent the multi-byte character that corresponds to the wide character given
by wc in the current locale, and stores the multi-byte character representation
in the array whose first element is pointed to by s. At most MB_CUR_MAX bytes
are stored. If wc is a null wide character, a null byte is stored; the resulting
state described is the initial conversion state.
Thread safety
Safe [if configured].
wctomb_l()
Description
Convert wide character to multi-byte character, per locale (POSIX.1).
Prototype
int wctomb_l(char * s,
wchar_t wc,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the multi-byte character. |
| wc | Wide character to convert. |
| loc | Locale used for conversion. |
Return value
Returns the number of bytes stored in the array object. When wc is
not a valid wide character, an encoding error occurs: wctomb_l() stores
the value of the macro EILSEQ in errno and returns (size_t)(-1); the
conversion state is unspecified.
Additional information
If s is a null pointer, wctomb_l() is equivalent to the call
wcrtomb_l(buf, 0, ps, loc) where buf is an internal buffer.
If s is not a null pointer, wctomb_l() determines the number of bytes needed
to represent the multi-byte character that corresponds to the wide character given
by wc in the locale loc, and stores the multi-byte character representation
in the array whose first element is pointed to by s. At most MB_CUR_MAX bytes
are stored. If wc is a null wide character, a null byte is stored; the resulting
state described is the initial conversion state.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
wcstombs()
Description
Convert wide string to multi-byte string.
Prototype
size_t wcstombs( char * s,
const wchar_t * pwcs,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the multi-byte string. |
| pwcs | Pointer to wide character string to convert. |
| n | Maximum number of bytes to write into s. |
Return value
If a wide character is encountered that does not correspond
to a valid multibyte character in the current locale, returns
(size_t)(-1). Otherwise, returns the number of bytes written,
not including a terminating null character (if any).
Additional information
Converts a sequence of wide characters in the current locale from
the array pointed to by pwcs into a sequence of corresponding
multi-byte characters that begins in the initial shift state,
and stores these multi-byte characters into the array pointed
to by s, stopping if a multi-byte character would exceed the
limit of n total bytes or if a null character is stored. Each
wide character is converted as if by a call to wctomb(), except
that the conversion state of wctomb() is not affected.
Thread safety
Safe [if configured].
wcstombs_l()
Description
Convert wide string to multi-byte string.
Prototype
size_t wcstombs_l( char * s,
const wchar_t * pwcs,
size_t n,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the multi-byte string. |
| pwcs | Pointer to wide character string to convert. |
| n | Maximum number of bytes to write into s. |
| loc | Locale used for conversion. |
Return value
If a wide character is encountered that does not correspond
to a valid multibyte character in the locale loc, returns
(size_t)(-1). Otherwise, returns the number of bytes written,
not including a terminating null character (if any).
Additional information
Converts a sequence of wide characters in the locale loc from
the array pointed to by pwcs into a sequence of corresponding
multi-byte characters that begins in the initial shift state,
and stores these multi-byte characters into the array pointed
to by s, stopping if a multi-byte character would exceed the
limit of n total bytes or if a null character is stored. Each
wide character is converted as if by a call to wctomb(), except
that the conversion state of wctomb() is not affected.
Thread safety
Safe.
<string.h>
The header file <string.h> defines functions that operate on
arrays that are interpreted as null-terminated strings.
Various methods are used for determining the lengths of the arrays, but in
all cases a char * or void * argument points to the initial (lowest
addressed) character of the array. If an array is accessed beyond the end of
an object, the behavior is undefined.
Where an argument declared as size_t n specifies the length of an array
for a function, n can have the value zero on a call to that function.
Unless explicitly stated otherwise in the description of a particular function,
pointer arguments must have valid values on a call with a zero size. On such
a call, a function that locates a character finds no occurrence, a function
that compares two character sequences returns zero, and a function that copies
characters copies zero characters.
Copying functions
| Function | Description |
|---|
| memset() | Set memory to character. |
| memset_s() | Set memory to character, safe (C11). |
| memcpy() | Copy memory. |
| memcpy_s() | Copy memory, safe (C11). |
| memccpy() | Copy memory, specify terminator (POSIX.1). |
| mempcpy() | Copy memory (GNU). |
| memmove() | Copy memory, tolerate overlaps. |
| memmove_s() | Copy memory, tolerate overlaps, safe (C11). |
| strcpy() | Copy string. |
| strcpy_s() | Copy string, safe (C11). |
| strncpy() | Copy string, limit length. |
| strlcpy() | Copy string, limit length, always zero terminate (BSD). |
| stpcpy() | Copy string, return end. |
| stpncpy() | Copy string, limit length, return end. |
| strcat() | Concatenate strings. |
| strncat() | Concatenate strings, limit length. |
| strlcat() | Concatenate strings, limit length, always zero terminate (BSD). |
| strdup() | Duplicate string (POSIX.1). |
| strndup() | Duplicate string, limit length (POSIX.1). |
| strxfrm() | Transform strings. |
memset()
Description
Set memory to character.
Prototype
void *memset(void * s,
int c,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to destination object. |
| c | Character to write. |
| n | Number of characters to write in destination object. |
Return value
Returns s.
Additional information
Copies the value of c (converted to an unsigned char) into each
of the first n characters of the object pointed to by s.
Thread safety
Safe.
memset_s()
Description
Set memory to character, safe (C11).
Prototype
errno_t memset_s(void * s,
size_t smax,
int c,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to destination object. |
| smax | Size of destination object in characters. |
| c | Character to write. |
| n | Number of characters to write in destination object. |
Runtime constraints
- s shall not be a null pointer.
- Neither smax nor n shall be greater than RSIZE_MAX.
- n shall not be greater than s1max.
If there is a runtime-constraint violation, memset_s() stores
c (converted to an unsigned char) into each of the first smax
characters of the object pointed to by s, if s is not a null
pointer and smax is not greater than RSIZE_MAX.
Return value
| = 0 | if runtime constraints are not violated. |
| ≠ 0 | if runtime constraints are violated. |
Additional information
The macro __STDC_WANT_LIB_EXT1__ must be set to 1 before
including <string.h> to access this function.
Copies the value of c (converted to an unsigned char) into each
of the first n characters of the object pointed to by s.
Conformance
ISO/IEC 9899:2011 (C11).
Thread safety
Safe.
memcpy()
Description
Copy memory.
Prototype
void *memcpy( void * s1,
const void * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination object. |
| s2 | Pointer to source object. |
| n | Number of characters to copy. |
Return value
Returns a pointer to the destination object.
Additional information
Copies n characters from the object pointed to by s2 into the
object pointed to by s1. The behavior of memcpy() is undefined
if copying takes place between objects that overlap.
Thread safety
Safe.
memcpy_s()
Description
Copy memory, safe (C11).
Prototype
errno_t memcpy_s( void * s1,
size_t s1max,
const void * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination object. |
| s1max | Size of destination object in characters. |
| s2 | Pointer to source object. |
| n | Number of characters to copy. |
Runtime constraints
- Neither s1 nor s2 shall be a null pointer.
- Neither s1max nor n shall be greater than RSIZE_MAX.
- n shall not be greater than s1max.
- Copying shall not take place between objects that overlap.
If there is a runtime-constraint violation, memcpy_s() stores
zeros in the first s1max characters of the object pointed to by
s1, if s1 is not a null pointer and s1max is not greater than RSIZE_MAX.
Return value
| = 0 | if runtime constraints are not violated. |
| ≠ 0 | if runtime constraints are violated. |
Additional information
The macro __STDC_WANT_LIB_EXT1__ must be set to 1 before
including <string.h> to access this function.
Copies n characters from the object pointed to by s2 into the
object pointed to by s1.
Conformance
ISO/IEC 9899:2011 (C11).
Thread safety
Safe.
memccpy()
Description
Copy memory, specify terminator (POSIX.1).
Prototype
void *memccpy( void * s1,
const void * s2,
int c,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination object. |
| s2 | Pointer to source object. |
| c | Character that terminates copy. |
| n | Maximum number of characters to copy. |
Return value
Returns a pointer to the character immediately following c in
s1, or NULL if c was not found in the first n characters of s2.
Additional information
Copies at most n characters from the object pointed to
by s2 into the object pointed to by s1. The copying stops as soon as
n characters are copied or the character c is copied into the
destination object pointed to by s1.
The behavior of memccpy() is undefined if copying takes place
between objects that overlap.
Conformance
POSIX.1-2008.
Thread safety
Safe.
mempcpy()
Description
Copy memory (GNU).
Prototype
void *mempcpy( void * s1,
const void * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination object. |
| s2 | Pointer to source object. |
| n | Number of characters to copy. |
Return value
Returns a pointer to the character immediately following the
final character written into s1.
Additional information
Copies n characters from the object pointed to by s2 into the
object pointed to by s1. The behavior of mempcpy() is undefined
if copying takes place between objects that overlap.
Conformance
This is an extension found in GNU libc.
Thread safety
Safe.
memmove()
Description
Copy memory, tolerate overlaps.
Prototype
void *memmove( void * s1,
const void * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination object. |
| s2 | Pointer to source object. |
| n | Number of characters to copy. |
Return value
Returns the value of s1.
Additional information
Copies n characters from the object pointed to by s2 into the
object pointed to by s1 ensuring that if s1 and s2 overlap, the
copy works correctly. Copying takes place as if the n characters
from the object pointed to by s2 are first copied into a temporary
array of n characters that does not overlap the objects pointed to
by s1 and s2, and then the n characters from the temporary array
are copied into the object pointed to by s1.
Thread safety
Safe.
memmove_s()
Description
Copy memory, tolerate overlaps, safe (C11).
Prototype
errno_t memmove_s( void * s1,
size_t s1max,
const void * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination object. |
| s1max | Size of destination object in characters. |
| s2 | Pointer to source object. |
| n | Number of characters to copy. |
Runtime constraints
- Neither s1 nor s2 shall be a null pointer.
- Neither s1max nor n shall be greater than RSIZE_MAX.
- n shall not be greater than s1max.
If there is a runtime-constraint violation, memmove_s() stores
zeros in the first s1max characters of the object pointed to by
s1, if s1 is not a null pointer and s1max is not greater than RSIZE_MAX.
Return value
| = 0 | if runtime constraints are not violated. |
| ≠ 0 | if runtime constraints are violated. |
Additional information
The macro __STDC_WANT_LIB_EXT1__ must be set to 1 before
including <string.h> to access this function.
Copies n characters from the object pointed to by s2 into the
object pointed to by s1 ensuring that if s1 and s2 overlap, the
copy works correctly. Copying takes place as if the n characters
from the object pointed to by s2 are first copied into a temporary
array of n characters that does not overlap the objects pointed to
by s1 and s2, and then the n characters from the temporary array
are copied into the object pointed to by s1.
Conformance
ISO/IEC 9899:2011 (C11).
Thread safety
Safe.
strcpy()
Description
Copy string.
Prototype
char *strcpy( char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | String to copy to. |
| s2 | String to copy. |
Return value
Returns the value of s1.
Additional information
Copies the string pointed to by s2 (including the terminating
null character) into the array pointed to by s1. The behavior of strcpy()
is undefined if copying takes place between objects that overlap.
Thread safety
Safe.
strcpy_s()
Description
Copy string, safe (C11).
Prototype
errno_t strcpy_s( char * s1,
size_t s1max,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination object. |
| s1max | Size of destination object in characters. |
| s2 | Pointer to source object. |
Runtime constraints
- Neither s1 nor s2 shall be a null pointer.
- s1max shall not be greater than RSIZE_MAX.
- s1max shall be greater than strnlen_s(s2, s1max).
- Copying shall not take place between objects that overlap.
If there is a runtime-constraint violation, strcpy_s() sets
s1[0] to zero if s1 is nonnull and s1max is not greater
than RSIZE_MAX.
Return value
| = 0 | if runtime constraints are not violated. |
| ≠ 0 | if runtime constraints are violated. |
Additional information
The macro __STDC_WANT_LIB_EXT1__ must be set to 1 before
including <string.h> to access this function.
Copies the string pointed to by s2 (including the terminating
null character) into the array pointed to by s1.
Conformance
ISO/IEC 9899:2011 (C11).
Thread safety
Safe.
strncpy()
Description
Copy string, limit length.
Prototype
char *strncpy( char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | String to copy to. |
| s2 | String to copy. |
| n | Maximum number of characters to copy. |
Return value
Returns the value of s1.
Additional information
Copies not more than n characters from the array pointed
to by s2 to the array pointed to by s1. Characters that follow
a null character in s2 are not copied. The behavior of strncpy()
is undefined if copying takes place between objects that overlap.
If the array pointed to by s2 is a string that is shorter than n
characters, null characters are appended to the copy in the array
pointed to by s1, until n characters in all have been written.
Notes
No null character is implicitly appended to the end of s1, so s1
will only be terminated by a null character if the length of the
string pointed to by s2 is less than n.
Thread safety
Safe.
strlcpy()
Description
Copy string, limit length, always zero terminate (BSD).
Prototype
size_t strlcpy( char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to string to copy to. |
| s2 | Pointer to string to copy. |
| n | Maximum number of characters, including terminating null, in s1. |
Return value
Returns the number of characters it tried to copy, which is
the length of the string s2 or n, whichever is smaller.
Additional information
Copies up to n-1 characters from the string pointed to by
s2 into the array pointed to by s1 and always terminates
the result with a null character.
The behavior of strlcpy() is undefined if copying takes place between
objects that overlap.
Conformance
Commonly found in BSD libraries and contrasts with strncpy()
in that the resulting string is always terminated with a null
character.
Thread safety
Safe.
stpcpy()
Description
Copy string, return end.
Prototype
char *stpcpy( char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | String to copy to. |
| s2 | String to copy. |
Return value
A pointer to the end of the string s1, i.e. the terminating null
byte of the string s1, after s2 is copied to it.
Additional information
Copies the string pointed to by s2 (including the terminating
null character) into the array pointed to by s1. The behavior of stpcpy()
is undefined if copying takes place between objects that overlap.
Thread safety
Safe.
stpncpy()
Description
Copy string, limit length, return end.
Prototype
char *stpncpy( char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | String to copy to. |
| s2 | String to copy. |
| n | Maximum number of characters to copy. |
Return value
stpncpy() returns a pointer to the terminating null byte in s1
after it is copied to, or, if s1 is not null-terminated, s1+n.
Additional information
Copies not more than n characters from the array pointed
to by s2 to the array pointed to by s1. Characters that follow
a null character in s2 are not copied. The behavior of strncpy()
is undefined if copying takes place between objects that overlap.
If the array pointed to by s2 is a string that is shorter than n
characters, null characters are appended to the copy in the array
pointed to by s1, until n characters in all have been written.
Notes
No null character is implicitly appended to the end of s1, so s1 will only be
terminated by a null character if the length of the string pointed to by s2 is
less than n.
Thread safety
Safe.
strcat()
Description
Concatenate strings.
Prototype
char *strcat( char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Zero-terminated string to append to. |
| s2 | Zero-terminated string to append. |
Return value
Returns the value of s1.
Additional information
Appends a copy of the string pointed to by s2 (including
the terminating null character) to the end of the string pointed to by s1.
The initial character of s2 overwrites the null character at the end
of s1. The behavior of strcat() is undefined if copying takes place
between objects that overlap.
Thread safety
Safe.
strncat()
Description
Concatenate strings, limit length.
Prototype
char *strncat( char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | String to append to. |
| s2 | String to append. |
| n | Maximum number of characters in s1. |
Return value
Returns the value of s1.
Additional information
Appends not more than n characters from the array pointed
to by s2 to the end of the string pointed to by s1. A null character
in s1 and characters that follow it are not appended. The initial character
of s2 overwrites the null character at the end of s1. A terminating
null character is always appended to the result.
The behavior of strncat() is undefined if copying takes place between
objects that overlap.
Thread safety
Safe.
strlcat()
Description
Concatenate strings, limit length, always zero terminate (BSD).
Prototype
size_t strlcat( char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to string to append to. |
| s2 | Pointer to string to append. |
| n | Maximum number of characters, including terminating null, in s1. |
Return value
Returns the number of characters it tried to copy, which is
the sum of the lengths of the strings s1 and s2 or n,
whichever is smaller.
Additional information
Appends no more than n-strlen(s1}-1 characters pointed to by s2 into
the array pointed to by s1 and always terminates the result with a
null character if n is greater than zero. Both the strings s1 and
s2 must be terminated with a null character on entry to strlcat()
and a character position for the terminating null should be included
in n.
The behavior of strlcat() is undefined if copying takes place between
objects that overlap.
Conformance
Commonly found in BSD libraries.
Thread safety
Safe.
strdup()
Description
Duplicate string (POSIX.1).
Prototype
char *strdup(const char * s1);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to string to duplicate. |
Return value
Returns a pointer to the new string or a null pointer if the
new string cannot be created. The returned pointer can be passed
to free().
Additional information
Duplicates the string pointed to by s1 by using malloc() to
allocate memory for a copy of s and then copyies s, including the
terminating null, to that memory
Conformance
POSIX.1-2008 and SC22 TR 24731-2.
Thread safety
Safe.
strndup()
Description
Duplicate string, limit length (POSIX.1).
Prototype
char *strndup(const char * s,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to string to duplicate. |
| n | Maximum number of characters to duplicate. |
Return value
Returns a pointer to the new string or a null pointer if the
new string cannot be created. The returned pointer can be
passed to free().
Additional information
Duplicates at most n characters from the the string pointed to
by s by using malloc() to allocate memory for a copy of s.
If the length of string pointed to by s is greater than n characters,
only n characters will be duplicated. If n is greater than the length of
the string pointed to by s, all characters in the string are copied into the
allocated array including the terminating null character.
Conformance
Conforms to POSIX.1-2008 and SC22 TR 24731-2.
Thread safety
Safe.
strxfrm()
Description
Transform strings.
Prototype
size_t strxfrm( char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination array. |
| s2 | Pointer to source string. |
| n | Maximum number of characters in the destination array. |
Return value
Returns the length of the transformed string. If the value
returned is n or more, the contents of the array pointed to
by s1 are undefined.
Thread safety
Safe.
Comparison functions
memcmp()
Description
Compare memory.
Prototype
int memcmp(const void * s1,
const void * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to object #1. |
| s2 | Pointer to object #2. |
| n | Number of characters to compare. |
Return value
| < 0 | s1 is less than s2. |
| = 0 | s1 is equal to s2. |
| > 0 | s1 is greater than to s2. |
Additional information
Compares the first n characters of the object pointed to by s1 to the
first n characters of the object pointed to by s2. memcmp() returns an
integer greater than, equal to, or less than zero as the object pointed
to by s1 is greater than, equal to, or less than the object pointed to
by s2.
Thread safety
Safe.
strcmp()
Description
Compare strings.
Prototype
int strcmp(const char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to string #1. |
| s2 | Pointer to string #2. |
Return value
Returns an integer greater than, equal to, or less than zero,
if the null-terminated array pointed to by s1 is greater than,
equal to, or less than the null-terminated array pointed to by s2.
Thread safety
Safe.
strncmp()
Description
Compare strings, limit length.
Prototype
int strncmp(const char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to string #1. |
| s2 | Pointer to string #2. |
| n | Maximum number of characters to compare. |
Return value
Returns an integer greater than, equal to, or less than zero,
if the possibly null-terminated array pointed to by s1 is greater than,
equal to, or less than the possibly null-terminated array pointed to by s2.
Additional information
Compares not more than n characters from the array pointed
to by s1 to the array pointed to by s2. Characters that follow
a null character are not compared.
Thread safety
Safe.
strcasecmp()
Description
Compare strings, ignore case (POSIX.1).
Prototype
int strcasecmp(const char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to string #1. |
| s2 | Pointer to string #2. |
Return value
| < 0 | s1 is less than s2. |
| = 0 | s1 is equal to s2. |
| > 0 | s1 is greater than to s2. |
Additional information
Compares the string pointed to by s1 to the string pointed
to by s2 ignoring differences in case.
strcasecmp() returns an integer greater than, equal to, or
less than zero if the string pointed to by s1 is greater
than, equal to, or less than the string pointed to by s2.
Conformance
POSIX.1-2008.
Thread safety
Safe.
strncasecmp()
Description
Compare strings, ignore case, limit length (POSIX.1).
Prototype
int strncasecmp(const char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to string #1. |
| s2 | Pointer to string #2. |
| n | Maximum number of characters to compare. |
Return value
| < 0 | s1 is less than s2. |
| = 0 | s1 is equal to s2. |
| > 0 | s1 is greater than to s2. |
Additional information
Compares not more than n characters from the array pointed
to by s1 to the array pointed to by s2 ignoring differences in case.
Characters that follow a null character are not compared.
strncasecmp() returns an integer greater than, equal to, or less than zero,
if the possibly null-terminated array pointed to by s1 is greater than,
equal to, or less than the possibly null-terminated array pointed to by s2.
Conformance
POSIX.1-2008.
Thread safety
Safe.
strcoll()
Description
Collate strings.
Prototype
int strcoll(const char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to string #1. |
| s2 | Pointer to string #2. |
Return value
Returns an integer greater than, equal to, or less than zero,
if the null-terminated array pointed to by s1 is greater than,
equal to, or less than the null-terminated array pointed to by s2.
Thread safety
Safe.
Search functions
| Function | Description |
|---|
| memchr() | Find character in memory, forward. |
| memrchr() | Find character in memory, reverse (BSD). |
| memmem() | Find memory in memory, forward (BSD). |
| strchr() | Find character within string, forward. |
| strnchr() | Find character within string, forward, limit length. |
| strrchr() | Find character within string, reverse. |
| strlen() | Calculate length of string. |
| strnlen() | Calculate length of string, limit length (POSIX.1). |
| strnlen_s() | Calculate length of string, limit length (C11). |
| strstr() | Find string within string, forward. |
| strnstr() | Find string within string, forward, limit length (BSD). |
| strcasestr() | Find string within string, forward, ignore case (BSD). |
| strncasestr() | Find string within string, forward, ignore case, limit length (BSD). |
| strpbrk() | Find first occurrence of characters within string. |
| strspn() | Compute size of string prefixed by a set of characters. |
| strcspn() | Compute size of string not prefixed by a set of characters. |
| strtok() | Break string into tokens. |
| strtok_r() | Break string into tokens, restartable (POSIX.1). |
| strsep() | Break string into tokens (BSD). |
memchr()
Description
Find character in memory, forward.
Prototype
void *memchr(const void * s,
int c,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to object to search. |
| c | Character to search for. |
| n | Number of characters in object to search. |
Return value
| = NULL | c does not occur in the object. |
| ≠ NULL | Pointer to the located character. |
Additional information
Locates the first occurrence of c (converted to an unsigned char)
in the initial n characters (each interpreted as unsigned char)
of the object pointed to by s. Unlike strchr(), memchr() does
not terminate a search when a null character is found in the object
pointed to by s.
Thread safety
Safe.
memrchr()
Description
Find character in memory, reverse (BSD).
Prototype
void *memrchr(const void * s,
int c,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to object to search. |
| c | Character to search for. |
| n | Number of characters in object to search. |
Return value
Returns a pointer to the located character, or a null pointer
if c does not occur in the octet string.
Additional information
Locates the last occurrence of c (converted to a char)
in the octet string pointed to by s.
Conformance
Commonly found in Linux and BSD C libraries.
Thread safety
Safe.
memmem()
Description
Find memory in memory, forward (BSD).
Prototype
void *memmem(const void * s1,
size_t n1,
const void * s2,
size_t n2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to object to search. |
| n1 | Number of characters to search in s1. |
| s2 | Pointer to object to search for. |
| n2 | Number of characters to search from s2. |
Return value
| = NULL | (s2, n2) does not occur in (s1, n1). |
| ≠ NULL | Pointer to the first occurrence of (s2, n2) in (s1, n1). |
Additional information
Locates the first occurrence of the octet string s2 of length n2
in the octet string s1 of length n1.
Conformance
Commonly found in Linux and BSD C libraries.
Thread safety
Safe.
strchr()
Description
Find character within string, forward.
Prototype
char *strchr(const char * s,
int c);
Parameters
| Parameter | Description |
|---|
| s | String to search. |
| c | Character to search for. |
Return value
Returns a pointer to the located character, or a null pointer
if c does not occur in the string.
Additional information
Locates the first occurrence of c (converted to a char)
in the string pointed to by s. The terminating null character
is considered to be part of the string.
Thread safety
Safe.
strnchr()
Description
Find character within string, forward, limit length.
Prototype
char *strnchr(const char * s,
size_t n,
int c);
Parameters
| Parameter | Description |
|---|
| s | String to search. |
| n | Number of characters to search. |
| c | Character to search for. |
Return value
Returns a pointer to the located character, or a null pointer
if c does not occur in the string.
Additional information
Searches not more than n characters to locate the first occurrence
of c (converted to a char) in the string pointed to by s. The
terminating null character is considered to be part of the string.
Thread safety
Safe.
strrchr()
Description
Find character within string, reverse.
Prototype
char *strrchr(const char * s,
int c);
Parameters
| Parameter | Description |
|---|
| s | String to search. |
| c | Character to search for. |
Return value
Returns a pointer to the located character, or a null pointer
if c does not occur in the string.
Additional information
Locates the last occurrence of c (converted to a char) in the
string pointed to by s. The terminating null character is
considered to be part of the string.
Thread safety
Safe.
strlen()
Description
Calculate length of string.
Prototype
size_t strlen(const char * s);
Parameters
| Parameter | Description |
|---|
| s | Pointer to zero-terminated string. |
Return value
Returns the length of the string pointed to by s, that
is the number of characters that precede the terminating
null character.
Thread safety
Safe.
strnlen()
Description
Calculate length of string, limit length (POSIX.1).
Prototype
size_t strnlen(const char * s,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to string. |
| n | Maximum number of characters to examine. |
Return value
Returns the length of the string pointed to by s, up
to a maximum of n characters. strnlen() only examines
the first n characters of the string s.
Conformance
POSIX.1-2008.
Thread safety
Safe.
strnlen_s()
Description
Calculate length of string, limit length (C11).
Prototype
size_t strnlen_s(const char * s,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to string or NULL. |
| n | Maximum number of characters to examine. |
Return value
If s is NULL, returns 0. If s is nonnull, returns the length
of the string pointed to by s, up to a maximum of n characters.
strnlen_s() only examines the first n characters of the string s.
Additional information
The macro __STDC_WANT_LIB_EXT1__ must be set to 1 before
including <string.h> to access this function.
Conformance
ISO/IEC 9899:2011 (C11).
Thread safety
Safe.
strstr()
Description
Find string within string, forward.
Prototype
char *strstr(const char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | String to search. |
| s2 | String to search for. |
Return value
Returns a pointer to the located string, or a null pointer if
the string is not found. If s2 points to a string with zero
length, strstr() returns s1.
Additional information
Locates the first occurrence in the string pointed to by s1
of the sequence of characters (excluding the terminating null
character) in the string pointed to by s2.
Thread safety
Safe.
strnstr()
Description
Find string within string, forward, limit length (BSD).
Prototype
char *strnstr(const char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | String to search. |
| s2 | String to search for. |
| n | Maximum number of characters to search for. |
Return value
Returns a pointer to the located string, or a null pointer if
the string is not found. If s2 points to a string with zero
length, strnstr() returns s1.
Additional information
Searches at most n characters to locate the first occurrence
in the string pointed to by s1 of the sequence of characters (excluding the
terminating null character) in the string pointed to by s2.
Conformance
Commonly found in Linux and BSD C libraries.
Thread safety
Safe.
strcasestr()
Description
Find string within string, forward, ignore case (BSD).
Prototype
char *strcasestr(const char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | String to search. |
| s2 | String to search for. |
Return value
Returns a pointer to the located string, or a null pointer if
the string is not found. If s2 points to a string with zero length,
returns s1.
Additional information
Locates the first occurrence in the string pointed to by s1
of the sequence of characters (excluding the terminating null character) in
the string pointed to by s2 without regard to character case.
Conformance
This extension is commonly found in Linux and BSD C libraries.
Thread safety
Safe.
strncasestr()
Description
Find string within string, forward, ignore case, limit length (BSD).
Prototype
char *strncasestr(const char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | String to search. |
| s2 | String to search for. |
| n | Maximum number of characters to compare in s2. |
Return value
Returns a pointer to the located string, or a null pointer if
the string is not found. If s2 points to a string with zero length,
returns s1.
Additional information
Searches at most n characters to locate the first occurrence
in the string pointed to by s1 of the sequence of characters (excluding the
terminating null character) in the string pointed to by s2 without regard
to character case.
Conformance
This extension is commonly found in Linux and BSD C libraries.
Thread safety
Safe.
strpbrk()
Description
Find first occurrence of characters within string.
Prototype
char *strpbrk(const char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to string to search. |
| s2 | Pointer to string to search for. |
Return value
Returns a pointer to the first character, or a null pointer if
no character from s2 occurs in s1.
Additional information
Locates the first occurrence in the string pointed to by s1
of any character from the string pointed to by s2.
Thread safety
Safe.
strspn()
Description
Compute size of string prefixed by a set of characters.
Prototype
size_t strspn(const char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to zero-terminated string to search. |
| s2 | Pointer to zero-terminated acceptable-set string. |
Return value
Returns the length of the string pointed to by s1 which
consists entirely of characters from the string pointed
to by s2
Additional information
Computes the length of the maximum initial segment of the string
pointed to by s1 which consists entirely of characters from the string
pointed to by s2.
Thread safety
Safe.
strcspn()
Description
Compute size of string not prefixed by a set of characters.
Prototype
size_t strcspn(const char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to string to search. |
| s2 | Pointer to string containing characters to skip. |
Return value
Returns the length of the segment of string s1 prefixed
by characters from s2.
Additional information
Computes the length of the maximum initial segment of the string
pointed to by s1 which consists entirely of characters not from the string
pointed to by s2.
Thread safety
Safe.
strtok()
Description
Break string into tokens.
Prototype
char *strtok( char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to zero-terminated string to parse. |
| s2 | Pointer to zero-terminated set of separators. |
Return value
NULL if no further tokens else a pointer to the next token.
Additional information
A sequence of calls to strtok() breaks the string pointed to by s1
into a sequence of tokens, each of which is delimited by a character from the
string pointed to by s2. The first call in the sequence has a non-null
first argument; subsequent calls in the sequence have a null first argument.
The separator string pointed to by s2 may be different from call to call.
The first call in the sequence searches the string pointed to by s1
for the first character that is not contained in the current separator string
pointed to by s2. If no such character is found, then there are no tokens
in the string pointed to by s1 and strtok() returns a null pointer.
If such a character is found, it is the start of the first token.
strtok() then searches from there for a character that is contained in
the current separator string. If no such character is found, the current token
extends to the end of the string pointed to by s1, and subsequent searches
for a token will return a null pointer. If such a character is found, it is
overwritten by a null character, which terminates the current token. strtok()
saves a pointer to the following character, from which the next search for a
token will start.
Each subsequent call, with a null pointer as the value of the first argument,
starts searching from the saved pointer and behaves as described above.
Thread safety
Safe [if configured].
See also
strsep(), strtok_r().
strtok_r()
Description
Break string into tokens, restartable (POSIX.1).
Prototype
char *strtok_r( char * s1,
const char * s2,
char ** lasts);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to zero-terminated string to parse. |
| s2 | Pointer to zero-terminated set of separators. |
| lasts | Pointer to pointer to char that maintains parse state. |
Return value
NULL if no further tokens else a pointer to the next token.
Additional information
strtok_r() is a restartable version of the function strtok()
where the state is maintained in the object of type char *
pointed to by s3.
Conformance
POSIX.1-2008.
Thread safety
Safe.
See also
strtok()
strsep()
Description
Break string into tokens (BSD).
Prototype
char *strsep( char ** stringp,
const char * delim);
Parameters
| Parameter | Description |
|---|
| stringp | Pointer to pointer to zero-terminated string. |
| delim | Pointer to delimiter set string. |
Return value
See below.
Additional information
Locates, in the string referenced by *stringp, the first
occurrence of any character in the string delim (or the
terminating null character) and replaces it with a null
character. The location of the next character after the
delimiter character (or NULL, if the end of the string was
reached) is stored in *stringp. The original value
of *stringp is returned.
An empty field (that is, a character in the string delim occurs as the
first character of *stringp) can be detected by comparing the location
referenced by the returned pointer to the null wide character.
If *stringp is initially null, strsep() returns null.
Conformance
Commonly found in Linux and BSD C libraries.
Thread safety
Safe.
Miscellaneous functions
| Function | Description |
|---|
| strerror() | Decode error code. |
strerror()
Description
Decode error code.
Prototype
char *strerror(int num);
Parameters
| Parameter | Description |
|---|
| num | Error number. |
Return value
Returns a pointer to the message string.
The program must not modify the returned message string.
The message may be overwritten by a subsequent call to strerror().
Additional information
Maps the number in num to a message string. Typically,
the values for num come from errno, but strerror() can
map any value of type int to a message.
Thread safety
Safe.
<time.h>
Operations
| Function | Description |
|---|
| mktime() | Convert a struct tm to time_t. |
| difftime() | Calculate difference between two times. |
mktime()
Description
Convert a struct tm to time_t.
Prototype
time_t mktime(tm * tp);
Parameters
| Parameter | Description |
|---|
| tp | Pointer to time object. |
Return value
Number of seconds since UTC 1 January 1970 of the validated object.
Additional information
Validates (and updates) the object pointed to by tp to ensure that the
tm_sec, tm_min, tm_hour, and tm_mon fields are within the supported
integer ranges and the tm_mday, tm_mon and tm_year fields are
consistent. The validated object is converted to the number of seconds
since UTC 1 January 1970 and returned.
Thread safety
Safe.
difftime()
Description
Calculate difference between two times.
Prototype
double difftime(time_t time2,
time_t time1);
Parameters
| Parameter | Description |
|---|
| time2 | End time. |
| time1 | Start time. |
Return value
returns time2-time1 as a double precision number.
Thread safety
Safe.
Conversion functions
ctime()
Description
Convert time_t to a string.
Prototype
char *ctime(const time_t * tp);
Parameters
| Parameter | Description |
|---|
| tp | Pointer to time to convert. |
Return value
Pointer to zero-terminated converted string.
Additional information
Converts the time pointed to by tp to a null-terminated string.
Notes
The returned string is held in a static buffer: this function
is not thread safe.
Thread safety
Unsafe.
ctime_r()
Description
Convert time_t to a string, reentrant.
Prototype
char *ctime_r(const time_t * tp,
char * buf);
Parameters
| Parameter | Description |
|---|
| tp | Pointer to time to convert. |
| buf | Pointer to array of characters that receives the zero-terminated string; the array must be at least 26 characters in length. |
Return value
Returns the value of buf.
Additional information
Converts the time pointed to by tp to a null-terminated string.
Notes
The returned string is held in a static buffer: this function
is not thread safe.
Thread safety
Safe.
asctime()
Description
Convert time_t to a string.
Prototype
char *asctime(const tm * tp);
Parameters
| Parameter | Description |
|---|
| tp | Pointer to time to convert. |
Return value
Pointer to zero-terminated converted string.
Additional information
Converts the time pointed to by tp to a null-terminated string
of the form Sun Sep 16 01:03:52 1973. The returned string is
held in a static buffer.
Notes
The returned string is held in a static buffer: this function
is not thread safe.
Thread safety
Unsafe.
asctime_r()
Description
Convert time_t to a string, reentrant.
Prototype
char *asctime_r(const tm * tp,
char * buf);
Parameters
| Parameter | Description |
|---|
| tp | Pointer to time to convert. |
| buf | Pointer to array of characters that receives the zero-terminated string; the array must be at least 26 characters in length. |
Return value
Returns the value of buf.
Additional information
Converts the time pointed to by tp to a null-terminated string
of the Sun Sep 16 01:03:52 1973. The converted string is
written into the array pointed to by buf.
Thread safety
Safe.
gmtime()
Description
Convert time_t to struct tm.
Prototype
gmtime(const time_t * tp);
Parameters
| Parameter | Description |
|---|
| tp | Pointer to time to convert. |
Return value
Pointer to converted time.
Additional information
Converts the time pointed to by tp to a struct tm.
Notes
The returned pointer points to a static buffer: this function
is not thread safe.
Thread safety
Unsafe.
gmtime_r()
Description
Convert time_t to struct tm, reentrant.
Prototype
gmtime_r(const time_t * tp,
tm *tm);
Parameters
| Parameter | Description |
|---|
| tp | Pointer to time to convert. |
| tm | Pointer to object that receives the converted time. |
Return value
Returns tm.
Additional information
Converts the time pointed to by tp to a struct tm.
Thread safety
Safe.
localtime()
Description
Convert time to local time.
Prototype
localtime(const time_t * tp);
Parameters
| Parameter | Description |
|---|
| tp | Pointer to time to convert. |
Return value
Pointer to a statically-allocated object holding the
local time.
Additional information
Converts the time pointed to by tp to local time format.
Notes
The returned pointer points to a static object: this function
is not thread safe.
Thread safety
Unsafe.
localtime_r()
Description
Convert time to local time, reentrant.
Prototype
localtime_r(const time_t * tp,
tm *tm);
Parameters
| Parameter | Description |
|---|
| tp | Pointer to time to convert. |
| tm | Pointer to object that receives the converted local time. |
Return value
Returns tm.
Additional information
Converts the time pointed to by tp to local time format and
writes it to the object pointed to by tm.
Thread safety
Safe.
strftime()
Description
Convert time to a string.
Prototype
size_t strftime( char * s,
size_t smax,
const char * fmt,
const tm * tp);
Parameters
| Parameter | Description |
|---|
| s | Pointer to object that receives the converted string. |
| smax | Maximum number of characters written to the array pointed to by s. |
| fmt | Pointer to zero-terminated format control string. |
| tp | Pointer to time to convert. |
Return value
Returns the name of the current locale.
Additional information
Formats the time pointed to by tp to a null-terminated string of maximum
size smax-1 into the pointed to by *s based on the fmt format string.
The format string consists of conversion specifications and ordinary
characters. Conversion specifications start with a “%” character followed
by an optional “#” character.
The following conversion specifications are supported:
| Specification | Description |
|---|
| %a | Abbreviated weekday name |
| %A | Full weekday name |
| %b | Abbreviated month name |
| %B | Full month name |
| %c | Date and time representation appropriate for locale |
| %#c | Date and time formatted as “%A, %B %#d, %Y, %H:%M:%S” (Microsoft extension) |
| %C | Century number |
| %d | Day of month as a decimal number [01,31] |
| %#d | Day of month without leading zero [1,31] |
| %D | Date in the form %m/%d/%y (POSIX.1-2008 extension) |
| %e | Day of month [ 1,31], single digit preceded by space |
| %F | Date in the format %Y-%m-%d |
| %h | Abbreviated month name as %b |
| %H | Hour in 24-hour format [00,23] |
| %#H | Hour in 24-hour format without leading zeros [0,23] |
| %I | Hour in 12-hour format [01,12] |
| %#I | Hour in 12-hour format without leading zeros [1,12] |
| %j | Day of year as a decimal number [001,366] |
| %#j | Day of year as a decimal number without leading zeros [1,366] |
| %k | Hour in 24-hour clock format [ 0,23] (POSIX.1-2008 extension) |
| %l | Hour in 12-hour clock format [ 0,12] (POSIX.1-2008 extension) |
| %m | Month as a decimal number [01,12] |
| %#m | Month as a decimal number without leading zeros [1,12] |
| %M | Minute as a decimal number [00,59] |
| %#M | Minute as a decimal number without leading zeros [0,59] |
| %n | Insert newline character (POSIX.1-2008 extension) |
| %p | Locale’s a.m or p.m indicator for 12-hour clock |
| %r | Time as %I:%M:%s %p (POSIX.1-2008 extension) |
| %R | Time as %H:%M (POSIX.1-2008 extension) |
| %S | Second as a decimal number [00,59] |
| %t | Insert tab character (POSIX.1-2008 extension) |
| %T | Time as %H:%M:%S |
| %#S | Second as a decimal number without leading zeros [0,59] |
| %U | Week of year as a decimal number [00,53], Sunday is first day of the week |
| %#U | Week of year as a decimal number without leading zeros [0,53], Sunday is first day of the week |
| %w | Weekday as a decimal number [0,6], Sunday is 0 |
| %W | Week number as a decimal number [00,53], Monday is first day of the week |
| %#W | Week number as a decimal number without leading zeros [0,53], Monday is first day of the week |
| %x | Locale’s date representation |
| %#x | Locale’s long date representation |
| %X | Locale’s time representation |
| %y | Year without century, as a decimal number [00,99] |
| %#y | Year without century, as a decimal number without leading zeros [0,99] |
| %Y | Year with century, as decimal number |
| %z,%Z | Timezone name or abbreviation |
| %% | % |
Thread safety
Safe [if configured].
strftime_l()
Description
Convert time to a string.
Prototype
size_t strftime_l( char * s,
size_t smax,
const char * fmt,
const tm * tp,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| s | Pointer to object that receives the converted string. |
| smax | Maximum number of characters written to the array pointed to by s. |
| fmt | Pointer to zero-terminated format control string. |
| tp | Pointer to time to convert. |
| loc | Locale to use for conversion. |
Return value
Returns the name of the current locale.
Additional information
Formats the time pointed to by tp to a null-terminated string of maximum
size smax-1 into the pointed to by *s based on the fmt format string and
using the locale loc.
The format string consists of conversion specifications and ordinary
characters. Conversion specifications start with a “%” character followed
by an optional “#” character.
See strftime() for a description of the format conversion specifications.
Thread safety
Safe.
<wchar.h>
Copying functions
wmemset()
Description
Set memory to wide character.
Prototype
wchar_t *wmemset(wchar_t * s,
wchar_t c,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to destination object. |
| c | Wide character to copy. |
| n | Length of destination object in wide characters. |
Return value
Returns s.
Additional information
Copies the value of c into each of the first n
wide characters of the object pointed to by s.
Thread safety
Safe.
wmemcpy()
Description
Copy memory.
Prototype
wchar_t *wmemcpy( wchar_t * s1,
const wchar_t * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination object. |
| s2 | Pointer to source object. |
| n | Number of wide characters to copy. |
Return value
Returns the value of s1.
Additional information
Copies n wide characters from the object pointed to by s2
into the object pointed to by s1. The behavior of wmemcpy() is
undefined if copying takes place between objects that overlap.
Thread safety
Safe.
wmemccpy()
Description
Copy memory, specify terminator (POSIX.1).
Prototype
wchar_t *wmemccpy( wchar_t * s1,
const wchar_t * s2,
wchar_t c,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination object. |
| s2 | Pointer to source object. |
| c | Character that terminates copy. |
| n | Maximum number of characters to copy. |
Return value
Returns a pointer to the wide character immediately following c
in s1, or NULL if c was not found in the first n wide characters
of s2.
Additional information
Copies at most n wide characters from the object pointed to by
s2 into the object pointed to by s1. The copying stops as soon
as n wide characters are copied or the wide character c is copied
into the destination object pointed to by s1.
The behavior of wmemccpy() is undefined if copying takes place
between objects that overlap.
Notes
Conforms to POSIX.1-2008.
Thread safety
Safe.
wmempcpy()
Description
Copy memory (GNU).
Prototype
wchar_t *wmempcpy( wchar_t * s1,
const wchar_t * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination object. |
| s2 | Pointer to source object. |
| n | Number of wide characters to copy. |
Return value
Returns a pointer to the wide character immediately following
the final wide character written into s1.
Additional information
Copies n wide characters from the object pointed to by s2
into the object pointed to by s1. The behavior of wmempcpy() is
undefined if copying takes place between objects that overlap.
Notes
This is an extension found in GNU libc.
Thread safety
Safe.
wmemmove()
Description
Copy memory, tolerate overlaps.
Prototype
wchar_t *wmemmove( wchar_t * s1,
const wchar_t * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination object. |
| s2 | Pointer to source object. |
| n | Number of wide characters to copy. |
Return value
Returns the value of s1.
Additional information
Copies n wide characters from the object pointed to by s2
into the object pointed to by s1 ensuring that if s1 and s2
overlap, the copy works correctly. Copying takes place as if
the n wide characters from the object pointed to by s2 are
first copied into a temporary array of n wide characters that
does not overlap the objects pointed to by s1 and s2, and
then the n wide characters from the temporary array are
copied into the object pointed to by s1.
Thread safety
Safe.
wcscpy()
Description
Copy string.
Prototype
wchar_t *wcscpy( wchar_t * s1,
const wchar_t * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string to copy to. |
| s2 | Pointer to wide string to copy. |
Return value
Returns the value of s1.
Additional information
Copies the wide string pointed to by s2 (including the terminating
null wide character) into the array pointed to by s1. The behavior of
wcscpy() is undefined if copying takes place between objects that
overlap.
Thread safety
Safe.
wcsncpy()
Description
Copy string, limit length.
Prototype
wchar_t *wcsncpy( wchar_t * s1,
const wchar_t * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string to copy to. |
| s2 | Pointer to wide string to copy. |
| n | Maximum number of wide characters to copy. |
Return value
Returns the value of s1.
Additional information
Copies not more than n wide characters from the array pointed
to by s2 to the array pointed to by s1. Wide characters that follow
a null wide character in s2 are not copied. The behavior of wcsncpy()
is undefined if copying takes place between objects that overlap. If the array
pointed to by s2 is a wide string that is shorter than n wide characters,
null wide characters are appended to the copy in the array pointed to by s1,
until n characters in all have been written.
Notes
No wide null character is implicitly appended to the end of s1, so s1 will only be
terminated by a wide null character if the length of the wide string pointed to by s2 is
less than n.
Thread safety
Safe.
wcslcpy()
Description
Copy string, limit length, always zero terminate (BSD).
Prototype
size_t wcslcpy( wchar_t * s1,
const wchar_t * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string to copy to. |
| s2 | Pointer to wide string to copy. |
| n | Maximum number of wide characters, including terminating null, in s1. |
Return value
Returns the number of wide characters it tried to copy, which is
the length of the wide string s2 or n, whichever is smaller.
Additional information
Copies up to n-1 wide characters from the wide string pointed to by
s2 into the array pointed to by s1 and always terminates
the result with a null character.
The behavior of strlcpy() is undefined if copying takes place between
objects that overlap.
Notes
Commonly found in BSD libraries and contrasts with wcsncpy()
in that the resulting string is always terminated with a null
wide character.
Thread safety
Safe.
wcscat()
Description
Concatenate strings.
Prototype
wchar_t *wcscat( wchar_t * s1,
const wchar_t * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Zero-terminated wide string to append to. |
| s2 | Zero-terminated wide string to append. |
Return value
Returns the value of s1.
Additional information
Appends a copy of the wide string pointed to by s2 (including
the terminating null wide character) to the end of the wide string
pointed to by s1. The initial character of s2 overwrites the null
wide character at the end of s1. The behavior of wcscat() is undefined
if copying takes place between objects that overlap.
Thread safety
Safe.
wcsncat()
Description
Concatenate strings, limit length.
Prototype
wchar_t *wcsncat( wchar_t * s1,
const wchar_t * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Wide string to append to. |
| s2 | Wide string to append. |
| n | Maximum number of wide characters in s1. |
Return value
Returns the value of s1.
Additional information
Appends not more than n wide characters from the array pointed
to by s2 to the end of the wide string pointed to by s1. A null wide character
in s1 and wide characters that follow it are not appended. The initial wide character
of s2 overwrites the null wide character at the end of s1. A terminating
wide null character is always appended to the result. The behavior of wcsncat()
is undefined if copying takes place between objects that overlap.
Thread safety
Safe.
wcslcat()
Description
Concatenate strings, limit length, always zero terminate (BSD).
Prototype
size_t wcslcat( char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string to append to. |
| s2 | Pointer to wide string to append. |
| n | Maximum number of characters, including terminating wide null, in s1. |
Return value
Returns the number of wide characters it tried to copy, which is
the sum of the lengths of the wide strings s1 and s2 or n,
whichever is smaller.
Additional information
Appends no more than n-strlen(s1}-1 wide characters pointed to by s2 into
the array pointed to by s1 and always terminates the result with a
wide null character if n is greater than zero. Both the wide strings s1 and
s2 must be terminated with a wide null character on entry to wcslcat()
and a character position for the terminating wide null should be included
in n.
The behavior of wcslcat() is undefined if copying takes place between
objects that overlap.
Notes
Commonly found in BSD libraries.
Thread safety
Safe.
wcsdup()
Description
Duplicate string (POSIX.1).
Prototype
wchar_t *wcsdup(const wchar_t * s);
Parameters
| Parameter | Description |
|---|
| s | Pointer to wide string to duplicate. |
Return value
Returns a pointer to the new wide string or a null pointer if the
new wide string cannot be created. The returned pointer can be passed
to free().
Additional information
Duplicates the wide string pointed to by s by using malloc() to
allocate memory for a copy of s and then copies s, including the
terminating null, to that memory
Notes
Conforms to POSIX.1-2008 and SC22 TR 24731-2.
Thread safety
Safe.
wcsndup()
Description
Duplicate string, limit length (GNU).
Prototype
wchar_t *wcsndup(const wchar_t * s,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to wide string to duplicate. |
| n | Maximum number of wide characters to duplicate. |
Return value
Returns a pointer to the new wide string or a null pointer if the
new wide string cannot be created. The returned pointer can be
passed to free().
Additional information
Duplicates at most n wide characters from the the string pointed to
by s by using malloc() to allocate memory for a copy of s.
If the length of string pointed to by s is greater than n wide characters,
only n wide characters will be duplicated. If n is greater than the length of
the wide string pointed to by s, all characters in the string are copied into the
allocated array including the terminating null character.
Notes
This is a GNU extension.
Thread safety
Safe.
wcsxfrm()
Description
Transform strings.
Prototype
size_t wcsxfrm( wchar_t * s1,
const wchar_t * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to destination array. |
| s2 | Pointer to source string. |
| n | Maximum number of characters in the destination array. |
Return value
Returns the length of the transformed string. If the value
returned is n or more, the contents of the array pointed to
by s1 are undefined.
Thread safety
Safe.
Comparison functions
wmemcmp()
Description
Compare memory.
Prototype
int wmemcmp(const wchar_t * s1,
const wchar_t * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to object #1. |
| s2 | Pointer to object #2. |
| n | Number of wide characters to compare. |
Return value
| < 0 | s1 is less than s2. |
| = 0 | s1 is equal to s2. |
| > 0 | s1 is greater than to s2. |
Additional information
Compares the first n wide characters of the object pointed
to by s1 to the first n wide characters of the object pointed to by
s2. wmemcmp() returns an integer greater than, equal to, or less
than zero as the object pointed to by s1 is greater than, equal to,
or less than the object pointed to by s2.
Thread safety
Safe.
wcscmp()
Description
Compare strings.
Prototype
int wcscmp(const wchar_t * s1,
const wchar_t * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string #1. |
| s2 | Pointer to wide string #2. |
Return value
Returns an integer greater than, equal to, or less than zero,
if the null-terminated wide string pointed to by s1 is greater than,
equal to, or less than the null-terminated wide string pointed to
by s2.
Thread safety
Safe.
wcsncmp()
Description
Compare strings, limit length.
Prototype
int wcsncmp(const wchar_t * s1,
const wchar_t * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string #1. |
| s2 | Pointer to wide string #2. |
| n | Maximum number of wide characters to compare. |
Return value
Returns an integer greater than, equal to, or less than zero,
if the possibly null-terminated array pointed to by s1 is greater than,
equal to, or less than the possibly null-terminated array pointed to by s2.
Additional information
Compares not more than n wide characters from the array pointed
to by s1 to the array pointed to by s2. Wide characters that follow
a null wide character are not compared.
Thread safety
Safe.
wcscasecmp()
Description
Compare strings, ignore case (POSIX.1).
Prototype
int wcscasecmp(const char * s1,
const char * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string #1. |
| s2 | Pointer to wide string #2. |
Return value
| < 0 | s1 is less than s2. |
| = 0 | s1 is equal to s2. |
| > 0 | s1 is greater than to s2. |
Additional information
Compares the wide string pointed to by s1 to the wide string pointed
to by s2 ignoring differences in case.
wcscasecmp() returns an integer greater than, equal to, or
less than zero if the wide string pointed to by s1 is greater
than, equal to, or less than the wide string pointed to by s2.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
wcsncasecmp()
Description
Compare strings, ignore case, limit length (POSIX.1).
Prototype
int wcsncasecmp(const char * s1,
const char * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string #1. |
| s2 | Pointer to wide string #2. |
| n | Maximum number of wide characters to compare. |
Return value
| < 0 | s1 is less than s2. |
| = 0 | s1 is equal to s2. |
| > 0 | s1 is greater than to s2. |
Additional information
Compares not more than n wide characters from the array pointed
to by s1 to the array pointed to by s2 ignoring differences in case.
Characters that follow a wide null character are not compared.
strncasecmp() returns an integer greater than, equal to, or less than zero,
if the possibly null-terminated array pointed to by s1 is greater than,
equal to, or less than the possibly null-terminated array pointed to by s2.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
wcscoll()
Description
Collate strings.
Prototype
int wcscoll(const wchar_t * s1,
const wchar_t * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string #1. |
| s2 | Pointer to wide string #2. |
Return value
Returns an integer greater than, equal to, or less than zero,
if the null-terminated wide string pointed to by s1 is greater than,
equal to, or less than the null-terminated wide string pointed to
by s2.
Thread safety
Safe.
Search functions
| Function | Description |
|---|
| wmemchr() | Find character in memory, forward. |
| wcschr() | Find character within string, forward. |
| wcsnchr() | Find character within string, forward, limit length. |
| wcsrchr() | Find character within string, reverse. |
| wcslen() | Calculate length of string. |
| wcsnlen() | Calculate length of string, limit length (POSIX.1). |
| wcsstr() | Find string within string, forward. |
| wcsnstr() | Find string within string, forward, limit length (BSD). |
| wcspbrk() | Find first occurrence of characters within string. |
| wcsspn() | Compute size of string prefixed by a set of characters. |
| wcscspn() | Compute size of string not prefixed by a set of characters. |
| wcstok() | Break string into tokens. |
| wcssep() | Break string into tokens (BSD). |
wmemchr()
Description
Find character in memory, forward.
Prototype
wchar_t *wmemchr(const wchar_t * s,
wchar_t c,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to object to search. |
| c | Wide character to search for. |
| n | Number of wide characters in object to search. |
Return value
| = NULL | c does not occur in the object. |
| ≠ NULL | Pointer to the located wide character. |
Additional information
Locates the first occurrence of c in the initial n wide characters
of the object pointed to by s. Unlike wcschr(), wmemchr() does
not terminate a search when a null wide character is found in the
object pointed to by s.
Thread safety
Safe.
wcschr()
Description
Find character within string, forward.
Prototype
wchar_t *wcschr(const wchar_t * s,
wchar_t c);
Parameters
| Parameter | Description |
|---|
| s | Wide string to search. |
| c | Wide character to search for. |
Return value
Returns a pointer to the located wide character, or a null pointer
if c does not occur in the wide string.
Additional information
Locates the first occurrence of c in the wide string pointed to
by s. The terminating wide null character is considered to be
part of the string.
Thread safety
Safe.
wcsnchr()
Description
Find character within string, forward, limit length.
Prototype
wchar_t *wcsnchr(const wchar_t * s,
size_t n,
wchar_t c);
Parameters
| Parameter | Description |
|---|
| s | Pointer to wide string to search. |
| n | Number of wide characters to search. |
| c | Wide character to search for. |
Return value
Returns a pointer to the located wide character, or a null pointer
if c does not occur in the string.
Additional information
Searches not more than n wide characters to locate the first occurrence
of c in the wide string pointed to by s. The terminating wide null
character is considered to be part of the wide string.
Thread safety
Safe.
wcsrchr()
Description
Find character within string, reverse.
Prototype
wchar_t *wcsrchr(const wchar_t * s,
wchar_t c);
Parameters
| Parameter | Description |
|---|
| s | Pointer to wide string to search. |
| c | Wide character to search for. |
Return value
Returns a pointer to the located wide character, or a null pointer
if c does not occur in the string.
Additional information
Locates the last occurrence of c in the wide string pointed
to by s. The terminating wide null character is considered to
be part of the string.
Thread safety
Safe.
wcslen()
Description
Calculate length of string.
Prototype
size_t wcslen(const wchar_t * s);
Parameters
| Parameter | Description |
|---|
| s | Pointer to zero-terminated wide string. |
Return value
Returns the length of the wide string pointed to by s, that
is the number of wide characters that precede the terminating
wide null character.
Thread safety
Safe.
wcsnlen()
Description
Calculate length of string, limit length (POSIX.1).
Prototype
size_t wcsnlen(const wchar_t * s,
size_t n);
Parameters
| Parameter | Description |
|---|
| s | Pointer to wide string. |
| n | Maximum number of wide characters to examine. |
Return value
Returns the length of the wide string pointed to by s, up
to a maximum of n wide characters. wcsnlen() only examines
the first n wide characters of the string s.
Notes
Conforms to POSIX.1-2008.
Thread safety
Safe.
wcsstr()
Description
Find string within string, forward.
Prototype
wchar_t *wcsstr(const wchar_t * s1,
const wchar_t * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string to search. |
| s2 | Pointer to wide string to search for. |
Return value
Returns a pointer to the located wide string, or a null pointer if
the wide string is not found. If s2 points to a wide string with zero
length, wcsstr() returns s1.
Additional information
Locates the first occurrence in the wide string pointed to by s1
of the sequence of wide characters (excluding the terminating null
wide character) in the wide string pointed to by s2.
Thread safety
Safe.
wcsnstr()
Description
Find string within string, forward, limit length (BSD).
Prototype
wchar_t *wcsnstr(const wchar_t * s1,
const wchar_t * s2,
size_t n);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string to search. |
| s2 | Pointer to wide string to search for. |
| n | Maximum number of characters to search for. |
Return value
Returns a pointer to the located wide string, or a null pointer if
the wide string is not found. If s2 points to a wide string with zero
length, wcsnstr() returns s1.
Additional information
Searches at most n wide characters to locate the first occurrence
in the wide string pointed to by s1 of the sequence of wide characters
(excluding the terminating wide null character) in the string pointed
to by s2.
Notes
Commonly found in Linux and BSD C libraries.
Thread safety
Safe.
wcspbrk()
Description
Find first occurrence of characters within string.
Prototype
wchar_t *wcspbrk(const wchar_t * s1,
const wchar_t * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string to search. |
| s2 | Pointer to wide string to search for. |
Return value
Returns a pointer to the first wide character, or a null pointer if
no wide character from s2 occurs in s1.
Additional information
Locates the first occurrence in the wide string pointed to by s1
of any wide character from the string pointed to by s2.
Thread safety
Safe.
wcsspn()
Description
Compute size of string prefixed by a set of characters.
Prototype
size_t wcsspn(const wchar_t * s1,
const wchar_t * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to zero-terminated wide string to search. |
| s2 | Pointer to zero-terminated acceptable-set wide string. |
Return value
Returns the length of the wide string pointed to by s1 which
consists entirely of wide characters from the wide string
pointed to by s2
Additional information
Computes the length of the maximum initial segment of the wide string
pointed to by s1 which consists entirely of wide characters from
the string pointed to by s2.
Thread safety
Safe.
wcscspn()
Description
Compute size of string not prefixed by a set of characters.
Prototype
size_t wcscspn(const wchar_t * s1,
const wchar_t * s2);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to wide string to search. |
| s2 | Pointer to wide string containing characters to skip. |
Return value
Returns the length of the segment of wide string s1 prefixed
by wide characters from s2.
Additional information
Computes the length of the maximum initial segment of the wide string
pointed to by s1 which consists entirely of wide characters not from
the wide string pointed to by s2.
Thread safety
Safe.
wcstok()
Description
Break string into tokens.
Prototype
wchar_t *wcstok( wchar_t * s1,
const wchar_t * s2,
wchar_t ** ptr);
Parameters
| Parameter | Description |
|---|
| s1 | Pointer to zero-terminated wide string to parse. |
| s2 | Pointer to zero-terminated set of separators. |
| ptr | Pointer to object that maintains parse state. |
Return value
NULL if no further tokens else a pointer to the next token.
Additional information
A sequence of calls to wcstok() breaks the wide string pointed to by s1
into a sequence of tokens, each of which is delimited by a wide character from the
wide string pointed to by s2. The first call in the sequence has a non-null
first argument; subsequent calls in the sequence have a null first argument.
The separator wide string pointed to by s2 may be different from call to call.
The first call in the sequence searches the wide string pointed to by s1
for the wide first character that is not contained in the current separator wide string
pointed to by s2. If no such wide character is found, then there are no tokens
in the string pointed to by s1 and wcstok() returns a null pointer.
If such a wide character is found, it is the start of the first token.
wcstok() then searches from there for a wide character that is contained in
the current separator wide string. If no such wide character is found, the current token
extends to the end of the wide string pointed to by s1, and subsequent searches
for a token will return a null pointer. If such a wide character is found, it is
overwritten by a null wide character, which terminates the current token. wcstok()
saves a pointer to the following wide character, from which the next search for a
token will start.
Each subsequent call, with a null pointer as the value of the first argument,
starts searching from the saved pointer and behaves as described above.
Thread safety
Safe.
See also
wcssep().
wcssep()
Description
Break string into tokens (BSD).
Prototype
wchar_t *wcssep( wchar_t ** stringp,
const wchar_t * delim);
Parameters
| Parameter | Description |
|---|
| stringp | Pointer to pointer to zero-terminated wide string. |
| delim | Pointer to delimiter set wide string. |
Return value
See below.
Additional information
Locates, in the wide string referenced by *stringp, the first
occurrence of any wide character in the wide string delim (or the
terminating null character) and replaces it with a null
wide character. The location of the next wide character after the
delimiter wide character (or NULL, if the end of the wide string was
reached) is stored in *stringp. The original value
of *stringp is returned.
An empty field (that is, a wide character in the string delim occurs as the
first character of *stringp) can be detected by comparing the location
referenced by the returned pointer to the null wide character.
If *stringp is initially null, wcssep() returns null.
Notes
Commonly found in Linux and BSD C libraries.
Thread safety
Safe.
Multi-byte/wide string conversion functions
| Function | Description |
|---|
| mbsinit() | Query initial conversion state. |
| mbrlen() | Count number of bytes in multi-byte character, restartable. |
| mbrlen_l() | Count number of bytes in multi-byte character, restartable, per locale (POSIX.1). |
| mbrtowc() | Convert multi-byte character to wide character, restartable. |
| mbrtowc_l() | Convert multi-byte character to wide character, restartable, per locale (POSIX.1). |
| wctob() | Convert wide character to single-byte character. |
| wctob_l() | Convert wide character to single-byte character, per locale (POSIX.1). |
| wcrtomb() | Convert wide character to multi-byte character, restartable. |
| wcrtomb_l() | Convert wide character to multi-byte character, restartable, per locale (POSIX.1). |
| wcsrtombs() | Convert wide string to multi-byte string, restartable. |
| wcsrtombs_l() | Convert wide string to multi-byte string, restartable (POSIX.1). |
| wcsnrtombs() | Convert wide string to multi-byte string, restartable (POSIX.1). |
| wcsnrtombs_l() | Convert wide string to multi-byte string, restartable (POSIX.1). |
mbsinit()
Description
Query initial conversion state.
Prototype
int mbsinit(const mbstate_t * ps);
Parameters
| Parameter | Description |
|---|
| ps | Pointer to conversion state. |
Return value
Returns nonzero (true) if ps is a null pointer or if the
pointed-to object describes an initial conversion state;
otherwise, returns zero.
Thread safety
Safe.
mbrlen()
Description
Count number of bytes in multi-byte character, restartable.
Prototype
size_t mbrlen(const char * s,
size_t n,
mbstate_t * ps);
Parameters
| Parameter | Description |
|---|
| s | Pointer to multi-byte character. |
| n | Maximum number of bytes to examine. |
| ps | Pointer to multi-byte conversion state. |
Return value
Number of bytes in multi-byte character.
Additional information
Determines the number of bytes contained in the multi-byte
character pointed to by s in the current locale.
Except that except that the expression designated by ps is
evaluated only once, this function is equivalent to the call:
mbrtowc(NULL, s, n, ps != NULL ? ps : &internal);
where internal is the mbstate_t object for the mbrlen() function.
Thread safety
Safe [if configured].
See also
mbrlen_l(), mbrtowc()
mbrlen_l()
Description
Count number of bytes in multi-byte character, restartable, per locale (POSIX.1).
Prototype
size_t mbrlen_l(const char * s,
size_t n,
mbstate_t * ps,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| s | Pointer to multi-byte character. |
| n | Maximum number of bytes to examine. |
| ps | Pointer to multi-byte conversion state. |
| loc | Locale used for conversion. |
Return value
Number of bytes in multi-byte character.
Additional information
Determines the number of bytes contained in the multi-byte
character pointed to by s in the locale loc.
Except that except that the expression designated by ps is
evaluated only once, this function is equivalent to the call:
mbrtowc_l(NULL, s, n, ps != NULL ? ps : &internal, loc);
where internal is the mbstate_t object for the mbrlen() function,
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
See also
mbrlen_l(), mbrtowc()
mbrtowc()
Description
Convert multi-byte character to wide character, restartable.
Prototype
size_t mbrtowc( wchar_t * pwc,
const char * s,
size_t n,
mbstate_t * ps);
Parameters
| Parameter | Description |
|---|
| pwc | Pointer to object that receives the wide character. |
| s | Pointer to multi-byte character string. |
| n | Maximum number of bytes that will be examined. |
| ps | Pointer to multi-byte conversion state. |
Return value
If s is a null pointer, mbrtowc() is equivalent to
mbrtowc(NULL, “”, 1, ps), ignoring pwc and n.
If s is not null and the object that s points to is a
wide null character, mbrtowc() returns 0.
If s is not null and the object that s points to forms a valid
multi-byte character in the current locale with a most n bytes,
mbrtowc() returns the length in bytes of the multi-byte character
and stores that wide character to the object pointed to by pwc
(if pwc is not null).
If the object that s points to forms an incomplete, but possibly
valid, multi-byte character, mbrtowc() returns -2.
If the object that s points to does not form a partial multi-byte
character, mbrtowc() returns -1.
Additional information
Converts a single multi-byte character to a wide character in the
current locale.
Thread safety
Safe [if configured].
See also
mbtowc(), mbrtowc_l()
mbrtowc_l()
Description
Convert multi-byte character to wide character, restartable,
per locale (POSIX.1).
Prototype
size_t mbrtowc_l( wchar_t * pwc,
const char * s,
size_t n,
mbstate_t * ps,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| pwc | Pointer to object that receives the wide character. |
| s | Pointer to multi-byte character string. |
| n | Maximum number of bytes that will be examined. |
| ps | Pointer to multi-byte conversion state. |
| loc | Locale used for conversion. |
Return value
If s is a null pointer, mbrtowc() is equivalent to
mbrtowc(NULL, “”, 1, ps), ignoring pwc and n.
If s is not null and the object that s points to is a
wide null character, mbrtowc() returns 0.
If s is not null and the object that s points to forms a valid
multi-byte character in the locale loc with a most n bytes,
mbrtowc() returns the length in bytes of the multi-byte character
and stores that wide character to the object pointed to by pwc
(if pwc is not null).
If the object that s points to forms an incomplete, but possibly
valid, multi-byte character, mbrtowc() returns -2.
If the object that s points to does not form a partial multi-byte
character, mbrtowc() returns -1.
Additional information
Converts a single multi-byte character to a wide character in the
locale loc.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
See also
mbtowc(), mbrtowc_l()
wctob()
Description
Convert wide character to single-byte character.
Prototype
int wctob(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Character to convert. |
Return value
Returns EOF if c does not correspond to a multi-byte character
with length one in the initial shift state in the current locale.
Otherwise, it returns the single-byte representation
of that character as an unsigned char converted to an int.
Additional information
Determines whether c corresponds to a member of the extended
character set whose multi-byte character representation is a
single byte in the current locale when in the initial shift state.
Thread safety
Safe [if configured].
wctob_l()
Description
Convert wide character to single-byte character, per locale (POSIX.1).
Prototype
int wctob_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Character to convert. |
| loc | Locale used for conversion. |
Return value
Returns EOF if c does not correspond to a multi-byte character
with length one in the initial shift state in the locale loc.
Otherwise, it returns the single-byte representation
of that character as an unsigned char converted to an int.
Additional information
Determines whether c corresponds to a member of the extended
character set whose multi-byte character representation is a
single byte in the locale loc when in the initial shift state.
Thread safety
Safe.
wcrtomb()
Description
Convert wide character to multi-byte character, restartable.
Prototype
size_t wcrtomb(char * s,
wchar_t wc,
mbstate_t * ps);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the multi-byte character. |
| wc | Wide character to convert. |
| ps | Pointer to multi-byte conversion state. |
Return value
Returns the number of bytes stored in the array object. When wc is
not a valid wide character, an encoding error occurs: wcrtomb() stores
the value of the macro EILSEQ in errno and returns (size_t)(-1); the
conversion state is unspecified.
Additional information
If s is a null pointer, wcrtomb() is equivalent to the call
wcrtomb(buf, 0, ps) where buf is an internal buffer.
If s is not a null pointer, wcrtomb() determines the number of bytes needed
to represent the multi-byte character that corresponds to the wide character given
by wc in the locale loc, and stores the multi-byte character representation
in the array whose first element is pointed to by s. At most MB_CUR_MAX bytes are
stored. If wc is a null wide character, a null byte is stored; the resulting
state described is the initial conversion state.
Thread safety
Safe [if configured].
wcrtomb_l()
Description
Convert wide character to multi-byte character, restartable,
per locale (POSIX.1).
Prototype
size_t wcrtomb_l(char * s,
wchar_t wc,
mbstate_t * ps,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| s | Pointer to array that receives the multi-byte character. |
| wc | Wide character to convert. |
| ps | Pointer to multi-byte conversion state. |
| loc | Locale used for conversion. |
Return value
Returns the number of bytes stored in the array object. When wc is
not a valid wide character, an encoding error occurs: wcrtomb_l() stores
the value of the macro EILSEQ in errno and returns (size_t)(-1); the
conversion state is unspecified.
Additional information
If s is a null pointer, wcrtomb() is equivalent to the call
wcrtomb(buf, 0, ps) where buf is an internal buffer.
If s is not a null pointer, wcrtomb() determines the number of bytes needed
to represent the multi-byte character that corresponds to the wide character given
by wc in the current locale, and stores the multi-byte character representation
in the array whose first element is pointed to by s. At most MB_CUR_MAX bytes are
stored. If wc is a null wide character, a null byte is stored; the resulting
state described is the initial conversion state.
Thread safety
Safe.
wcsrtombs()
Description
Convert wide string to multi-byte string, restartable.
Prototype
size_t wcsrtombs( char * dst,
const wchar_t ** src,
size_t len,
mbstate_t * ps);
Parameters
| Parameter | Description |
|---|
| dst | Pointer to array that receives the multi-byte string. |
| src | Indirect pointer to wide character string being converted. |
| len | Maximum number of bytes to write into the array pointed to by dst. |
| ps | Pointer to multi-byte conversion state. |
Return value
If conversion stops because a wide character is reached that does not
correspond to a valid multi-byte character, an encoding error occurs:
wcsrtombs() stores the value of the macro EILSEQ in errno and returns
(size_t)(-1); the conversion state is unspecified. Otherwise, it returns
the number of bytes in the resulting multi-byte character sequence, not
including the terminating null character (if any).
Additional information
Converts a sequence of wide characters in the current locale from the
array indirectly pointed to by src into a sequence of corresponding
multi-byte characters that begins in the conversion state described by
the object pointed to by ps. If dst is not a null pointer, the converted
characters are then stored into the array pointed to by dst. Conversion
continues up to and including a terminating null wide character, which
is also stored.
Conversion stops earlier in two cases: when a wide character is reached
that does not correspond to a valid multi-byte character, or (if dst
is not a null pointer) when the next multi-byte character would exceed
the limit of len total bytes to be stored into the array pointed to by
dst. Each conversion takes place as if by a call to wcrtomb().
If dst is not a null pointer, the pointer object pointed to by src is
assigned either a null pointer (if conversion stopped due to reaching a
terminating null wide character) or the address just past the last wide
character converted (if any). If conversion stopped due to reaching a
terminating null wide character, the resulting state described is the
initial conversion state.
Thread safety
Safe [if configured].
wcsrtombs_l()
Description
Convert wide string to multi-byte string, restartable (POSIX.1).
Prototype
size_t wcsrtombs_l( char * dst,
const wchar_t ** src,
size_t len,
mbstate_t * ps,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| dst | Pointer to array that receives the multi-byte string. |
| src | Indirect pointer to wide character string being converted. |
| len | Maximum number of bytes to write into the array pointed to by dst. |
| ps | Pointer to multi-byte conversion state. |
| loc | Locale used for conversion. |
Return value
If conversion stops because a wide character is reached that does not
correspond to a valid multi-byte character, an encoding error occurs:
wcsrtombs() stores the value of the macro EILSEQ in errno and returns
(size_t)(-1); the conversion state is unspecified. Otherwise, it returns
the number of bytes in the resulting multi-byte character sequence, not
including the terminating null character (if any).
Additional information
Converts a sequence of wide characters in the locale loc from the
array indirectly pointed to by src into a sequence of corresponding
multi-byte characters that begins in the conversion state described by
the object pointed to by ps. If dst is not a null pointer, the converted
characters are then stored into the array pointed to by dst. Conversion
continues up to and including a terminating null wide character, which
is also stored.
Conversion stops earlier in two cases: when a wide character is reached
that does not correspond to a valid multi-byte character, or (if dst
is not a null pointer) when the next multi-byte character would exceed
the limit of len total bytes to be stored into the array pointed to by
dst. Each conversion takes place as if by a call to wcrtomb_l().
If dst is not a null pointer, the pointer object pointed to by src is
assigned either a null pointer (if conversion stopped due to reaching a
terminating null wide character) or the address just past the last wide
character converted (if any). If conversion stopped due to reaching a
terminating null wide character, the resulting state described is the
initial conversion state.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
wcsnrtombs()
Description
Convert wide string to multi-byte string, restartable (POSIX.1).
Prototype
size_t wcsnrtombs( char * dst,
const wchar_t ** src,
size_t nwc,
size_t len,
mbstate_t * ps);
Parameters
| Parameter | Description |
|---|
| dst | Pointer to array that receives the multi-byte string. |
| src | Indirect pointer to wide character string being converted. |
| nwc | Maximum number of wide characters to read from src. |
| len | Maximum number of bytes to write into the array pointed to by dst. |
| ps | Pointer to multi-byte conversion state. |
Return value
If conversion stops because a wide character is reached that does not
correspond to a valid multi-byte character, an encoding error occurs:
wcsrtombs() stores the value of the macro EILSEQ in errno and returns
(size_t)(-1); the conversion state is unspecified. Otherwise, it returns
the number of bytes in the resulting multi-byte character sequence, not
including the terminating null character (if any).
Additional information
Converts a sequence of wide characters in the locale loc from the
array indirectly pointed to by src into a sequence of corresponding
multi-byte characters that begins in the conversion state described by
the object pointed to by ps. If dst is not a null pointer, the converted
characters are then stored into the array pointed to by dst. Conversion
continues up to and including a terminating null wide character, which
is also stored.
Conversion stops earlier in two cases: when a wide character is reached
that does not correspond to a valid multi-byte character, or (if dst
is not a null pointer) when the next multi-byte character would exceed
the limit of len total bytes to be stored into the array pointed to by
dst. Each conversion takes place as if by a call to wcrtomb_l().
If dst is not a null pointer, the pointer object pointed to by src is
assigned either a null pointer (if conversion stopped due to reaching a
terminating null wide character) or the address just past the last wide
character converted (if any). If conversion stopped due to reaching a
terminating null wide character, the resulting state described is the
initial conversion state.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe [if configured].
wcsnrtombs_l()
Description
Convert wide string to multi-byte string, restartable (POSIX.1).
Prototype
size_t wcsnrtombs_l( char * dst,
const wchar_t ** src,
size_t nwc,
size_t len,
mbstate_t * ps,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| dst | Pointer to array that receives the multi-byte string. |
| src | Indirect pointer to wide character string being converted. |
| nwc | Maximum number of wide characters to read from src. |
| len | Maximum number of bytes to write into the array pointed to by dst. |
| ps | Pointer to multi-byte conversion state. |
| loc | Locale used for conversion. |
Return value
If conversion stops because a wide character is reached that does not
correspond to a valid multi-byte character, an encoding error occurs:
wcsrtombs() stores the value of the macro EILSEQ in errno and returns
(size_t)(-1); the conversion state is unspecified. Otherwise, it returns
the number of bytes in the resulting multi-byte character sequence, not
including the terminating null character (if any).
Additional information
Converts a sequence of wide characters in the locale loc from the
array indirectly pointed to by src into a sequence of corresponding
multi-byte characters that begins in the conversion state described by
the object pointed to by ps. If dst is not a null pointer, the converted
characters are then stored into the array pointed to by dst. Conversion
continues up to and including a terminating null wide character, which
is also stored.
Conversion stops earlier in two cases: when a wide character is reached
that does not correspond to a valid multi-byte character, or (if dst
is not a null pointer) when the next multi-byte character would exceed
the limit of len total bytes to be stored into the array pointed to by
dst. Each conversion takes place as if by a call to wcrtomb_l().
If dst is not a null pointer, the pointer object pointed to by src is
assigned either a null pointer (if conversion stopped due to reaching a
terminating null wide character) or the address just past the last wide
character converted (if any). If conversion stopped due to reaching a
terminating null wide character, the resulting state described is the
initial conversion state.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
<wctype.h>
Classification functions
| Function | Description |
|---|
| iswcntrl() | Is character a control? |
| iswcntrl_l() | Is character a control, per locale? (POSIX.1). |
| iswblank() | Is character a blank? |
| iswblank_l() | Is character a blank, per locale? (POSIX.1). |
| iswspace() | Is character a whitespace character? |
| iswspace_l() | Is character a whitespace character, per locale? (POSIX.1). |
| iswpunct() | Is character a punctuation mark? |
| iswpunct_l() | Is character a punctuation mark, per locale? (POSIX.1). |
| iswdigit() | Is character a decimal digit? |
| iswdigit_l() | Is character a decimal digit, per locale? (POSIX. |
| iswxdigit() | Is character a hexadecimal digit? |
| iswxdigit_l() | Is character a hexadecimal digit, per locale? (POSIX.1). |
| iswalpha() | Is character alphabetic? |
| iswalpha_l() | Is character alphabetic, per locale? (POSIX.1). |
| iswalnum() | Is character alphanumeric? |
| iswalnum_l() | Is character alphanumeric, per locale? (POSIX.1). |
| iswupper() | Is character an uppercase letter? |
| iswupper_l() | Is character an uppercase letter, per locale? (POSIX.1). |
| iswlower() | Is character a lowercase letter? |
| iswlower_l() | Is character a lowercase letter, per locale? (POSIX.1). |
| iswprint() | Is character printable? |
| iswprint_l() | Is character printable, per locale? (POSIX.1). |
| iswgraph() | Is character any printing character? |
| iswgraph_l() | Is character any printing character, per locale? (POSIX.1). |
| iswctype() | Construct character mapping. |
| iswctype_l() | Construct character mapping, per locale (POSIX.1). |
| wctype() | Construct character class. |
iswcntrl()
Description
Is character a control?
Prototype
int iswcntrl(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide 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].
iswcntrl_l()
Description
Is character a control, per locale? (POSIX.1).
Prototype
int iswcntrl_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide 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.
iswblank()
Description
Is character a blank?
Prototype
int iswblank(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide 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].
iswblank_l()
Description
Is character a blank, per locale? (POSIX.1).
Prototype
int iswblank_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide 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.
iswspace()
Description
Is character a whitespace character?
Prototype
int iswspace(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide 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].
iswspace_l()
Description
Is character a whitespace character, per locale? (POSIX.1).
Prototype
int iswspace_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide 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.
iswpunct()
Description
Is character a punctuation mark?
Prototype
int iswpunct(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide 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].
iswpunct_l()
Description
Is character a punctuation mark, per locale? (POSIX.1).
Prototype
int iswpunct_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide 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.
iswdigit()
Description
Is character a decimal digit?
Prototype
int iswdigit(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide 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].
iswdigit_l()
Description
Is character a decimal digit, per locale? (POSIX.1)
Prototype
int iswdigit_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide 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.
iswxdigit()
Description
Is character a hexadecimal digit?
Prototype
int iswxdigit(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide 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].
iswxdigit_l()
Description
Is character a hexadecimal digit, per locale? (POSIX.1).
Prototype
int iswxdigit_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide 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.
iswalpha()
Description
Is character alphabetic?
Prototype
int iswalpha(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide character to test. |
Return value
Returns true if the character c is alphabetic in the current locale.
That is, any character for which iswupper() or iswlower() returns true
is considered alphabetic in addition to any of the locale-specific set of
alphabetic characters for which none of iswcntrl(), iswdigit(), iswpunct(),
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].
iswalpha_l()
Description
Is character alphabetic, per locale? (POSIX.1).
Prototype
int iswalpha_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide character to test. |
| loc | Locale used to test c. |
Return value
Returns true if the wide character c is alphabetic in the locale loc.
That is, any character for which iswupper() or iswlower() returns true
is considered alphabetic in addition to any of the locale-specific set of
alphabetic characters for which none of iswcntrl_l(), iswdigit_l(),
iswpunct_l(), or iswspace_l() is true in the locale loc.
In the C locale, iswalpha_l() returns nonzero (true) if and only if
iswupper_l() or iswlower_l() return true for value of the argument c.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
iswalnum()
Description
Is character alphanumeric?
Prototype
int iswalnum(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide 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].
iswalnum_l()
Description
Is character alphanumeric, per locale? (POSIX.1).
Prototype
int iswalnum_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide 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.
iswupper()
Description
Is character an uppercase letter?
Prototype
int iswupper(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide 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].
iswupper_l()
Description
Is character an uppercase letter, per locale? (POSIX.1).
Prototype
int iswupper_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide 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.
iswlower()
Description
Is character a lowercase letter?
Prototype
int iswlower(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide 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].
iswlower_l()
Description
Is character a lowercase letter, per locale? (POSIX.1).
Prototype
int iswlower_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide 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.
iswprint()
Description
Is character printable?
Prototype
int iswprint(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide 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].
iswprint_l()
Description
Is character printable, per locale? (POSIX.1).
Prototype
int iswprint_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide 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.
iswgraph()
Description
Is character any printing character?
Prototype
int iswgraph(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide 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].
iswgraph_l()
Description
Is character any printing character, per locale? (POSIX.1).
Prototype
int iswgraph_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide 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.
iswctype()
Description
Construct character mapping.
Prototype
int iswctype(wint_t c,
wctype_t t);
Parameters
| Parameter | Description |
|---|
| c | Wide character to test. |
| t | Property to test, typically delivered by calling wctype(). |
Return value
Returns nonzero (true) if and only if the wide character c
has the property t in the current locale.
Additional information
Determines whether the wide character c has the
property described by t in the current locale.
Thread safety
Safe [if configured].
iswctype_l()
Description
Construct character mapping, per locale (POSIX.1).
Prototype
int iswctype_l(wint_t c,
wctype_t t,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide character to test. |
| t | Property to test, typically delivered by calling wctype_l(). |
| loc | Locale used for mapping. |
Return value
Returns nonzero (true) if and only if the wide character c
has the property t in the locale loc.
Additional information
Determines whether the wide character c has the
property described by t in the locale loc.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
wctype()
Description
Construct character class.
Prototype
wctype_t wctype(char const * name);
Parameters
| Parameter | Description |
|---|
| name | Name of mapping. |
Return value
Character class; zero if class unrecognized.
Additional information
Constructs a value of type wctype_t that describes a class
of wide characters identified by the string argument property.
If property identifies a valid class of wide characters in
the current locale, returns a nonzero value that is valid
as the second argument to iswctype(); otherwise, it returns
zero.
Notes
The only mappings supported are:
- “alnum”
- “alpha”,
- “blank”
- “cntrl”
- “digit”
- “graph”
- “lower”
- “print”
- “punct”
- “space”
- “upper”
- “xdigit”
Thread safety
Safe [if configured].
Conversion functions
| Function | Description |
|---|
| towupper() | Convert uppercase character to lowercase. |
| towupper_l() | Convert uppercase character to lowercase, per locale (POSIX.1). |
| towlower() | Convert uppercase character to lowercase. |
| towlower_l() | Convert uppercase character to lowercase, per locale (POSIX.1). |
| towctrans() | Translate character. |
| towctrans_l() | Translate character, per locale (POSIX.1). |
| wctrans() | Construct character mapping. |
| wctrans_l() | Construct character mapping, per locale (POSIX.1). |
towupper()
Description
Convert uppercase character to lowercase.
Prototype
wint_t towupper(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide character to convert. |
Return value
Converted wide character.
Additional information
Converts a lowercase letter to a corresponding uppercase letter.
If the argument c is a wide character for which iswlower() is true
and there are one or more corresponding wide characters, in the
current current locale, for which iswupper() is true, towupper()
returns one (and always the same one for any given locale) of the
corresponding wide characters; otherwise, c is returned unchanged.
Thread safety
Safe [if configured].
towupper_l()
Description
Convert uppercase character to lowercase, per locale (POSIX.1).
Prototype
wint_t towupper_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide character to convert. |
| loc | Locale used to convert c. |
Return value
Converted wide character.
Additional information
Converts a lowercase letter to a corresponding uppercase letter.
If the argument c is a wide character for which iswlower_l() is true
and there are one or more corresponding wide characters, in the
current locale loc, for which iswupper_l() is true, towupper_l()
returns one (and always the same one for any given locale) of the
corresponding wide characters; otherwise, c is returned unchanged.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
towlower()
Description
Convert uppercase character to lowercase.
Prototype
wint_t towlower(wint_t c);
Parameters
| Parameter | Description |
|---|
| c | Wide character to convert. |
Return value
Converted wide character.
Additional information
Converts an uppercase letter to a corresponding lowercase letter.
If the argument c is a wide character for which iswupper() is true and there
are one or more corresponding wide characters, in the current locale, for
which iswlower() is true, towlower() returns one (and always the same one
for any given locale) of the corresponding wide characters; otherwise, c is
returned unchanged.
Thread safety
Safe [if configured].
towlower_l()
Description
Convert uppercase character to lowercase, per locale (POSIX.1).
Prototype
wint_t towlower_l(wint_t c,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide character to convert. |
| loc | Locale used to convert c. |
Return value
Converted wide character.
Additional information
Converts an uppercase letter to a corresponding lowercase letter.
If the argument c is a wide character for which iswupper_l() is true
and there are one or more corresponding wide characters, in the locale
loc, for which iswlower_l() is true, towlower_l() returns one (and
always the same one for any given locale) of the corresponding wide
characters; otherwise, c is returned unchanged.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
towctrans()
Description
Translate character.
Prototype
wint_t towctrans(wint_t c,
wctrans_t t);
Parameters
| Parameter | Description |
|---|
| c | Wide character to convert. |
| t | Mapping to use for conversion. |
Return value
Converted wide character.
Additional information
Maps the wide character c using the mapping described by
t in the current locale.
Thread safety
Safe [if configured].
towctrans_l()
Description
Translate character, per locale (POSIX.1).
Prototype
wint_t towctrans_l(wint_t c,
wctrans_t t,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| c | Wide character to convert. |
| t | Mapping to use for conversion. |
| loc | Locale used for conversion. |
Return value
Converted wide character.
Additional information
Maps the wide character c using the mapping described by
t in the locale loc.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
wctrans()
Description
Construct character mapping.
Prototype
wctrans_t wctrans(const char * name);
Parameters
| Parameter | Description |
|---|
| name | Name of mapping. |
Return value
Transformation mapping; zero if mapping unrecognized.
Additional information
Constructs a value of type wctrans_t that describes a mapping
between wide characters identified by the string argument property.
If property identifies a valid mapping of wide characters in the
current locale, wctrans_l() returns a nonzero value that is valid as
the second argument to towctrans(); otherwise, it returns zero.
The only mappings supported are “tolower” and “toupper”.
Thread safety
Safe.
wctrans_l()
Description
Construct character mapping, per locale (POSIX.1).
Prototype
wctrans_t wctrans_l(const char * name,
locale_t loc);
Parameters
| Parameter | Description |
|---|
| name | Name of mapping. |
| loc | Locale used for mapping. |
Return value
Transformation mapping; zero if mapping unrecognized.
Additional information
Constructs a value of type wctrans_t that describes a mapping
between wide characters identified by the string argument property.
If property identifies a valid mapping of wide characters in the
locale loc, wctrans_l() returns a nonzero value that is valid as
the second argument to towctrans(); otherwise, it returns zero.
The only mappings supported are “tolower” and “toupper”.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
<xlocale.h>
Locale management
newlocale()
Description
Create or modify locale (POSIX.1).
Prototype
locale_t newlocale( int category_mask,
const char * loc,
locale_t base);
Parameters
| Parameter | Description |
|---|
| category_mask | Locale categories to be set or modified. |
| loc | Locale name. |
| base | Base to modify or NULL to create a new locale. |
Return value
Pointer to modified locale.
Additional information
Creates a new locale object or modifies an existing one.
If the base argument is NULL, a new locale object is created.
category_mask specifies the locale categories to be set or modified.
Values for category_mask are constructed by a bitwise-inclusive OR
of the symbolic constants LC_CTYPE_MASK, LC_NUMERIC_MASK, LC_TIME_MASK,
LC_COLLATE_MASK, LC_MONETARY_MASK, and LC_MESSAGES_MASK.
For each category with the corresponding bit set in category_mask, the data
from the locale named by loc is used. In the case of modifying an existing
locale object, the data from the locale named by loc replaces the existing
data within the locale object. If a completely new locale object is created,
the data for all sections not requested by category_mask are taken from the
default locale.
The locales “C” and “POSIX” are equivalent and defined for all settings
of category_mask:
If loc is NULL, then the “C” locale is used. If loc is an empty
string, newlocale() will use the default locale.
If base is NULL, the current locale is used. If base is LC_GLOBAL_LOCALE,
the global locale is used.
If mask is LC_ALL_MASK, base is ignored.
Notes
Conforms to POSIX.1-2017.
POSIX.1-2017 does not specify whether the locale object pointed to by
base is modified or whether it is freed and a new locale object created.
The category mask LC_MESSAGES_MASK is not implemented as POSIX messages
are not implemented.
Thread safety
Safe [if configured].
duplocale()
Description
Duplicate locale data (POSIX.1).
Prototype
locale_t duplocale(locale_t base);
Parameters
| Parameter | Description |
|---|
| base | Locale to duplicate. |
Return value
If there is insufficient memory to duplicate loc, returns
a NULL and sets errno to ENOMEM as required by POSIX.1-2017.
Otherwise, returns a new, duplicated locale.
Additional information
Duplicates the locale object referenced by loc.
Duplicated locales must be freed with freelocale().
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe [if configured].
uselocale()
Description
Set current locale (POSIX.1).
Prototype
locale_t uselocale(locale_t loc);
Parameters
| Parameter | Description |
|---|
| loc | Locale to use. |
Return value
The locale set using the previous call to uselocale(), or
LC_GLOBAL_LOCALE if none was set.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe [if configured].
freelocale()
Description
Free locale (POSIX.1).
Prototype
int freelocale(locale_t loc);
Parameters
| Parameter | Description |
|---|
| loc | Locale to free. |
Return value
Zero on success, -1 on error.
Additional information
Frees the storage associated with loc.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe [if configured].
localeconv_l()
Description
Get locale data (POSIX.1).
Prototype
localeconv_l(locale_t loc);
Parameters
| Parameter | Description |
|---|
| loc | Locale to inquire. |
Return value
Returns a pointer to a structure of type lconv with the
corresponding values for the locale loc filled in.
Notes
Conforms to POSIX.1-2017.
Thread safety
Safe.
Compiler support API
Environment support
This section summarises the functions proved by emRun to support
the C library and environment.
| Function | Description |
|---|
| __SEGGER_RTL_execute_at_exit_fns | Execute at-exit functions. |
| __SEGGER_RTL_set_locale_name_buffer | Set buffer used to store locale names. |
__SEGGER_RTL_execute_at_exit_fns()
Description
Execute at-exit functions.
Prototype
void __SEGGER_RTL_execute_at_exit_fns(void);
Additional information
Executes all functions registered by calls to atexit() in reverse
order of their registration. It does this in the caller’s
execution context.
Thread safety
Not applicable.
__SEGGER_RTL_set_locale_name_buffer()
Description
Set buffer used to store locale names.
Prototype
void __SEGGER_RTL_set_locale_name_buffer(char * buf);
Parameters
| Parameter | Description |
|---|
| buf | Pointer to object that stores name buffer. |
Additional information
The function setlocale() returns a pointer to an object that contains
the previously-set locale. As such, that object must be thread-local,
but its size is not known at compile time. Additionally, to be thread-safe,
this buffer must be local to the thread and not shared between separate
execution contexts.
The user can set the location for the name buffer used by setlocale()
using this function. The name buffer must be large enough to contain
six locale names separated by semicolons and terminated by a final null.
Assuming a locale name “hu_HU.iso_8859_2” of 16 characters, a buffer of
at least 102 characters is required for correct operation.
Note that if no name buffer is set using this function, setlocale() may
still be used but will return NULL as the result. This enables use of
setlocale() but does incur an overhead for a thread-local or global
buffer which may never be required.
Thread safety
Safe [if configured].
Arm AEABI library API
The emRun provides an implementation of the Arm AEABI
functions.
The assembly language floating-point funnctions are contained in
separate files:
- For Arm this is found in floatasmops_arm.s.
The interface to the AEABI functions differs from the standard calling convention
when the hard-floating ABI is used: all floatting-point AEABI functions receive
their parameters in integer registers and return their results in integer regsisters.
Floating arithmetic
| Function | Description |
|---|
| __aeabi_fadd | Add, float. |
| __aeabi_dadd | Add, double. |
| __aeabi_fsub | Subtract, float. |
| __aeabi_dsub | Subtract, double. |
| __aeabi_frsub | Reverse subtract, float. |
| __aeabi_drsub | Reverse subtract, double. |
| __aeabi_fmul | Multiply, float. |
| __aeabi_dmul | Multiply, double. |
| __aeabi_fdiv | Divide, float. |
| __aeabi_ddiv | Divide, double. |
__aeabi_fadd()
Description
Add, float.
Prototype
__SEGGER_RTL_U32 __aeabi_fadd(__SEGGER_RTL_U32 x,
__SEGGER_RTL_U32 y);
Parameters
| Parameter | Description |
|---|
| x | Augend. |
| y | Addend. |
Return value
Sum.
Thread safety
Safe.
__aeabi_dadd()
Description
Add, double.
Prototype
__SEGGER_RTL_U64 __aeabi_dadd(__SEGGER_RTL_U64 x,
__SEGGER_RTL_U64 y);
Parameters
| Parameter | Description |
|---|
| x | Augend. |
| y | Addend. |
Return value
Sum.
Thread safety
Safe.
__aeabi_fsub()
Description
Subtract, float.
Prototype
__SEGGER_RTL_U32 __aeabi_fsub(__SEGGER_RTL_U32 x,
__SEGGER_RTL_U32 y);
Parameters
| Parameter | Description |
|---|
| x | Minuend. |
| y | Subtrahend. |
Return value
Difference.
Thread safety
Safe.
__aeabi_dsub()
Description
Subtract, double.
Prototype
__SEGGER_RTL_U64 __aeabi_dsub(__SEGGER_RTL_U64 x,
__SEGGER_RTL_U64 y);
Parameters
| Parameter | Description |
|---|
| x | Minuend. |
| y | Subtrahend. |
Return value
Difference.
Thread safety
Safe.
__aeabi_frsub()
Description
Reverse subtract, float.
Prototype
__SEGGER_RTL_U32 __aeabi_frsub(__SEGGER_RTL_U32 x,
__SEGGER_RTL_U32 y);
Parameters
| Parameter | Description |
|---|
| x | Minuend. |
| y | Subtrahend. |
Return value
Difference.
Thread safety
Safe.
__aeabi_drsub()
Description
Reverse subtract, double.
Prototype
__SEGGER_RTL_U64 __aeabi_drsub(__SEGGER_RTL_U64 x,
__SEGGER_RTL_U64 y);
Parameters
| Parameter | Description |
|---|
| x | Minuend. |
| y | Subtrahend. |
Return value
Difference.
Thread safety
Safe.
__aeabi_fmul()
Description
Multiply, float.
Prototype
__SEGGER_RTL_U32 __aeabi_fmul(__SEGGER_RTL_U32 x,
__SEGGER_RTL_U32 y);
Parameters
| Parameter | Description |
|---|
| x | Multiplicand. |
| y | Multiplier. |
Return value
Product.
Thread safety
Safe.
__aeabi_dmul()
Description
Multiply, double.
Prototype
__SEGGER_RTL_U64 __aeabi_dmul(__SEGGER_RTL_U64 x,
__SEGGER_RTL_U64 y);
Parameters
| Parameter | Description |
|---|
| x | Multiplicand. |
| y | Multiplier. |
Return value
Product.
Thread safety
Safe.
__aeabi_fdiv()
Description
Divide, float.
Prototype
__SEGGER_RTL_U32 __aeabi_fdiv(__SEGGER_RTL_U32 x,
__SEGGER_RTL_U32 y);
Parameters
| Parameter | Description |
|---|
| x | Dividend. |
| y | Divisor. |
Return value
Quotient.
Thread safety
Safe.
__aeabi_ddiv()
Description
Divide, double.
Prototype
__SEGGER_RTL_U64 __aeabi_ddiv(__SEGGER_RTL_U64 x,
__SEGGER_RTL_U64 y);
Parameters
| Parameter | Description |
|---|
| x | Dividend. |
| y | Divisor. |
Return value
Quotient.
Thread safety
Safe.
Floating conversions
| Function | Description |
|---|
| __aeabi_f2iz | Convert float to int. |
| __aeabi_d2iz | Convert double to int. |
| __aeabi_f2uiz | Convert float to unsigned int. |
| __aeabi_d2uiz | Convert double to unsigned. |
| __aeabi_f2lz | Convert float to long long. |
| __aeabi_d2lz | Convert double to long long. |
| __aeabi_f2ulz | Convert float to unsigned long long. |
| __aeabi_d2ulz | Convert double to unsigned long long. |
| __aeabi_i2f | Convert int to float. |
| __aeabi_i2d | Convert int to double. |
| __aeabi_ui2f | Convert unsigned to float. |
| __aeabi_ui2d | Convert unsigned to double. |
| __aeabi_l2f | Convert long long to float. |
| __aeabi_l2d | Convert long long to double. |
| __aeabi_ul2f | Convert unsigned long long to float. |
| __aeabi_ul2d | Convert unsigned long long to double. |
| __aeabi_f2d | Extend float to double. |
| __aeabi_d2f | Truncate double to float. |
| __aeabi_f2h | Truncate float to IEEE half-precision float. |
| __aeabi_d2h | Truncate double to IEEE half-precision float. |
| __aeabi_h2f | Convert IEEE half-precision float to float. |
| __aeabi_h2d | Convert IEEE half-precision float to double. |
__aeabi_f2iz()
Description
Convert float to int.
Prototype
__SEGGER_RTL_I32 __aeabi_f2iz(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__aeabi_d2iz()
Description
Convert double to int.
Prototype
__SEGGER_RTL_I32 __aeabi_d2iz(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__aeabi_f2uiz()
Description
Convert float to unsigned int.
Prototype
__SEGGER_RTL_U32 __aeabi_f2uiz(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__aeabi_d2uiz()
Description
Convert double to unsigned.
Prototype
__SEGGER_RTL_U32 __aeabi_d2uiz(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Double value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__aeabi_f2lz()
Description
Convert float to long long.
Prototype
__SEGGER_RTL_I64 __aeabi_f2lz(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Notes
The RV32 compiler converts a __SEGGER_RTL_U32 to a 64-bit integer
by calling runtime support to handle it.
Thread safety
Safe.
__aeabi_d2lz()
Description
Convert double to long long.
Prototype
__SEGGER_RTL_I64 __aeabi_d2lz(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Notes
RV32 always calls runtime for __SEGGER_RTL_U64 to int64 conversion.
Thread safety
Safe.
__aeabi_f2ulz()
Description
Convert float to unsigned long long.
Prototype
__SEGGER_RTL_U64 __aeabi_f2ulz(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__aeabi_d2ulz()
Description
Convert double to unsigned long long.
Prototype
__SEGGER_RTL_U64 __aeabi_d2ulz(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__aeabi_i2f()
Description
Convert int to float.
Prototype
__SEGGER_RTL_U32 __aeabi_i2f(__SEGGER_RTL_I32 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__aeabi_i2d()
Description
Convert int to double.
Prototype
__SEGGER_RTL_U64 __aeabi_i2d(__SEGGER_RTL_I32 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__aeabi_ui2f()
Description
Convert unsigned to float.
Prototype
__SEGGER_RTL_U32 __aeabi_ui2f(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__aeabi_ui2d()
Description
Convert unsigned to double.
Prototype
__SEGGER_RTL_U64 __aeabi_ui2d(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Unsigned value to convert. |
Return value
__SEGGER_RTL_U64 value.
Thread safety
Safe.
__aeabi_l2f()
Description
Convert long long to float.
Prototype
__SEGGER_RTL_U32 __aeabi_l2f(__SEGGER_RTL_I64 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__aeabi_l2d()
Description
Convert long long to double.
Prototype
__SEGGER_RTL_U64 __aeabi_l2d(__SEGGER_RTL_I64 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__aeabi_ul2f()
Description
Convert unsigned long long to float.
Prototype
__SEGGER_RTL_U32 __aeabi_ul2f(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Unsigned long long value to convert. |
Return value
__SEGGER_RTL_U32 value.
Thread safety
Safe.
__aeabi_ul2d()
Description
Convert unsigned long long to double.
Prototype
__SEGGER_RTL_U64 __aeabi_ul2d(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Unsigned long long value to convert. |
Return value
__SEGGER_RTL_U64 value.
Thread safety
Safe.
__aeabi_f2d()
Description
Extend float to double.
Prototype
__SEGGER_RTL_U64 __aeabi_f2d(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to extend. |
Return value
__SEGGER_RTL_U64 value.
Thread safety
Safe.
__aeabi_d2f()
Description
Truncate double to float.
Prototype
__SEGGER_RTL_U32 __aeabi_d2f(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Double value to truncate. |
Return value
Float value.
Thread safety
Safe.
__aeabi_f2h()
Description
Truncate float to IEEE half-precision float.
Prototype
__SEGGER_RTL_U16 __aeabi_f2h(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Float value to truncate. |
Return value
Float value.
Thread safety
Safe.
__aeabi_d2h()
Description
Truncate double to IEEE half-precision float.
Prototype
__SEGGER_RTL_U16 __aeabi_d2h(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Double value to truncate. |
Return value
Half-precision value.
Thread safety
Safe.
__aeabi_h2f()
Description
Convert IEEE half-precision float to float.
Prototype
__SEGGER_RTL_U32 __aeabi_h2f(__SEGGER_RTL_U16 x);
Parameters
| Parameter | Description |
|---|
| x | Half-precision float. |
Return value
Single-precision float.
Thread safety
Safe.
__aeabi_f2h()
Description
Truncate float to IEEE half-precision float.
Prototype
__SEGGER_RTL_U16 __aeabi_f2h(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Float value to truncate. |
Return value
Float value.
Thread safety
Safe.
Floating comparisons
| Function | Description |
|---|
| __aeabi_fcmpeq | Equal, float. |
| __aeabi_dcmpeq | Equal, double. |
| __aeabi_fcmplt | Less than, float. |
| __aeabi_dcmplt | Less than, double. |
| __aeabi_fcmple | Less than or equal, float. |
| __aeabi_dcmple | Less than, double. |
| __aeabi_fcmpgt | Less than, float. |
| __aeabi_dcmpgt | Less than, double. |
| __aeabi_fcmpge | Less than, float. |
| __aeabi_dcmpge | Less than, double. |
__aeabi_fcmpeq()
Description
Equal, float.
Prototype
int __aeabi_fcmpeq(__SEGGER_RTL_U32 x,
__SEGGER_RTL_U32 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
| 0 | x is not equal to y. |
| 1 | x is equal to y. |
Thread safety
Safe.
__aeabi_dcmpeq()
Description
Equal, double.
Prototype
int __aeabi_dcmpeq(__SEGGER_RTL_U64 x,
__SEGGER_RTL_U64 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
| 0 | x is not equal to y. |
| 1 | x is equal to y. |
Thread safety
Safe.
__aeabi_fcmplt()
Description
Less than, float.
Prototype
int __aeabi_fcmplt(__SEGGER_RTL_U32 x,
__SEGGER_RTL_U32 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
| 0 | x is not less than y. |
| 1 | x is less than y. |
Thread safety
Safe.
__aeabi_dcmplt()
Description
Less than, double.
Prototype
int __aeabi_dcmplt(__SEGGER_RTL_U64 x,
__SEGGER_RTL_U64 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
| 0 | x is not less than y. |
| 1 | x is less than y. |
Thread safety
Safe.
__aeabi_fcmple()
Description
Less than or equal, float.
Prototype
int __aeabi_fcmple(__SEGGER_RTL_U32 x,
__SEGGER_RTL_U32 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
| 0 | x is not less than or equal to y. |
| 1 | x is less than or equal to y. |
Thread safety
Safe.
__aeabi_dcmple()
Description
Less than, double.
Prototype
int __aeabi_dcmple(__SEGGER_RTL_U64 x,
__SEGGER_RTL_U64 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
| 0 | x is not less than or equal to y. |
| 1 | x is less than or equal to y. |
Thread safety
Safe.
__aeabi_fcmpgt()
Description
Less than, float.
Prototype
int __aeabi_fcmpgt(__SEGGER_RTL_U32 x,
__SEGGER_RTL_U32 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
| 0 | x is not greater than y. |
| 1 | x is greater than y. |
Thread safety
Safe.
__aeabi_dcmpgt()
Description
Less than, double.
Prototype
int __aeabi_dcmpgt(__SEGGER_RTL_U64 x,
__SEGGER_RTL_U64 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
| 0 | x is not greater than y. |
| 1 | x is greater than y. |
Thread safety
Safe.
__aeabi_fcmpge()
Description
Less than, float.
Prototype
int __aeabi_fcmpge(__SEGGER_RTL_U32 x,
__SEGGER_RTL_U32 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
| 0 | x is not greater than or equal to y. |
| 1 | x is greater than or equal to y. |
Thread safety
Safe.
__aeabi_dcmpge()
Description
Less than, double.
Prototype
int __aeabi_dcmpge(__SEGGER_RTL_U64 x,
__SEGGER_RTL_U64 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
| 0 | x is not greater than or equal to y. |
| 1 | x is greater than or equal to y. |
Thread safety
Safe.
GNU library API
Integer arithmetic
| Function | Description |
|---|
| __mulsi3 | Multiply, signed 32-bit integer. |
| __muldi3 | Multiply, signed 64-bit integer. |
| __multi3 | Multiply, signed 128-bit integer. |
| __divsi3 | Divide, signed 32-bit integer. |
| __divdi3 | Divide, signed 64-bit integer. |
| __divti3 | Divide, signed 128-bit integer. |
| __udivsi3 | Divide, unsigned 32-bit integer. |
| __udivdi3 | Divide, unsigned 64-bit integer. |
| __udivti3 | Divide, unsigned 128-bit integer. |
| __modsi3 | Remainder after divide, signed 32-bit integer. |
| __moddi3 | Remainder after divide, signed 64-bit integer. |
| __modti3 | Remainder after divide, signed 128-bit integer. |
| __umodsi3 | Remainder after divide, unsigned 32-bit integer. |
| __umoddi3 | Remainder after divide, unsigned 64-bit integer. |
| __umodti3 | Remainder after divide, unsigned 128-bit integer. |
| __udivmodsi4 | Divide with remainder, unsigned 32-bit integer. |
| __udivmoddi4 | Divide with remainder, unsigned 64-bit integer. |
| __clzsi2 | Count leading zeros, 32-bit integer. |
| __clzdi2 | Count leading zeros, 64-bit integer. |
| __popcountsi2 | Population count, 32-bit integer. |
| __popcountdi2 | Population count, 64-bit integer. |
| __paritysi2 | Parity, 32-bit integer. |
| __paritydi2 | Parity, 64-bit integer. |
__mulsi3()
Description
Multiply, signed 32-bit integer.
Prototype
__SEGGER_RTL_U32 __mulsi3(__SEGGER_RTL_U32 a,
__SEGGER_RTL_U32 b);
Parameters
| Parameter | Description |
|---|
| a | Multiplier. |
| b | Multiplicand. |
Return value
Product.
Thread safety
Safe.
__muldi3()
Description
Multiply, signed 64-bit integer.
Prototype
__SEGGER_RTL_U64 __muldi3(__SEGGER_RTL_U64 a,
__SEGGER_RTL_U64 b);
Parameters
| Parameter | Description |
|---|
| a | Multiplier. |
| b | Multiplicand. |
Return value
Product.
Thread safety
Safe.
__multi3()
Description
Multiply, signed 128-bit integer.
Prototype
__SEGGER_RTL_U128 __multi3(__SEGGER_RTL_U128 a,
__SEGGER_RTL_U128 b);
Parameters
| Parameter | Description |
|---|
| a | Multiplier. |
| b | Multiplicand. |
Return value
Product.
Thread safety
Safe.
__divsi3()
Description
Divide, signed 32-bit integer.
Prototype
int32_t __divsi3(int32_t u,
int32_t v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
Quotient.
Thread safety
Safe.
__divdi3()
Description
Divide, signed 64-bit integer.
Prototype
int64_t __divdi3(int64_t u,
int64_t v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
Quotient.
Thread safety
Safe.
__divti3()
Description
Divide, signed 128-bit integer.
Prototype
__SEGGER_RTL_U128 __divti3(__SEGGER_RTL_U128 u,
__SEGGER_RTL_U128 v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
Quotient.
Thread safety
Safe.
__udivsi3()
Description
Divide, unsigned 32-bit integer.
Prototype
__SEGGER_RTL_U32 __udivsi3(__SEGGER_RTL_U32 u,
__SEGGER_RTL_U32 v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
Quotient.
Thread safety
Safe.
__udivdi3()
Description
Divide, unsigned 64-bit integer.
Prototype
__SEGGER_RTL_U64 __udivdi3(__SEGGER_RTL_U64 u,
__SEGGER_RTL_U64 v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
floor(u / v).
Thread safety
Safe.
__udivti3()
Description
Divide, unsigned 128-bit integer.
Prototype
__SEGGER_RTL_U128 __udivti3(__SEGGER_RTL_U128 u,
__SEGGER_RTL_U128 v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
floor(u / v).
Thread safety
Safe.
__modsi3()
Description
Remainder after divide, signed 32-bit integer.
Prototype
int32_t __modsi3(int32_t u,
int32_t v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
Remainder.
Thread safety
Safe.
__moddi3()
Description
Remainder after divide, signed 64-bit integer.
Prototype
int64_t __moddi3(int64_t u,
int64_t v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
Remainder.
Thread safety
Safe.
__modti3()
Description
Remainder after divide, signed 128-bit integer.
Prototype
__SEGGER_RTL_U128 __modti3(__SEGGER_RTL_U128 u,
__SEGGER_RTL_U128 v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
Remainder.
Thread safety
Safe.
__umodsi3()
Description
Remainder after divide, unsigned 32-bit integer.
Prototype
__SEGGER_RTL_U32 __umodsi3(__SEGGER_RTL_U32 u,
__SEGGER_RTL_U32 v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
Remainder.
Thread safety
Safe.
__umoddi3()
Description
Remainder after divide, unsigned 64-bit integer.
Prototype
__SEGGER_RTL_U64 __umoddi3(__SEGGER_RTL_U64 u,
__SEGGER_RTL_U64 v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
Remainder.
Thread safety
Safe.
__umodti3()
Description
Remainder after divide, unsigned 128-bit integer.
Prototype
__SEGGER_RTL_U128 __umodti3(__SEGGER_RTL_U128 u,
__SEGGER_RTL_U128 v);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
Return value
Remainder.
Thread safety
Safe.
__udivmodsi4()
Description
Divide with remainder, unsigned 32-bit integer.
Prototype
__SEGGER_RTL_U32 __udivmodsi4(__SEGGER_RTL_U32 u,
__SEGGER_RTL_U32 v,
__SEGGER_RTL_U32 *rem);
Parameters
| Parameter | Description |
|---|
| u | Divivdend. |
| v | Divisor. |
| rem | Pointer to object that receives the remainder. |
Return value
Quotient.
Thread safety
Safe.
__udivmoddi4()
Description
Divide with remainder, unsigned 64-bit integer.
Prototype
__SEGGER_RTL_U64 __udivmoddi4(__SEGGER_RTL_U64 u,
__SEGGER_RTL_U64 v,
__SEGGER_RTL_U64 *rem);
Parameters
| Parameter | Description |
|---|
| u | Dividend. |
| v | Divisor. |
| rem | Pointer to object that receives the remainder. |
Return value
Quotient.
Thread safety
Safe.
__clzsi2()
Description
Count leading zeros, 32-bit integer.
Prototype
int __clzsi2(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Argument; x must not be zero. |
Return value
Number of leading zeros in x.
Thread safety
Safe.
__clzdi2()
Description
Count leading zeros, 64-bit integer.
Prototype
int __clzdi2(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Argument; x must not be zero. |
Return value
Number of leading zeros in x.
Thread safety
Safe.
__popcountsi2()
Description
Population count, 32-bit integer.
Prototype
int __popcountsi2(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Argument. |
Return value
Count of number of one bits in x.
Thread safety
Safe.
__popcountdi2()
Description
Population count, 64-bit integer.
Prototype
int __popcountdi2(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Argument. |
Return value
Count of number of one bits in x.
Thread safety
Safe.
__paritysi2()
Description
Parity, 32-bit integer.
Prototype
int __paritysi2(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Argument. |
Return value
| 1 | number of one bits in x is odd. |
| 0 | number of one bits in x is even. |
Thread safety
Safe.
__paritydi2()
Description
Parity, 64-bit integer.
Prototype
int __paritydi2(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Argument. |
Return value
| 1 | number of one bits in x is odd. |
| 0 | number of one bits in x is even. |
Thread safety
Safe.
Floating arithmetic
| Function | Description |
|---|
| __addsf3 | Add, float. |
| __adddf3 | Add, double. |
| __addtf3 | Add, long double. |
| __subsf3 | Subtract, float. |
| __subdf3 | Subtract, double. |
| __subtf3 | Subtract, long double. |
| __mulsf3 | Multiply, float. |
| __muldf3 | Multiply, double. |
| __multf3 | Multiply, long double. |
| __divsf3 | Divide, float. |
| __divdf3 | Divide, double. |
| __divtf3 | Divide, long double. |
__addsf3()
Description
Add, float.
Prototype
float __addsf3(float x,
float y);
Parameters
| Parameter | Description |
|---|
| x | Augend. |
| y | Addend. |
Return value
Sum.
Thread safety
Safe.
__adddf3()
Description
Add, double.
Prototype
double __adddf3(double x,
double y);
Parameters
| Parameter | Description |
|---|
| x | Augend. |
| y | Addend. |
Return value
Sum.
Thread safety
Safe.
__addtf3()
Description
Add, long double.
Prototype
long double __addtf3(long double x,
long double y);
Parameters
| Parameter | Description |
|---|
| x | Augend. |
| y | Addend. |
Return value
Sum.
Thread safety
Safe.
__subsf3()
Description
Subtract, float.
Prototype
float __subsf3(float x,
float y);
Parameters
| Parameter | Description |
|---|
| x | Minuend. |
| y | Subtrahend. |
Return value
Difference.
Thread safety
Safe.
__subdf3()
Description
Subtract, double.
Prototype
double __subdf3(double x,
double y);
Parameters
| Parameter | Description |
|---|
| x | Minuend. |
| y | Subtrahend. |
Return value
Difference.
Thread safety
Safe.
__subtf3()
Description
Subtract, long double.
Prototype
long double __subtf3(long double x,
long double y);
Parameters
| Parameter | Description |
|---|
| x | Minuend. |
| y | Subtrahend. |
Return value
Difference.
Thread safety
Safe.
__mulsf3()
Description
Multiply, float.
Prototype
float __mulsf3(float x,
float y);
Parameters
| Parameter | Description |
|---|
| x | Multiplicand. |
| y | Multiplier. |
Return value
Product.
Thread safety
Safe.
__muldf3()
Description
Multiply, double.
Prototype
double __muldf3(double x,
double y);
Parameters
| Parameter | Description |
|---|
| x | Multiplicand. |
| y | Multiplier. |
Return value
Product.
Thread safety
Safe.
__multf3()
Description
Multiply, long double.
Prototype
long double __multf3(long double x,
long double y);
Parameters
| Parameter | Description |
|---|
| x | Multiplicand. |
| y | Multiplier. |
Return value
Product.
Thread safety
Safe.
__divsf3()
Description
Divide, float.
Prototype
float __divsf3(float x,
float y);
Parameters
| Parameter | Description |
|---|
| x | Dividend. |
| y | Divisor. |
Return value
Quotient.
Thread safety
Safe.
__divdf3()
Description
Divide, double.
Prototype
double __divdf3(double x,
double y);
Parameters
| Parameter | Description |
|---|
| x | Dividend. |
| y | Divisor. |
Return value
Quotient.
Thread safety
Safe.
__divtf3()
Description
Divide, long double.
Prototype
long double __divtf3(long double x,
long double y);
Parameters
| Parameter | Description |
|---|
| x | Dividend. |
| y | Divisor. |
Return value
Quotient.
Thread safety
Safe.
Floating conversions
| Function | Description |
|---|
| __fixhfsi | Convert half-precision float to int. |
| __fixsfsi | Convert float to int. |
| __fixdfsi | Convert double to int. |
| __fixtfsi | Convert long double to int. |
| __fixhfdi | Convert half-precision float to int. |
| __fixsfdi | Convert float to long long. |
| __fixdfdi | Convert double to long long. |
| __fixtfdi | Convert long double to long long. |
| __fixunshfsi | Convert half-precision float to unsigned. |
| __fixunssfsi | Convert float to unsigned. |
| __fixunsdfsi | Convert double to unsigned. |
| __fixunstfsi | Convert long double to int. |
| __fixunshfdi | Convert half-precision float to unsigned. |
| __fixunssfdi | Convert float to unsigned long long. |
| __fixunsdfdi | Convert double to unsigned long long. |
| __fixunstfdi | Convert long double to unsigned long long. |
| __floatsihf | Convert int to half-precision float. |
| __floatsisf | Convert int to float. |
| __floatsidf | Convert int to double. |
| __floatsitf | Convert int to long double. |
| __floatdihf | Convert long long to half-precision float. |
| __floatdisf | Convert long long to float. |
| __floatdidf | Convert long long to double. |
| __floatditf | Convert long long to long double. |
| __floatunsihf | Convert unsigned to half-precision float. |
| __floatunsisf | Convert unsigned to float. |
| __floatunsidf | Convert unsigned to double. |
| __floatunsitf | Convert unsigned to long double. |
| __floatundihf | Convert unsigned long long to half-precision float. |
| __floatundisf | Convert unsigned long long to float. |
| __floatundidf | Convert unsigned long long to double. |
| __floatunditf | Convert unsigned long long to long double. |
| __extendhfsf2 | Convert IEEE half-precision float to float. |
| __extendhfdf2 | Convert IEEE half-precision float to double. |
| __extendhftf2 | Convert IEEE half-precision float to long double. |
| __extendsfdf2 | Extend float to double. |
| __extendsftf2 | Extend float to long double. |
| __extenddftf2 | Extend double to long double. |
| __trunctfdf2 | Truncate long double to double. |
| __trunctfsf2 | Truncate long double to float. |
| __trunctfhf2 | Truncate long double to IEEE half-precision float. |
| __truncdfsf2 | Truncate double to float. |
| __truncdfhf2 | Truncate double to IEEE half-precision float. |
| __truncsfhf2 | Truncate float to IEEE half-precision float. |
__fixhfsi()
Description
Convert half-precision float to int.
Prototype
__SEGGER_RTL_I32 __fixhfsi(__SEGGER_RTL_FLOAT16 x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixsfsi()
Description
Convert float to int.
Prototype
__SEGGER_RTL_I32 __fixsfsi(float x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixdfsi()
Description
Convert double to int.
Prototype
__SEGGER_RTL_I32 __fixdfsi(double x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixtfsi()
Description
Convert long double to int.
Prototype
__SEGGER_RTL_I32 __fixtfsi(long double x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixhfdi()
Description
Convert half-precision float to int.
Prototype
__SEGGER_RTL_I64 __fixhfdi(__SEGGER_RTL_FLOAT16 x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixsfdi()
Description
Convert float to long long.
Prototype
__SEGGER_RTL_I64 __fixsfdi(float f);
Parameters
| Parameter | Description |
|---|
| f | Floating value to convert. |
Return value
Integerized value.
Notes
The RV32 compiler converts a float to a 64-bit integer
by calling runtime support to handle it.
Thread safety
Safe.
__fixdfdi()
Description
Convert double to long long.
Prototype
__SEGGER_RTL_I64 __fixdfdi(double x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Notes
RV32 always calls runtime for double to int64 conversion.
Thread safety
Safe.
__fixtfdi()
Description
Convert long double to long long.
Prototype
__SEGGER_RTL_I64 __fixtfdi(long double x);
Parameters
| Parameter | Description |
|---|
| x | Floating value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixunshfsi()
Description
Convert half-precision float to unsigned.
Prototype
unsigned __fixunshfsi(__SEGGER_RTL_FLOAT16 x);
Parameters
| Parameter | Description |
|---|
| x | Float value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixunssfsi()
Description
Convert float to unsigned.
Prototype
__SEGGER_RTL_U32 __fixunssfsi(float x);
Parameters
| Parameter | Description |
|---|
| x | Float value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixunsdfsi()
Description
Convert double to unsigned.
Prototype
__SEGGER_RTL_U32 __fixunsdfsi(double x);
Parameters
| Parameter | Description |
|---|
| x | Float value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixunstfsi()
Description
Convert long double to int.
Prototype
int __fixunstfsi(long double x);
Parameters
| Parameter | Description |
|---|
| x | Float value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixunshfdi()
Description
Convert half-precision float to unsigned.
Prototype
__SEGGER_RTL_I64 __fixunshfdi(__SEGGER_RTL_FLOAT16 x);
Parameters
| Parameter | Description |
|---|
| x | Float value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixunssfdi()
Description
Convert float to unsigned long long.
Prototype
__SEGGER_RTL_U64 __fixunssfdi(float f);
Parameters
| Parameter | Description |
|---|
| f | Float value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixunsdfdi()
Description
Convert double to unsigned long long.
Prototype
__SEGGER_RTL_U64 __fixunsdfdi(double x);
Parameters
| Parameter | Description |
|---|
| x | Float value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__fixunstfdi()
Description
Convert long double to unsigned long long.
Prototype
__SEGGER_RTL_U64 __fixunstfdi(long double x);
Parameters
| Parameter | Description |
|---|
| x | Float value to convert. |
Return value
Integerized value.
Thread safety
Safe.
__floatsihf()
Description
Convert int to half-precision float.
Prototype
__SEGGER_RTL_FLOAT16 __floatsihf(__SEGGER_RTL_I32 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__floatsisf()
Description
Convert int to float.
Prototype
float __floatsisf(__SEGGER_RTL_I32 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__floatsidf()
Description
Convert int to double.
Prototype
double __floatsidf(__SEGGER_RTL_I32 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__floatsitf()
Description
Convert int to long double.
Prototype
long double __floatsitf(__SEGGER_RTL_I32 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__floatdihf()
Description
Convert long long to half-precision float.
Prototype
__SEGGER_RTL_FLOAT16 __floatdihf(__SEGGER_RTL_I64 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__floatdisf()
Description
Convert long long to float.
Prototype
float __floatdisf(__SEGGER_RTL_I64 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__floatdidf()
Description
Convert long long to double.
Prototype
double __floatdidf(__SEGGER_RTL_I64 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__floatditf()
Description
Convert long long to long double.
Prototype
long double __floatditf(__SEGGER_RTL_I64 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__floatunsihf()
Description
Convert unsigned to half-precision float.
Prototype
__SEGGER_RTL_FLOAT16 __floatunsihf(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__floatunsisf()
Description
Convert unsigned to float.
Prototype
float __floatunsisf(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Integer value to convert. |
Return value
Floating value.
Thread safety
Safe.
__floatunsidf()
Description
Convert unsigned to double.
Prototype
double __floatunsidf(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Unsigned value to convert. |
Return value
Double value.
Thread safety
Safe.
__floatunsitf()
Description
Convert unsigned to long double.
Prototype
long double __floatunsitf(__SEGGER_RTL_U32 x);
Parameters
| Parameter | Description |
|---|
| x | Unsigned value to convert. |
Return value
Long double value.
Thread safety
Safe.
__floatundihf()
Description
Convert unsigned long long to half-precision float.
Prototype
__SEGGER_RTL_FLOAT16 __floatundihf(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Unsigned long long value to convert. |
Return value
Float value.
Thread safety
Safe.
__floatundisf()
Description
Convert unsigned long long to float.
Prototype
float __floatundisf(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Unsigned long long value to convert. |
Return value
Float value.
Thread safety
Safe.
__floatundidf()
Description
Convert unsigned long long to double.
Prototype
double __floatundidf(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Unsigned long long value to convert. |
Return value
Double value.
Thread safety
Safe.
__floatunditf()
Description
Convert unsigned long long to long double.
Prototype
long double __floatunditf(__SEGGER_RTL_U64 x);
Parameters
| Parameter | Description |
|---|
| x | Unsigned long long value to convert. |
Return value
Long double value.
Thread safety
Safe.
__extendhfsf2()
Description
Convert IEEE half-precision float to float.
Prototype
float __extendhfsf2(__SEGGER_RTL_FLOAT16 x);
Parameters
| Parameter | Description |
|---|
| x | Half-precision float. |
Return value
Single-precision float.
Thread safety
Safe.
__extendhfdf2()
Description
Convert IEEE half-precision float to double.
Prototype
double __extendhfdf2(__SEGGER_RTL_FLOAT16 x);
Parameters
| Parameter | Description |
|---|
| x | Half-precision float. |
Return value
Double-precision float.
Thread safety
Safe.
__extendhftf2()
Description
Convert IEEE half-precision float to long double.
Prototype
long double __extendhftf2(__SEGGER_RTL_FLOAT16 x);
Parameters
| Parameter | Description |
|---|
| x | Half-precision float. |
Return value
Long-double float.
Thread safety
Safe.
__extendsfdf2()
Description
Extend float to double.
Prototype
double __extendsfdf2(float x);
Parameters
| Parameter | Description |
|---|
| x | Float value to extend. |
Return value
Double value.
Thread safety
Safe.
__extendsftf2()
Description
Extend float to long double.
Prototype
long double __extendsftf2(float x);
Parameters
| Parameter | Description |
|---|
| x | Float value to extend. |
Return value
Double value.
Thread safety
Safe.
__extenddftf2()
Description
Extend double to long double.
Prototype
long double __extenddftf2(double x);
Parameters
| Parameter | Description |
|---|
| x | Double value to extend. |
Return value
Long double value.
Thread safety
Safe.
__trunctfdf2()
Description
Truncate long double to double.
Prototype
double __trunctfdf2(long double x);
Parameters
| Parameter | Description |
|---|
| x | Long double value to truncate. |
Return value
Double value.
Thread safety
Safe.
__trunctfsf2()
Description
Truncate long double to float.
Prototype
float __trunctfsf2(long double x);
Parameters
| Parameter | Description |
|---|
| x | Long double value to truncate. |
Return value
Float value.
Thread safety
Safe.
__trunctfhf2()
Description
Truncate long double to IEEE half-precision float.
Prototype
__SEGGER_RTL_FLOAT16 __trunctfhf2(long double x);
Parameters
| Parameter | Description |
|---|
| x | Long-double value to truncate. |
Return value
Half-precision value.
Thread safety
Safe.
__truncdfsf2()
Description
Truncate double to float.
Prototype
float __truncdfsf2(double x);
Parameters
| Parameter | Description |
|---|
| x | Double value to truncate. |
Return value
Float value.
Thread safety
Safe.
__truncdfhf2()
Description
Truncate double to IEEE half-precision float.
Prototype
__SEGGER_RTL_FLOAT16 __truncdfhf2(double x);
Parameters
| Parameter | Description |
|---|
| x | Double value to truncate. |
Return value
Half-precision value.
Thread safety
Safe.
__truncsfhf2()
Description
Truncate float to IEEE half-precision float.
Prototype
__SEGGER_RTL_FLOAT16 __truncsfhf2(float x);
Parameters
| Parameter | Description |
|---|
| x | Float value to truncate. |
Return value
Float value.
Thread safety
Safe.
Complex arithmetic
| Function | Description |
|---|
| __mulsc3 | Multiply, float complex. |
| __muldc3 | Multiply, double complex. |
| __divsc3 | Divide, float complex. |
| __divdc3 | Divide, double complex. |
__mulsc3()
Description
Multiply, float complex.
Prototype
__SEGGER_RTL_FLOAT32_C_COMPLEX __mulsc3(float a,
float b,
float c,
float d);
Parameters
| Parameter | Description |
|---|
| a | Real part of multiplicand. |
| b | Imaginary part of multiplicand. |
| c | Real part of multiplier. |
| d | Imaginary part of multiplier. |
Return value
Product.
Thread safety
Safe.
__muldc3()
Description
Multiply, double complex.
Prototype
__SEGGER_RTL_FLOAT64_C_COMPLEX __muldc3(double a,
double b,
double c,
double d);
Parameters
| Parameter | Description |
|---|
| a | Real part of multiplicand. |
| b | Imaginary part of multiplicand. |
| c | Real part of multiplier. |
| d | Imaginary part of multiplier. |
Return value
Product.
Thread safety
Safe.
__multc3()
Description
Multiply, long double complex.
Prototype
__SEGGER_RTL_LDOUBLE_C_COMPLEX __multc3(long double a,
long double b,
long double c,
long double d);
Parameters
| Parameter | Description |
|---|
| a | Real part of multiplicand. |
| b | Imaginary part of multiplicand. |
| c | Real part of multiplier. |
| d | Imaginary part of multiplier. |
Return value
Product.
Thread safety
Safe.
__divsc3()
Description
Divide, float complex.
Prototype
__SEGGER_RTL_FLOAT32_C_COMPLEX __divsc3(float a,
float b,
float c,
float d);
Parameters
| Parameter | Description |
|---|
| a | Real part of dividend. |
| b | Imaginary part of dividend. |
| c | Real part of divisor. |
| d | Imaginary part of divisor. |
Return value
Quotient.
Thread safety
Safe.
__divdc3()
Description
Divide, double complex.
Prototype
__SEGGER_RTL_FLOAT64_C_COMPLEX __divdc3(double a,
double b,
double c,
double d);
Parameters
| Parameter | Description |
|---|
| a | Real part of dividend. |
| b | Imaginary part of dividend. |
| c | Real part of divisor. |
| d | Imaginary part of divisor. |
Return value
Quotient.
Thread safety
Safe.
__divtc3()
Description
Divide, long double complex.
Prototype
__SEGGER_RTL_LDOUBLE_C_COMPLEX __divtc3(long double a,
long double b,
long double c,
long double d);
Parameters
| Parameter | Description |
|---|
| a | Real part of dividend. |
| b | Imaginary part of dividend. |
| c | Real part of divisor. |
| d | Imaginary part of divisor. |
Return value
Quotient.
Thread safety
Safe.
Floating comparisons
| Function | Description |
|---|
| __eqhf2 | Equal, half-precision float. |
| __eqsf2 | Equal, float. |
| __eqdf2 | Equal, double. |
| __eqtf2 | Equal, long double. |
| __nehf2 | Not equal, half-precision float. |
| __nesf2 | Not equal, float. |
| __nedf2 | Not equal, double. |
| __netf2 | Not equal, long double. |
| __lthf2 | Less than, half-precision float. |
| __ltsf2 | Less than, float. |
| __ltdf2 | Less than, double. |
| __lttf2 | Less than, long double. |
| __lehf2 | Less than or equal, half-precision float. |
| __lesf2 | Less than or equal, float. |
| __ledf2 | Less than or equal, double. |
| __letf2 | Less than or equal, long double. |
| __gthf2 | Greater than, half-precision float. |
| __gtsf2 | Greater than, float. |
| __gtdf2 | Greater than, double. |
| __gttf2 | Greater than, long double. |
| __gehf2 | Greater than or equal, half-precision float. |
| __gesf2 | Greater than or equal, float. |
| __gedf2 | Greater than or equal, double. |
| __getf2 | Greater than or equal, long double. |
| __unordsf2 | Unordered operand query, float. |
| __unorddf2 | Unordered operand query, double. |
| __unordtf2 | Unordered operand query, long double. |
__eqhf2()
Description
Equal, half-precision float.
Prototype
int __eqhf2(__SEGGER_RTL_FLOAT16 x,
__SEGGER_RTL_FLOAT16 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return = 0 if both operands are non-NaN and a = b (GNU
three-way boolean).
Thread safety
Safe.
__eqsf2()
Description
Equal, float.
Prototype
int __eqsf2(float x,
float y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return = 0 if both operands are non-NaN and a = b (GNU
three-way boolean).
Thread safety
Safe.
__eqdf2()
Description
Equal, double.
Prototype
int __eqdf2(double x,
double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return = 0 if both operands are non-NaN and a = b (GNU
three-way boolean).
Thread safety
Safe.
__eqtf2()
Description
Equal, long double.
Prototype
int __eqtf2(long double x,
long double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return = 0 if both operands are non-NaN and a = b (GNU
three-way boolean).
Thread safety
Safe.
__nehf2()
Description
Not equal, half-precision float.
Prototype
int __nehf2(__SEGGER_RTL_FLOAT16 x,
__SEGGER_RTL_FLOAT16 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return = 0 if both operands are non-NaN and a = b (GNU
three-way boolean).
Thread safety
Safe.
__nesf2()
Description
Not equal, float.
Prototype
int __nesf2(float x,
float y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return = 0 if both operands are non-NaN and a = b (GNU
three-way boolean).
Thread safety
Safe.
__nedf2()
Description
Not equal, double.
Prototype
int __nedf2(double x,
double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return = 0 if both operands are non-NaN and a = b (GNU
three-way boolean).
Thread safety
Safe.
__netf2()
Description
Not equal, long double.
Prototype
int __netf2(long double x,
long double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return = 0 if both operands are non-NaN and a = b (GNU
three-way boolean).
Thread safety
Safe.
__lthf2()
Description
Less than, half-precision float.
Prototype
int __lthf2(__SEGGER_RTL_FLOAT16 x,
__SEGGER_RTL_FLOAT16 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return < 0 if both operands are non-NaN and a < b (GNU
three-way boolean).
Thread safety
Safe.
__ltsf2()
Description
Less than, float.
Prototype
int __ltsf2(float x,
float y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return < 0 if both operands are non-NaN and a < b (GNU
three-way boolean).
Thread safety
Safe.
__ltdf2()
Description
Less than, double.
Prototype
int __ltdf2(double x,
double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return < 0 if both operands are non-NaN and a < b (GNU
three-way boolean).
Thread safety
Safe.
__lttf2()
Description
Less than, long double.
Prototype
int __lttf2(long double x,
long double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return < 0 if both operands are non-NaN and a < b (GNU
three-way boolean).
Thread safety
Safe.
__lehf2()
Description
Less than or equal, half-precision float.
Prototype
int __lehf2(__SEGGER_RTL_FLOAT16 x,
__SEGGER_RTL_FLOAT16 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return ≤ 0 if both operands are non-NaN and a < b (GNU
three-way boolean).
Thread safety
Safe.
__lesf2()
Description
Less than or equal, float.
Prototype
int __lesf2(float x,
float y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return ≤ 0 if both operands are non-NaN and a < b (GNU
three-way boolean).
Thread safety
Safe.
__ledf2()
Description
Less than or equal, double.
Prototype
int __ledf2(double x,
double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return ≤ 0 if both operands are non-NaN and a < b (GNU
three-way boolean).
Thread safety
Safe.
__letf2()
Description
Less than or equal, long double.
Prototype
int __letf2(long double x,
long double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return ≤ 0 if both operands are non-NaN and a ≤ b (GNU
three-way boolean).
Thread safety
Safe.
__gthf2()
Description
Greater than, half-precision float.
Prototype
int __gthf2(__SEGGER_RTL_FLOAT16 x,
__SEGGER_RTL_FLOAT16 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return > 0 if both operands are non-NaN and a > b (GNU
three-way boolean).
Thread safety
Safe.
__gtsf2()
Description
Greater than, float.
Prototype
int __gtsf2(float x,
float y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return > 0 if both operands are non-NaN and a > b (GNU
three-way boolean).
Thread safety
Safe.
__gtdf2()
Description
Greater than, double.
Prototype
int __gtdf2(double x,
double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return > 0 if both operands are non-NaN and a > b (GNU
three-way boolean).
Thread safety
Safe.
__gttf2()
Description
Greater than, long double.
Prototype
int __gttf2(long double x,
long double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return > 0 if both operands are non-NaN and a > b (GNU
three-way boolean).
Thread safety
Safe.
__gehf2()
Description
Greater than or equal, half-precision float.
Prototype
int __gehf2(__SEGGER_RTL_FLOAT16 x,
__SEGGER_RTL_FLOAT16 y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return ≥ 0 if both operands are non-NaN and a ≥ b (GNU
three-way boolean).
Thread safety
Safe.
__gesf2()
Description
Greater than or equal, float.
Prototype
int __gesf2(float x,
float y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return ≥ 0 if both operands are non-NaN and a ≥ b (GNU
three-way boolean).
Thread safety
Safe.
__gedf2()
Description
Greater than or equal, double.
Prototype
int __gedf2(double x,
double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return ≥ 0 if both operands are non-NaN and a ≥ b (GNU
three-way boolean).
Thread safety
Safe.
__getf2()
Description
Greater than or equal, long double.
Prototype
int __getf2(long double x,
long double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return ≥ 0 if both operands are non-NaN and a ≥ b (GNU
three-way boolean).
Thread safety
Safe.
__unordsf2()
Description
Unordered operand query, float.
Prototype
int __unordsf2(float x,
float y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return nonzero if comparison between operands is unordered.
Thread safety
Safe.
__unorddf2()
Description
Unordered operand query, double.
Prototype
int __unorddf2(double x,
double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return nonzero if comparison between operands is unordered.
Thread safety
Safe.
__unordtf2()
Description
Unordered operand query, long double.
Prototype
int __unordtf2(long double x,
long double y);
Parameters
| Parameter | Description |
|---|
| x | Left-hand operand. |
| y | Right-hand operand. |
Return value
Return nonzero if comparison between operands is unordered.
Thread safety
Safe.
Atomic operations
| Function | Description |
|---|
| __atomic_load | |
| __atomic_store | |
| __atomic_is_lock_free | |
| __atomic_load_1 | |
| __atomic_load_2 | |
| __atomic_load_4 | |
| __atomic_load_8 | |
| __atomic_load_16 | |
| __atomic_store_1 | |
| __atomic_store_2 | |
| __atomic_store_4 | |
| __atomic_store_8 | |
| __atomic_store_16 | |
| __atomic_add_fetch_1 | |
| __atomic_add_fetch_2 | |
| __atomic_add_fetch_4 | |
| __atomic_add_fetch_8 | |
| __atomic_add_fetch_16 | |
| __atomic_sub_fetch_1 | |
| __atomic_sub_fetch_2 | |
| __atomic_sub_fetch_4 | |
| __atomic_sub_fetch_8 | |
| __atomic_sub_fetch_16 | |
| __atomic_and_fetch_1 | |
| __atomic_and_fetch_2 | |
| __atomic_and_fetch_4 | |
| __atomic_and_fetch_8 | |
| __atomic_and_fetch_16 | |
| __atomic_or_fetch_1 | |
| __atomic_or_fetch_2 | |
| __atomic_or_fetch_4 | |
| __atomic_or_fetch_8 | |
| __atomic_or_fetch_16 | |
| __atomic_xor_fetch_1 | |
| __atomic_xor_fetch_2 | |
| __atomic_xor_fetch_4 | |
| __atomic_xor_fetch_8 | |
| __atomic_xor_fetch_16 | |
| __atomic_nand_fetch_1 | |
| __atomic_nand_fetch_2 | |
| __atomic_nand_fetch_4 | |
| __atomic_nand_fetch_8 | |
| __atomic_nand_fetch_16 | |
| __atomic_fetch_add_1 | |
| __atomic_fetch_add_2 | |
| __atomic_fetch_add_4 | |
| __atomic_fetch_add_8 | |
| __atomic_fetch_add_16 | |
| __atomic_fetch_sub_1 | |
| __atomic_fetch_sub_2 | |
| __atomic_fetch_sub_4 | |
| __atomic_fetch_sub_8 | |
| __atomic_fetch_sub_16 | |
| __atomic_fetch_and_1 | |
| __atomic_fetch_and_2 | |
| __atomic_fetch_and_4 | |
| __atomic_fetch_and_8 | |
| __atomic_fetch_and_16 | |
| __atomic_fetch_or_1 | |
| __atomic_fetch_or_2 | |
| __atomic_fetch_or_4 | |
| __atomic_fetch_or_8 | |
| __atomic_fetch_or_16 | |
| __atomic_fetch_xor_1 | |
| __atomic_fetch_xor_2 | |
| __atomic_fetch_xor_4 | |
| __atomic_fetch_xor_8 | |
| __atomic_fetch_xor_16 | |
| __atomic_fetch_nand_1 | |
| __atomic_fetch_nand_2 | |
| __atomic_fetch_nand_4 | |
| __atomic_fetch_nand_8 | |
| __atomic_fetch_nand_16 | |
|
| __sync_fetch_and_add_1 | |
| __sync_fetch_and_add_2 | |
| __sync_fetch_and_add_4 | |
| __sync_fetch_and_add_8 | |
| __sync_fetch_and_add_16 | |
| __sync_fetch_and_sub_1 | |
| __sync_fetch_and_sub_2 | |
| __sync_fetch_and_sub_4 | |
| __sync_fetch_and_sub_8 | |
| __sync_fetch_and_sub_16 | |
| __sync_fetch_and_and_1 | |
| __sync_fetch_and_and_2 | |
| __sync_fetch_and_and_4 | |
| __sync_fetch_and_and_8 | |
| __sync_fetch_and_and_16 | |
| __sync_fetch_and_or_1 | |
| __sync_fetch_and_or_2 | |
| __sync_fetch_and_or_4 | |
| __sync_fetch_and_or_8 | |
| __sync_fetch_and_or_16 | |
| __sync_fetch_and_xor_1 | |
| __sync_fetch_and_xor_2 | |
| __sync_fetch_and_xor_4 | |
| __sync_fetch_and_xor_8 | |
| __sync_fetch_and_xor_16 | |
| __sync_fetch_and_nand_1 | |
| __sync_fetch_and_nand_2 | |
| __sync_fetch_and_nand_4 | |
| __sync_fetch_and_nand_8 | |
| __sync_fetch_and_nand_16 | |
| __sync_add_and_fetch_1 | |
| __sync_add_and_fetch_2 | |
| __sync_add_and_fetch_4 | |
| __sync_add_and_fetch_8 | |
| __sync_add_and_fetch_16 | |
| __sync_sub_and_fetch_1 | |
| __sync_sub_and_fetch_2 | |
| __sync_sub_and_fetch_4 | |
| __sync_sub_and_fetch_8 | |
| __sync_sub_and_fetch_16 | |
| __sync_and_and_fetch_1 | |
| __sync_and_and_fetch_2 | |
| __sync_and_and_fetch_4 | |
| __sync_and_and_fetch_8 | |
| __sync_and_and_fetch_16 | |
| __sync_or_and_fetch_1 | |
| __sync_or_and_fetch_2 | |
| __sync_or_and_fetch_4 | |
| __sync_or_and_fetch_8 | |
| __sync_or_and_fetch_16 | |
| __sync_xor_and_fetch_1 | |
| __sync_xor_and_fetch_2 | |
| __sync_xor_and_fetch_4 | |
| __sync_xor_and_fetch_8 | |
| __sync_xor_and_fetch_16 | |
| __sync_nand_and_fetch_1 | |
| __sync_nand_and_fetch_2 | |
| __sync_nand_and_fetch_4 | |
| __sync_nand_and_fetch_8 | |
| __sync_nand_and_fetch_16 | |
| __sync_bool_compare_and_swap_1 | |
| __sync_bool_compare_and_swap_2 | |
| __sync_bool_compare_and_swap_4 | |
| __sync_bool_compare_and_swap_8 | |
| __sync_bool_compare_and_swap_16 | |
| __sync_val_compare_and_swap_1 | |
| __sync_val_compare_and_swap_2 | |
| __sync_val_compare_and_swap_4 | |
| __sync_val_compare_and_swap_8 | |
| __sync_val_compare_and_swap_16 | |
| __sync_lock_test_and_set_1 | |
| __sync_lock_test_and_set_2 | |
| __sync_lock_test_and_set_4 | |
| __sync_lock_test_and_set_8 | |
| __sync_lock_test_and_set_16 | |
| __sync_lock_release_1 | |
| __sync_lock_release_2 | |
| __sync_lock_release_4 | |
| __sync_lock_release_8 | |
| __sync_lock_release_16 | |
__atomic_load
__atomic_store
__atomic_is_lock_free
__atomic_load_1
__atomic_load_2
__atomic_load_4
__atomic_load_8
__atomic_load_16
__atomic_store_1
__atomic_store_2
__atomic_store_4
__atomic_store_8
__atomic_store_16
__atomic_add_fetch_1
__atomic_add_fetch_2
__atomic_add_fetch_4
__atomic_add_fetch_8
__atomic_add_fetch_16
__atomic_sub_fetch_1
__atomic_sub_fetch_2
__atomic_sub_fetch_4
__atomic_sub_fetch_8
__atomic_sub_fetch_16
__atomic_and_fetch_1
__atomic_and_fetch_2
__atomic_and_fetch_4
__atomic_and_fetch_8
__atomic_and_fetch_16
__atomic_or_fetch_1
__atomic_or_fetch_2
__atomic_or_fetch_4
__atomic_or_fetch_8
__atomic_or_fetch_16
__atomic_xor_fetch_1
__atomic_xor_fetch_2
__atomic_xor_fetch_4
__atomic_xor_fetch_8
__atomic_xor_fetch_16
__atomic_nand_fetch_1
__atomic_nand_fetch_2
__atomic_nand_fetch_4
__atomic_nand_fetch_8
__atomic_nand_fetch_16
__atomic_fetch_add_1
__atomic_fetch_add_2
__atomic_fetch_add_4
__atomic_fetch_add_8
__atomic_fetch_add_16
__atomic_fetch_sub_1
__atomic_fetch_sub_2
__atomic_fetch_sub_4
__atomic_fetch_sub_8
__atomic_fetch_sub_16
__atomic_fetch_and_1
__atomic_fetch_and_2
__atomic_fetch_and_4
__atomic_fetch_and_8
__atomic_fetch_and_16
__atomic_fetch_or_1
__atomic_fetch_or_2
__atomic_fetch_or_4
__atomic_fetch_or_8
__atomic_fetch_or_16
__atomic_fetch_xor_1
__atomic_fetch_xor_2
__atomic_fetch_xor_4
__atomic_fetch_xor_8
__atomic_fetch_xor_16
__atomic_fetch_nand_1
__atomic_fetch_nand_2
__atomic_fetch_nand_4
__atomic_fetch_nand_8
__atomic_fetch_nand_16
__sync_synchronize
__sync_fetch_and_add_1
__sync_fetch_and_add_2
__sync_fetch_and_add_4
__sync_fetch_and_add_8
__sync_fetch_and_add_16
__sync_fetch_and_sub_1
__sync_fetch_and_sub_2
__sync_fetch_and_sub_4
__sync_fetch_and_sub_8
__sync_fetch_and_sub_16
__sync_fetch_and_and_1
__sync_fetch_and_and_2
__sync_fetch_and_and_4
__sync_fetch_and_and_8
__sync_fetch_and_and_16
__sync_fetch_and_or_1
__sync_fetch_and_or_2
__sync_fetch_and_or_4
__sync_fetch_and_or_8
__sync_fetch_and_or_16
__sync_fetch_and_xor_1
__sync_fetch_and_xor_2
__sync_fetch_and_xor_4
__sync_fetch_and_xor_8
__sync_fetch_and_xor_16
__sync_fetch_and_nand_1
__sync_fetch_and_nand_2
__sync_fetch_and_nand_4
__sync_fetch_and_nand_8
__sync_fetch_and_nand_16
__sync_add_and_fetch_1
__sync_add_and_fetch_2
__sync_add_and_fetch_4
__sync_add_and_fetch_8
__sync_add_and_fetch_16
__sync_sub_and_fetch_1
__sync_sub_and_fetch_2
__sync_sub_and_fetch_4
__sync_sub_and_fetch_8
__sync_sub_and_fetch_16
__sync_and_and_fetch_1
__sync_and_and_fetch_2
__sync_and_and_fetch_4
__sync_and_and_fetch_8
__sync_and_and_fetch_16
__sync_or_and_fetch_1
__sync_or_and_fetch_2
__sync_or_and_fetch_4
__sync_or_and_fetch_8
__sync_or_and_fetch_16
__sync_xor_and_fetch_1
__sync_xor_and_fetch_2
__sync_xor_and_fetch_4
__sync_xor_and_fetch_8
__sync_xor_and_fetch_16
__sync_nand_and_fetch_1
__sync_nand_and_fetch_2
__sync_nand_and_fetch_4
__sync_nand_and_fetch_8
__sync_nand_and_fetch_16
__sync_bool_compare_and_swap_1
__sync_bool_compare_and_swap_2
__sync_bool_compare_and_swap_4
__sync_bool_compare_and_swap_8
__sync_bool_compare_and_swap_16
__sync_val_compare_and_swap_1
__sync_val_compare_and_swap_2
__sync_val_compare_and_swap_4
__sync_val_compare_and_swap_8
__sync_val_compare_and_swap_16
__sync_lock_test_and_set_1
__sync_lock_test_and_set_2
__sync_lock_test_and_set_4
__sync_lock_test_and_set_8
__sync_lock_test_and_set_16
__sync_lock_release_1
__sync_lock_release_2
__sync_lock_release_4
__sync_lock_release_8
__sync_lock_release_16
External function interface
This section summarises the functions to be provided by the
implementor when integrating emRun into an application
or library.
I/O functions
| Function | Description |
|---|
| __SEGGER_RTL_X_file_open | Open file. |
| __SEGGER_RTL_X_file_error | Test for file-error condition. |
| __SEGGER_RTL_X_file_end | Test for end-of-file condition. |
| __SEGGER_RTL_X_file_stat | Get file status. |
| __SEGGER_RTL_X_file_bufsize | Get stream buffer size. |
| __SEGGER_RTL_X_file_flush | Flush unwritten data to file. |
| __SEGGER_RTL_X_file_getpos | Get file position. |
| __SEGGER_RTL_X_file_seek | Set file position. |
| __SEGGER_RTL_X_file_clrerr | Clear file-error status. |
| __SEGGER_RTL_X_file_close | Close file. |
| __SEGGER_RTL_X_file_read | Read from file. |
| __SEGGER_RTL_X_file_write | Read from file. |
| __SEGGER_RTL_X_file_rename | Rename file. |
| __SEGGER_RTL_X_file_remove | Remove file. |
| __SEGGER_RTL_X_file_tmpnam | Generate name for temporary file. |
| __SEGGER_RTL_X_file_tmpfile | Generate temporary file. |
| __SEGGER_RTL_X_file_unget | Push character back to file. |
__SEGGER_RTL_X_file_open()
Description
Open file.
Prototype
__SEGGER_RTL_FILE *__SEGGER_RTL_X_file_open(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. |
__SEGGER_RTL_X_file_error()
Description
Test for file-error condition.
Prototype
int __SEGGER_RTL_X_file_error(__SEGGER_RTL_FILE *stream);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file. |
Return value
| < 0 | Failure, stream is closed. |
| = 0 | Success, stream is not in error. |
| > 0 | Success, stream is in error. |
__SEGGER_RTL_X_file_end()
Description
Test for end-of-file condition.
Prototype
int __SEGGER_RTL_X_file_end(__SEGGER_RTL_FILE *stream);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file. |
Return value
| < 0 | Failure, stream is closed. |
| = 0 | Success, stream is not at end of file. |
| > 0 | Success, stream is at end of file. |
__SEGGER_RTL_X_file_stat()
Description
Get file status.
Prototype
int __SEGGER_RTL_X_file_stat(__SEGGER_RTL_FILE *stream);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file. |
Return value
| < 0 | Failure, stream is not a valid file. |
| ≥ 0 | Success, stream is a valid 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.
__SEGGER_RTL_X_file_bufsize()
Description
Get stream buffer size.
Prototype
int __SEGGER_RTL_X_file_bufsize(__SEGGER_RTL_FILE *stream);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file. |
Return value
Nonzero number of characters to use for buffered I/O; for
unbuffered I/O, return 1.
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.
__SEGGER_RTL_X_file_flush()
Description
Flush unwritten data to file.
Prototype
int __SEGGER_RTL_X_file_flush(__SEGGER_RTL_FILE *stream);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file. |
Return value
| < 0 | Failure, file cannot be flushed or was not successfully flushed. |
| = 0 | Success, unwritten data is flushed. |
__SEGGER_RTL_X_file_getpos()
Description
Get file position.
Prototype
int __SEGGER_RTL_X_file_getpos( __SEGGER_RTL_FILE *stream,
fpos_t * pos);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file. |
| pos | Pointer to object that receives the position. |
Return value
| = 0 | Position retrieved successfully. |
| < 0 | Position not retrieved successfully. |
__SEGGER_RTL_X_file_seek()
Description
Set file position.
Prototype
int __SEGGER_RTL_X_file_seek( __SEGGER_RTL_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. |
__SEGGER_RTL_X_file_clrerr()
Description
Clear file-error status.
Prototype
void __SEGGER_RTL_X_file_clrerr(__SEGGER_RTL_FILE *stream);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file. |
__SEGGER_RTL_X_file_close()
Description
Close file.
Prototype
int __SEGGER_RTL_X_file_close(__SEGGER_RTL_FILE *stream);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file. |
Return value
| < 0 | Failure, stream is already closed. |
| ≥ 0 | Success, stream is closed. |
Additional information
Close the file stream. If the stream is connected to a temporary
file (by use of tmpfile()), the temporary file is deleted.
__SEGGER_RTL_X_file_read()
Description
Read from file.
Prototype
int __SEGGER_RTL_X_file_read( __SEGGER_RTL_FILE *stream,
char * s,
unsigned len);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file to read from. |
| s | Pointer to object to write to. |
| len | Number of characters to read. |
Return value
The number of characters successfully read, which may be less than
len if a read error or end-of-file is encountered.
__SEGGER_RTL_X_file_write()
Description
Read from file.
Prototype
int __SEGGER_RTL_X_file_write( __SEGGER_RTL_FILE *stream,
const char * s,
unsigned len);
Parameters
| Parameter | Description |
|---|
| stream | Pointer to file to read from. |
| s | Pointer to object to write. |
| len | Number of characters to write. |
Return value
The number of characters successfully written, which may be less than
len if an error occurs.
__SEGGER_RTL_X_file_rename()
Description
Rename file.
Prototype
int __SEGGER_RTL_X_file_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. |
__SEGGER_RTL_X_file_remove()
Description
Remove file.
Prototype
int __SEGGER_RTL_X_file_remove(const char * filename);
Parameters
| Parameter | Description |
|---|
| filename | Pointer to string denoting file name to remove. |
Return value
| = 0 | Remove succeeded. |
| ≠ 0 | Remove failed. |
__SEGGER_RTL_X_file_tmpnam()
Description
Generate name for temporary file.
Prototype
char *__SEGGER_RTL_X_file_tmpnam(char * s,
unsigned max);
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. |
| max | Maxumum number of characters acceptable in the object s. |
Return value
| = NULL | Cannot generate a unique temporary name. |
| ≠ NULL | Pointer to temporary name generated. |
__SEGGER_RTL_X_file_tmpfile()
Description
Generate temporary file.
Prototype
__SEGGER_RTL_FILE *__SEGGER_RTL_X_file_tmpfile(void);
Return value
| = NULL | Cannot generate a unique temporary file. |
| ≠ NULL | Pointer to temporary file. |
__SEGGER_RTL_X_file_unget()
Description
Push character back to file.
Prototype
int __SEGGER_RTL_X_file_unget( __SEGGER_RTL_FILE *stream,
int c);
Parameters
| Parameter | Description |
|---|
| stream | File to push character to. |
| c | Character to push back to file. |
Return value
| = EOF | Failed to push character back. |
| ≠ EOF | The character pushed back to the file. |
Additional information
This function pushes the character c back to the file stream so
that it can be read again. If c is EOF, the function fails and
EOF is returned. One character of pushback is guaranteed; if more
than one character is pushed back without an intervening read,
the pushback may fail.
Heap functions
| Function | Description |
|---|
| __SEGGER_RTL_init_heap | Initializes the heap. |
| __SEGGER_RTL_X_heap_lock | Lock heap. |
| __SEGGER_RTL_X_heap_unlock | Unlock heap. |
__SEGGER_RTL_init_heap()
Description
Initializes the heap.
Prototype
void __SEGGER_RTL_init_heap(void * ptr,
size_t size);
Parameters
| Parameter | Description |
|---|
| ptr | Pointer to correctly-aligned heap memory to manage. |
| size | Size of managed area in bytes. |
__SEGGER_RTL_X_heap_lock()
Description
Lock heap.
Prototype
void __SEGGER_RTL_X_heap_lock(void);
Additional information
This function is called to lock access to the heap before
allocation or deallocation is processed. This is only
required for multitasking systems where heap operations
may possibly be called called from different threads.
__SEGGER_RTL_X_heap_unlock()
Description
Unlock heap.
Prototype
void __SEGGER_RTL_X_heap_unlock(void);
Additional information
This function is called to unlock access to the heap after
allocation or deallocation has completed. This is only
required for multitasking systems where heap operations
may possibly be called called from different threads.
Atomic functions
| Function | Description |
|---|
| __SEGGER_RTL_X_atomic_lock | Lock for atomic access. |
| __SEGGER_RTL_X_atomic_unlock | Unlock atomic access. |
| __SEGGER_RTL_X_atomic_synchronize | Full memory barrier. |
__SEGGER_RTL_X_atomic_lock()
Description
Lock for atomic access.
Prototype
int __SEGGER_RTL_X_atomic_lock(void);
Return value
User-defined value to be passed to matching atomic unlock.
Additional information
This function is called to provide exclusive access to an object.
Typically, interrupts are disabled by the function, but in a
multi-tasking system a mutex can be used.
__SEGGER_RTL_X_atomic_unlock()
Description
Unlock atomic access.
Prototype
void __SEGGER_RTL_X_atomic_unlock(int state);
Parameters
| Parameter | Description |
|---|
| state | Value returned by __SEGGER_RTL_X_atomic_lock(). |
Additional information
This function is called to relinquish previously-locked atomic
access.
__SEGGER_RTL_X_atomic_synchronize()
Description
Full memory barrier.
Prototype
void __SEGGER_RTL_X_atomic_synchronize(void);
Additional information
This function is called to ensure all memory reads and writes
are complete before continuing.
Error and assertion functions
| Function | Description |
|---|
| __SEGGER_RTL_X_assert | User-defined behavior for the assert macro. |
| __SEGGER_RTL_X_errno_addr | Return pointer to object holding errno. |
__SEGGER_RTL_X_assert()
Description
User-defined behavior for the assert macro.
Prototype
void __SEGGER_RTL_X_assert(const char * expr,
const char * filename,
int line);
Parameters
| Parameter | Description |
|---|
| expr | Stringized expression that caused failure. |
| filename | Filename of the source file where the failure was signaled. |
| line | Line number of the failed assertion. |
Additional information
The default implementation of __SEGGER_RTL_X_assert() prints the
filename, line, and error message to standard output and then
calls abort().
__SEGGER_RTL_X_assert() is defined as a weak function and can be
replaced by user code.
__SEGGER_RTL_X_errno_addr()
Description
Return pointer to object holding errno.
Prototype
int *__SEGGER_RTL_X_errno_addr(void);
Return value
Pointer to errno object.
Additional information
The default implementation of this function is to return the
address of a variable declared with the __SEGGER_RTL_STATE_THREAD
storage class. Thus, for multithreaded environments that
implement thread-local variables through __SEGGER_RTL_STATE_THREAD,
each thread receives its own thread-local errno.
It is beyond the scope of this manual to describe how
thread-local variables are implemented by the compiler and
any associated real-time operating system.
When __SEGGER_RTL_STATE_THREAD is defined as an empty macro, this
function returns the address of a singleton errno object.
Appendices
The following benchmarks of the low-level floating-point arithmetic functions
show expected performance of each archttecture, measured on the same device.
For the RISC-V benchmarks, the device is a TLS9518A executing from
instruction-local memory.
RV32I benchmarks
IEEE-754 Floating-point Library Benchmarks
Copyright (c) 2018-2022 SEGGER Microcontroller GmbH.
System: emRun v2.26.0
Target: RV32I
Target: Little-endian byte order
Config: SEGGER_RTL_OPTIMIZE = 2
Config: SEGGER_RTL_FP_HW = 0 // No FPU, software floating point
Config: SEGGER_RTL_FP_ABI = 0 // Floats and doubles in core registers
Config: With assembly-coded acceleration
Config: With fully conformant NaNs
======================
GNU libgcc API
======================
Function Min Max Avg Description
-------------- ------ ------ ------ -------------------------------
__addsf3 37 50 43.1 Random distribution over (0, 1), operands differ
__subsf3 31 58 48.9 Random distribution over (0, 1), operands differ
__mulsf3 238 324 269.3 Random distribution over (0, 1), operands differ
__divsf3 149 222 186.7 Random distribution over (0, 1), operands differ
__ltsf2 9 13 9.8 Random distribution over (0, 1), operands differ
__lesf2 8 12 9.6 Random distribution over (0, 1), operands differ
__gtsf2 9 12 10.2 Random distribution over (0, 1), operands differ
__gesf2 10 14 11.7 Random distribution over (0, 1), operands differ
__eqsf2 9 12 10.1 Random distribution over (0, 1), operands differ
__nesf2 9 12 10.1 Random distribution over (0, 1), operands differ
__adddf3 43 70 56.0 Random distribution over (0, 1), operands differ
__subdf3 51 110 74.3 Random distribution over (0, 1), operands differ
__muldf3 877 1010 936.8 Random distribution over (0, 1), operands differ
__divdf3 707 991 898.8 Random distribution over (0, 1), operands differ
__ltdf2 11 17 13.4 Random distribution over (0, 1), operands differ
__ledf2 12 19 14.1 Random distribution over (0, 1), operands differ
__gtdf2 11 17 13.7 Random distribution over (0, 1), operands differ
__gedf2 12 18 14.4 Random distribution over (0, 1), operands differ
__eqdf2 13 16 14.3 Random distribution over (0, 1), operands differ
__eqdf2 13 16 14.3 Random distribution over (0, 1), operands differ
__fixsfsi 4 16 9.2 Random distribution over (-2^31.., 1..2^31)
__fixunssfsi 2 12 5.2 Random distribution over (1..2^31)
__fixsfdi 5 22 18.5 Random distribution over (-2^63..1, 1..2^63)
__fixunssfdi 5 19 15.5 Random distribution over (-2^63..2^63)
__floatsisf 27 36 31.2 Random distribution over (-2^31.., 1..2^31)
__floatunsisf 20 28 24.3 Random distribution over (1..2^31)
__floatdisf 28 51 35.3 Random distribution over (-2^63..1, 1..2^63)
__floatundisf 23 43 31.0 Random distribution over (-2^63..2^63)
__fixdfsi 3 16 8.2 Random distribution over (-2^31.., 1..2^31)
__fixunsdfsi 3 8 4.9 Random distribution over (1..2^31)
__fixdfdi 6 29 23.7 Random distribution over (-2^63..1, 1..2^63)
__fixunsdfdi 6 23 19.3 Random distribution over (-2^63..2^63)
__floatsidf 20 28 23.2 Random distribution over (-2^31.., 1..2^31)
__floatunsidf 15 23 19.1 Random distribution over (1..2^31)
__floatdidf 22 55 37.3 Random distribution over (-2^63..1, 1..2^63)
__floatundidf 21 47 31.4 Random distribution over (-2^63..2^63)
__extendsfdf2 8 12 9.9 Random distribution over (-2^63..1, 1..2^63)
__truncdfsf2 4 25 21.9 Random distribution over (-2^63..1, 1..2^63)
Total cycles: 10924741
RV32IMC benchmarks
IEEE-754 Floating-point Library Benchmarks
Copyright (c) 2018-2022 SEGGER Microcontroller GmbH.
System: emRun v2.26.0
Target: RV32IMC
Target: Little-endian byte order
Config: SEGGER_RTL_OPTIMIZE = 2
Config: SEGGER_RTL_FP_HW = 0 // No FPU, software floating point
Config: SEGGER_RTL_FP_ABI = 0 // Floats and doubles in core registers
Config: With assembly-coded acceleration
Config: With fully conformant NaNs
======================
GNU libgcc API
======================
Function Min Max Avg Description
-------------- ------ ------ ------ -------------------------------
__addsf3 36 46 40.6 Random distribution over (0, 1), operands differ
__subsf3 29 66 49.8 Random distribution over (0, 1), operands differ
__mulsf3 30 38 33.1 Random distribution over (0, 1), operands differ
__divsf3 64 66 64.5 Random distribution over (0, 1), operands differ
__ltsf2 7 9 8.4 Random distribution over (0, 1), operands differ
__lesf2 7 8 7.0 Random distribution over (0, 1), operands differ
__gtsf2 6 8 6.8 Random distribution over (0, 1), operands differ
__gesf2 7 9 8.4 Random distribution over (0, 1), operands differ
__eqsf2 6 8 6.7 Random distribution over (0, 1), operands differ
__nesf2 6 8 6.7 Random distribution over (0, 1), operands differ
__adddf3 43 67 55.0 Random distribution over (0, 1), operands differ
__subdf3 47 105 72.4 Random distribution over (0, 1), operands differ
__muldf3 64 79 69.8 Random distribution over (0, 1), operands differ
__divdf3 194 201 197.7 Random distribution over (0, 1), operands differ
__ltdf2 9 13 9.8 Random distribution over (0, 1), operands differ
__ledf2 9 14 10.5 Random distribution over (0, 1), operands differ
__gtdf2 10 15 11.2 Random distribution over (0, 1), operands differ
__gedf2 10 14 10.9 Random distribution over (0, 1), operands differ
__eqdf2 10 12 10.7 Random distribution over (0, 1), operands differ
__eqdf2 10 12 11.5 Random distribution over (0, 1), operands differ
__fixsfsi 1 13 6.3 Random distribution over (-2^31.., 1..2^31)
__fixunssfsi 1 8 3.3 Random distribution over (1..2^31)
__fixsfdi 3 18 15.5 Random distribution over (-2^63..1, 1..2^63)
__fixunssfdi 3 14 11.3 Random distribution over (-2^63..2^63)
__floatsisf 24 33 28.6 Random distribution over (-2^31.., 1..2^31)
__floatunsisf 20 26 22.7 Random distribution over (1..2^31)
__floatdisf 32 52 37.7 Random distribution over (-2^63..1, 1..2^63)
__floatundisf 27 45 33.0 Random distribution over (-2^63..2^63)
__fixdfsi 2 17 6.6 Random distribution over (-2^31.., 1..2^31)
__fixunsdfsi 2 7 3.6 Random distribution over (1..2^31)
__fixdfdi 6 28 22.2 Random distribution over (-2^63..1, 1..2^63)
__fixunsdfdi 5 22 18.2 Random distribution over (-2^63..2^63)
__floatsidf 19 25 21.8 Random distribution over (-2^31.., 1..2^31)
__floatunsidf 12 20 15.8 Random distribution over (1..2^31)
__floatdidf 23 52 37.8 Random distribution over (-2^63..1, 1..2^63)
__floatundidf 21 44 30.8 Random distribution over (-2^63..2^63)
__extendsfdf2 10 11 10.3 Random distribution over (-2^63..1, 1..2^63)
__truncdfsf2 6 26 23.7 Random distribution over (-2^63..1, 1..2^63)
Total cycles: 2862096
RV32IMCP
IEEE-754 Floating-point Library Benchmarks
Copyright (c) 2018-2022 SEGGER Microcontroller GmbH.
System: emRun v2.26.0
Target: RV32IMACP
Target: Little-endian byte order
Config: SEGGER_RTL_OPTIMIZE = 2
Config: SEGGER_RTL_FP_HW = 0 // No FPU, software floating point
Config: SEGGER_RTL_FP_ABI = 0 // Floats and doubles in core registers
Config: With assembly-coded acceleration
Config: With RISC-V SIMD acceleration
Config: With fully conformant NaNs
======================
GNU libgcc API
======================
Function Min Max Avg Description
-------------- ------ ------ ------ -------------------------------
__addsf3 35 45 40.5 Random distribution over (0, 1), operands differ
__subsf3 29 51 37.4 Random distribution over (0, 1), operands differ
__mulsf3 29 37 32.8 Random distribution over (0, 1), operands differ
__divsf3 63 65 63.7 Random distribution over (0, 1), operands differ
__ltsf2 7 10 8.4 Random distribution over (0, 1), operands differ
__lesf2 6 7 6.5 Random distribution over (0, 1), operands differ
__gtsf2 6 7 6.5 Random distribution over (0, 1), operands differ
__gesf2 7 9 8.0 Random distribution over (0, 1), operands differ
__eqsf2 6 8 6.4 Random distribution over (0, 1), operands differ
__nesf2 6 8 6.4 Random distribution over (0, 1), operands differ
__adddf3 42 66 54.3 Random distribution over (0, 1), operands differ
__subdf3 48 87 64.7 Random distribution over (0, 1), operands differ
__muldf3 63 78 69.5 Random distribution over (0, 1), operands differ
__divdf3 193 198 197.0 Random distribution over (0, 1), operands differ
__ltdf2 10 13 11.4 Random distribution over (0, 1), operands differ
__ledf2 10 13 10.8 Random distribution over (0, 1), operands differ
__gtdf2 10 14 11.5 Random distribution over (0, 1), operands differ
__gedf2 10 14 11.9 Random distribution over (0, 1), operands differ
__eqdf2 11 13 11.5 Random distribution over (0, 1), operands differ
__eqdf2 11 13 11.8 Random distribution over (0, 1), operands differ
__fixsfsi 1 13 6.4 Random distribution over (-2^31.., 1..2^31)
__fixunssfsi 1 8 3.5 Random distribution over (1..2^31)
__fixsfdi 1 17 13.6 Random distribution over (-2^63..1, 1..2^63)
__fixunssfdi 4 16 11.8 Random distribution over (-2^63..2^63)
__floatsisf 15 19 16.4 Random distribution over (-2^31.., 1..2^31)
__floatunsisf 8 13 9.0 Random distribution over (1..2^31)
__floatdisf 19 28 23.4 Random distribution over (-2^63..1, 1..2^63)
__floatundisf 11 21 17.6 Random distribution over (-2^63..2^63)
__fixdfsi 3 17 7.4 Random distribution over (-2^31.., 1..2^31)
__fixunsdfsi 1 7 4.0 Random distribution over (1..2^31)
__fixdfdi 4 26 20.8 Random distribution over (-2^63..1, 1..2^63)
__fixunsdfdi 3 21 17.2 Random distribution over (-2^63..2^63)
__floatsidf 9 11 9.6 Random distribution over (-2^31.., 1..2^31)
__floatunsidf 3 4 3.7 Random distribution over (1..2^31)
__floatdidf 14 35 25.0 Random distribution over (-2^63..1, 1..2^63)
__floatundidf 11 28 19.9 Random distribution over (-2^63..2^63)
__extendsfdf2 5 7 6.0 Random distribution over (-2^63..1, 1..2^63)
__truncdfsf2 6 26 24.0 Random distribution over (-2^63..1, 1..2^63)
Total cycles: 2771332
IEEE-754 Floating-point Library Benchmarks
Copyright (c) 2018-2022 SEGGER Microcontroller GmbH.
System: emRun v2.26.0
Target: RV32IMACP
Target: Little-endian byte order
Config: SEGGER_RTL_OPTIMIZE = 2
Config: SEGGER_RTL_FP_HW = 0 // No FPU, software floating point
Config: SEGGER_RTL_FP_ABI = 0 // Floats and doubles in core registers
Config: With assembly-coded acceleration
Config: With RISC-V SIMD acceleration
Config: With Andes V5 Performance Extension acceleration
Config: With fully conformant NaNs
======================
GNU libgcc API
======================
Function Min Max Avg Description
-------------- ------ ------ ------ -------------------------------
__addsf3 32 41 36.8 Random distribution over (0, 1), operands differ
__subsf3 26 47 34.3 Random distribution over (0, 1), operands differ
__mulsf3 27 35 30.7 Random distribution over (0, 1), operands differ
__divsf3 57 58 58.0 Random distribution over (0, 1), operands differ
__ltsf2 8 10 8.5 Random distribution over (0, 1), operands differ
__lesf2 8 9 8.4 Random distribution over (0, 1), operands differ
__gtsf2 7 10 8.2 Random distribution over (0, 1), operands differ
__gesf2 8 10 8.5 Random distribution over (0, 1), operands differ
__eqsf2 7 8 7.5 Random distribution over (0, 1), operands differ
__nesf2 7 8 7.5 Random distribution over (0, 1), operands differ
__adddf3 39 63 51.6 Random distribution over (0, 1), operands differ
__subdf3 45 77 60.8 Random distribution over (0, 1), operands differ
__muldf3 64 76 69.2 Random distribution over (0, 1), operands differ
__divdf3 193 200 197.0 Random distribution over (0, 1), operands differ
__ltdf2 10 13 11.6 Random distribution over (0, 1), operands differ
__ledf2 9 12 10.7 Random distribution over (0, 1), operands differ
__gtdf2 9 14 11.4 Random distribution over (0, 1), operands differ
__gedf2 11 12 11.2 Random distribution over (0, 1), operands differ
__eqdf2 11 12 12.0 Random distribution over (0, 1), operands differ
__eqdf2 11 12 12.0 Random distribution over (0, 1), operands differ
__fixsfsi 2 13 6.7 Random distribution over (-2^31.., 1..2^31)
__fixunssfsi 1 8 3.9 Random distribution over (1..2^31)
__fixsfdi 2 17 14.8 Random distribution over (-2^63..1, 1..2^63)
__fixunssfdi 4 16 12.8 Random distribution over (-2^63..2^63)
__floatsisf 13 17 14.2 Random distribution over (-2^31.., 1..2^31)
__floatunsisf 7 11 8.0 Random distribution over (1..2^31)
__floatdisf 18 26 21.9 Random distribution over (-2^63..1, 1..2^63)
__floatundisf 10 19 15.7 Random distribution over (-2^63..2^63)
__fixdfsi 3 17 8.1 Random distribution over (-2^31.., 1..2^31)
__fixunsdfsi 2 9 4.4 Random distribution over (1..2^31)
__fixdfdi 3 26 20.5 Random distribution over (-2^63..1, 1..2^63)
__fixunsdfdi 4 22 17.7 Random distribution over (-2^63..2^63)
__floatsidf 9 11 9.8 Random distribution over (-2^31.., 1..2^31)
__floatunsidf 4 5 4.1 Random distribution over (1..2^31)
__floatdidf 14 32 23.7 Random distribution over (-2^63..1, 1..2^63)
__floatundidf 10 28 19.0 Random distribution over (-2^63..2^63)
__extendsfdf2 6 8 6.7 Random distribution over (-2^63..1, 1..2^63)
__truncdfsf2 6 22 20.0 Random distribution over (-2^63..1, 1..2^63)
Total cycles: 2707282