📄 AppWizard User Guide & Reference Manual
📄 embOS & embOS-MPU User Guide & Reference Manual
📄 emCompress-Embed User Guide & Reference Manual
📄 emCompress-Flex User Guide & Reference Manual
📄 emCompress-ToGo User Guide & Reference Manual
📄 emCrypt User Guide & Reference Manual
📄 emDropbox User Guide & Reference Manual
📄 emFile User Guide & Reference Manual
📄 emNet User Guide & Reference Manual
📄 emSecure-ECDSA User Guide & Reference Manual
📄 emSecure-RSA User Guide & Reference Manual
📄 emSSH User Guide & Reference Manual
📄 emSSL User Guide & Reference Manual
📄 emUSB-Device User Guide & Reference Manual
📄 emUSB-Host User Guide & Reference Manual
📄 emWeb User Guide & Reference Manual
📄 emWin User Guide & Reference Manual
📄 IoT Toolkit User Guide & Reference Manual
📄 SEGGER Assembler User Guide & Reference Manual
📄 SEGGER Floating-point Library User Guide & Reference Manual
📄 SEGGER Linker User Guide & Reference Manual
📄 SEGGER Runtime Library User Guide & Reference Manual

SEGGER Runtime Library User Guide & Reference Manual

A small, efficient C runtime library.

Introduction

This section presents an overview of SEGGER Runtime Library, its structure, and its capabilities.

What is the SEGGER Runtime Library?

SEGGER Runtime Library is an optimized C library for Arm and RISC-V processors.

Features

SEGGER Runtime Library 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 SEGGER Runtime Library:

We recommend keeping SEGGER Runtime Library 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 SEGGER Runtime Library by simply replacing the LIB directory. Your application files can be stored anywhere.

Note

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

Package content

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

Directory Description
Doc SEGGER Runtime Library documentation.
LIB SEGGER Runtime Library 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 SEGGER Runtime Library if you have old files included and therefore mix different versions. If you keep SEGGER Runtime Library 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 the SEGGER Runtime Library

User-facing source files

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

The user-facing interface files are:

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

In addition some private header files are required:

File Description
__libc.h General definitions used when compiling the library.
__libc_conf.h Configuration of the library.
__libc_conf_defaults.h Default configuration of the library.

Implementation source files

SEGGER Runtime Library 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 for the GNU GCC compiler.
basicops.c Support for simple I/O operations e.g. putc.
codesets.c Support for code pages used in locales
convops.c Support for conversion between binary and printable strings.
errno.c Support for errno in a tasking environment.
execops.c Support for execution control functions e.g. atexit().
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.
floatops_rv.c Support for high-level floating point functions (RISC-V).
heapops.c Support for dynamic memory functions e.g. malloc().
intops.c Support for high-level integer functions e.g. ldiv().
intops_rv.c Support for low-level integer functions (RISC-V).
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().
prinops_rtt.c Support for formatted output using RTT.
prinops_semi.c Support for formatted output using semihosting.
prinops_host.c Support for formatted output using semihosting with host-side formatting.
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().
strops_rv.c Support for string and memory functions (RISC-V).
timeops.c Support for time operations e.g. mktime().
utilops.c Support for SEGGER Runtime Library framework.
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().

Configuring the library

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

Symbol Description
__SEGGER_RTL_BYTE_ORDER Select the target’s byte order.
__SEGGER_RTL_SIZEOF_WCHAR_T Select size of the wchar_t type.
__SEGGER_RTL_SIZEOF_LONG Select size of long types.
__SEGGER_RTL_SIZEOF_PTR Select size of pointer types.
__SEGGER_RTL_OPTIMIZE Prefer size-optimized or speed-optimized code.
__SEGGER_RTL_HEAP_SIZE The size of the heap, in bytes.
__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_ATEXIT_COUNT The maximum number of registered atexit() functions.

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

Symbol Description
__thumb__ Assemble targeting the Thumb instruction set (as opposed to ARM).
__thumb2__ Assemble targeting the Thumb-2 instruction set.
__ARCH_V3 Assemble targeting ARMv3.
__ARCH_V4 Assemble targeting ARMv4.
__ARCH_V4T Assemble targeting ARMv4T.
__ARCH_V5TE Assemble targeting for ARMv5TE.
__ARCH_V6M Assemble targeting for ARMv6-M.
__ARCH_V7M Assemble targeting for ARMv7-M.
__ARCH_V7EM Assemble targeting for ARMv7E-M.
__FP_ABI_HARD__ Assemble targeting the hard floating point ABI.
__FPU_VFP__ Assemble targeting the vector FPU.
__FPV4_SP_D16__ Assemble targeting the single-precision v4 FPU.
__FPV5_SP_D16__ Assemble targeting the single-precision v5 FPU.
__LITTLE_ENDIAN Target little-endian processors.
__BIG_ENDIAN Target big-endian processors.

For RISC-V the default configuration of the library is derived from these preprocessor symbols:

Symbol Description
__riscv Target is RISC-V.
__riscv_abi_rve Assemble targeting RV32E.
__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_xlen Distinguish RV32 and RV64 targets.

The SEGGER Runtime Library configuration file

The configuration of SEGGER Runtime Library is defined by the content of __libc_conf.h which is included by all C and assembly language source files.

__SEGGER_RTL_BYTE_ORDER

Set this to -1 for little-endian byte order and +1 for big-endian byte order.

__SEGGER_RTL_SIZEOF_LONG

This preprocessor symbol must be set to the underlying size of long and must be 4 or 8.

__SEGGER_RTL_SIZEOF_PTR

This preprocessor symbol must be set to the underlying size of pointer types and must be 4 or 8.

__SEGGER_RTL_SIZEOF_WCHAR_T

This preprocessor symbol must be set to the underlying size of wchar_t. It is possible to select a specific implementation of wchar_t using command line switches, ensure that __SIZEOF_CHAR_T correctly reflects the size of the type.

Typical implementations of wchar_t are 16-bit and 32-bit quantities corresponding to UCS-2 and UCS-4 code points.

__SEGGER_RTL_OPTIMIZE

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.
+3 Favor speed at the expense of size and place code and read-only data in the fast section.

__SEGGER_RTL_HEAP_SIZE

The __SEGGER_RTL_HEAP_SIZE preprocessor symbol sets the size of the heap, in bytes, available to the application.

__SEGGER_RTL_FORMAT_INT_WIDTH

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.

__SEGGER_RTL_FORMAT_FLOAT_WIDTH

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 Reserved: support output of float values, no doubles.
2 Support output of float and double values.

__SEGGER_RTL_FORMAT_WCHAR

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.

__SEGGER_RTL_FORMAT_CHAR_CLASS

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.

__SEGGER_RTL_FORMAT_WIDTH_PRECISION

Set this preprocessor symbol to include width and precision suppoer 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.

__SEGGER_RTL_STDOUT_BUFFER_LEN

Set this preprocessor symbol to set the internal size of the formatting buffer, in characters, used by RTT and semihosting I/O.

__SEGGER_RTL_THREAD

Set this preprocessor symbol to the keyword that introduces thread-local storage, if using thread local storage. The GNU compiler, for instance, uses __thread to indicate thread-local data.

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 that invoked main().

Input and output

Input

For formatted input using scanf() and for functions such as gets() the library requires the user to implement the function __SEGGER_RTL_stdin_getc():

int __SEGGER_RTL_stdin_getc(void);

The return value should be EOF an error receiving a character, and in the case of success the code of the character received.

Output

For formatted output using printf() and for functions such as puts() the library requires the user to implement the function __SEGGER_RTL_stdout_putc():

int __SEGGER_RTL_stdout_putc(int c);

The parameter is the character to write to standard output. The return value should be EOF an error or non-negative to indicate success.

C library API

<assert.h>

Assertion functions

Function Description
assert Place assertion.
__SEGGER_RTL_X_assert User-defined behavior for the assert macro.
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 asser is executed and e is false, assert() calls the __SEGGER_RTL_X_assert() function 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.

__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

There is no default implementation of __SEGGER_RTL_X_assert(). Keeping __SEGGER_RTL_X_assert() out of the library means that you can can customize its behavior without rebuilding the library. The user is responsible for implementing this function.

<ctype.h>

Classification functions

Function Description
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).
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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

<errno.h>

Errors

Error names

Description

Symbolic error names for raised errors.

Definition

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

Symbols

Definition Description
EDOM Domain error
EILSEQ Illegal multibyte sequence in conversion
ERANGE Range error
EHEAP Heap is corrupt
ENOMEM Out of memory
EINVAL Invalid parameter
errno

Description

Macro returning the current error.

Definition

#define errno    (*__SEGGER_RTL_X_errno())

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 library function.

<float.h>

Floating-point constants

Common parameters

Description

Applies to single-precision and double-precision formats.

Definition

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

Symbols

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

Description

IEEE 32-bit single-precision floating format parameters.

Definition

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

Symbols

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

Description

IEEE 64-bit double-precision floating format parameters.

Definition

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

Symbols

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

<iso646.h>

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

Macros

Replacement macros

Description

Standard replacement macros.

Definition

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

<limits.h>

Minima and maxima

Character minima and maxima

Description

Minimum and maximum values for character types.

Definition

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

Symbols

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

Description

Minimum and maximum values for short integer types.

Definition

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

Symbols

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

Description

Minimum and maximum values for integer types.

Definition

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

Symbols

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

Description

Minimum and maximum values for long integer types.

Definition

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

Symbols

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

Description

Minimum and maximum values for long integer types.

Definition

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

Symbols

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

Description

Minimum and maximum values for long integer types.

Definition

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

Symbols

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

Description

Maximum number of bytes in a multi-byte character.

Definition

#define MB_LEN_MAX    4

Symbols

Definition Description
MB_LEN_MAX Maximum

Additional information

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

<locale.h>

Data types

__SEGGER_RTL_lconv

Type definition

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

Structure members

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

Locale management

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

Description

Set locale.

Prototype

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

Parameters

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

Return value

Returns the name of the current locale.

Additional information

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().
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.

<math.h>

Exponential and logarithm functions

Function Description
sqrt() Compute square root, double.
sqrtf() Compute square root, float.
cbrt() Compute cube root, double.
cbrtf() Compute cube root, float.
exp() Compute base-e exponential, double.
expf() Compute base-e exponential, float.
expm1f() Compute base-e exponential, modified, double.
exp2() Compute base-2 exponential, double.
exp2f() Compute base-2 exponential, float.
exp10() Compute base-10 exponential, double.
exp10f() Compute base-10 exponential, float.
frexp() Set exponent, double.
frexpf() Set exponent, float.
hypot() Compute magnitude of complex, double.
hypotf() Compute magnitude of complex, float.
log() Compute natural logarithm, double.
logf() Compute natural logarithm, float.
log10() Compute common logarithm, double.
log10f() Compute common logarithm, float.
ldexp() Scale by power of two, double.
ldexpf() Scale by power of two, float.
pow() Raise to power, double.
powf() Raise to power, float.
scalbn() Scale, double.
scalbnf() Scale, float.
sqrt()

Description

Compute square root, double.

Prototype

double sqrt(double x);

Parameters

Parameter Description
x Value to compute square root of.

Return value

Additional information

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

sqrtf()

Description

Compute square root, float.

Prototype

float sqrtf(float x);

Parameters

Parameter Description
x Value to compute square root of.

Return value

Additional information

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

cbrt()

Description

Compute cube root, double.

Prototype

double cbrt(double x);

Parameters

Parameter Description
x Value to compute cube root of.

Return value

cbrtf()

Description

Compute cube root, float.

Prototype

float cbrtf(float x);

Parameters

Parameter Description
x Value to compute cube root of.

Return value

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

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

expm1f()

Description

Compute base-e exponential, modified, double.

Prototype

float expm1f(float x);

Parameters

Parameter Description
x Value to compute exponential of.

Return value

exp2()

Description

Compute base-2 exponential, double.

Prototype

double exp2(double x);

Parameters

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

Return value

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

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

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

frexp()

Description

Set exponent, double.

Prototype

double frexp(double   x,
             int    * exp);

Parameters

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

Return value

Additional information

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

frexpf()

Description

Set exponent, float.

Prototype

float frexpf(float   x,
             int   * exp);

Parameters

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

Return value

Additional information

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

hypot()

Description

Compute magnitude of complex, double.

Prototype

double hypot(double x,
             double y);

Parameters

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

Return value

Additional information

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

hypotf()

Description

Compute magnitude of complex, float.

Prototype

float hypotf(float x,
             float y);

Parameters

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

Return value

Additional information

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

log()

Description

Compute natural logarithm, double.

Prototype

double log(double x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

logf()

Description

Compute natural logarithm, float.

Prototype

float logf(float x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

log10()

Description

Compute common logarithm, double.

Prototype

double log10(double x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

log10f()

Description

Compute common logarithm, float.

Prototype

float log10f(float x);

Parameters

Parameter Description
x Value to compute logarithm of.

Return value

ldexp()

Description

Scale by power of two, double.

Prototype

double ldexp(double x,
             int    n);

Parameters

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

Return value

Additional information

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

See also

scalbn()

ldexpf()

Description

Scale by power of two, float.

Prototype

float ldexpf(float x,
             int   n);

Parameters

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

Return value

Additional information

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

See also

scalbnf()

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.

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.

scalbn()

Description

Scale, double.

Prototype

double scalbn(double x,
              int    n);

Parameters

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

Return value

Additional information

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

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

See also

ldexpf()

scalbnf()

Description

Scale, float.

Prototype

float scalbnf(float x,
              int   n);

Parameters

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

Return value

Additional information

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

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

See also

ldexpf()

Trigonometric functions

Function Description
sin() Calculate sine, double.
sinf() Calculate sine, float.
cos() Calculate cosine, double.
cosf() Calculate cosine, float.
tan() Compute tangent, double.
tanf() Compute tangent, float.
sinh() Compute hyperbolic sine, double.
sinhf() Compute hyperbolic sine, float.
cosh() Compute hyperbolic cosine, double.
coshf() Compute hyperbolic cosine, float.
tanh() Compute hyperbolic tangent, double.
tanhf() Compute hyperbolic tangent, float.
sin()

Description

Calculate sine, double.

Prototype

double sin(double x);

Parameters

Parameter Description
x Angle to compute cosine of.

Return value

sinf()

Description

Calculate sine, float.

Prototype

float sinf(float x);

Parameters

Parameter Description
x Angle to compute sine of, radians.

Return value

cos()

Description

Calculate cosine, double.

Prototype

double cos(double x);

Parameters

Parameter Description
x Angle to compute cosine of, radians.

Return value

cosf()

Description

Calculate cosine, float.

Prototype

float cosf(float x);

Parameters

Parameter Description
x Angle to compute cosine of, radians.

Return value

tan()

Description

Compute tangent, double.

Prototype

double tan(double x);

Parameters

Parameter Description
x Angle to compute tangent of, radians.

Return value

tanf()

Description

Compute tangent, float.

Prototype

float tanf(float x);

Parameters

Parameter Description
x Angle to compute tangent of, radians.

Return value

sinh()

Description

Compute hyperbolic sine, double.

Prototype

double sinh(double x);

Parameters

Parameter Description
x Value to compute hyperbolic sine of.

Return value

sinhf()

Description

Compute hyperbolic sine, float.

Prototype

float sinhf(float x);

Parameters

Parameter Description
x Value to compute hyperbolic sine of.

Return value

cosh()

Description

Compute hyperbolic cosine, double.

Prototype

double cosh(double x);

Parameters

Parameter Description
x Value to compute hyperbolic cosine of.

Return value

coshf()

Description

Compute hyperbolic cosine, float.

Prototype

float coshf(float x);

Parameters

Parameter Description
x Value to compute hyperbolic cosine of.

Return value

tanh()

Description

Compute hyperbolic tangent, double.

Prototype

double tanh(double x);

Parameters

Parameter Description
x Value to compute hyperbolic tangent of.

Return value

tanhf()

Description

Compute hyperbolic tangent, float.

Prototype

float tanhf(float x);

Parameters

Parameter Description
x Value to compute hyperbolic tangent of.

Return value

Inverse trigonometric functions

Function Description
asin() Compute inverse sine, double.
asinf() Compute inverse sine, float.
acos() Compute inverse cosine, double.
acosf() Compute inverse cosine, float.
atan() Compute inverse tangent, double.
atanf() Compute inverse tangent, float.
atan2() Compute inverse tangent, with quadrant, double.
atan2f() Compute inverse tangent, with quadrant, float.
asinh() Compute inverse hyperbolic sine, double.
asinhf() Compute inverse hyperbolic sine, float.
acosh() Compute inverse hyperbolic cosine, double.
acoshf() Compute inverse hyperbolic cosine, float.
atanh() Compute inverse hyperbolic tangent, double.
atanhf() Compute inverse hyperbolic tangent, float.
asin()

Description

Compute inverse sine, double.

Prototype

double asin(double x);

Parameters

Parameter Description
x Value to compute inverse sine of.

Return value

Additional information

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

asinf()

Description

Compute inverse sine, float.

Prototype

float asinf(float x);

Parameters

Parameter Description
x Value to compute inverse sine of.

Return value

Additional information

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

acos()

Description

Compute inverse cosine, double.

Prototype

double acos(double x);

Parameters

Parameter Description
x Value to compute inverse cosine of.

Return value

Additional information

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

acosf()

Description

Compute inverse cosine, float.

Prototype

float acosf(float x);

Parameters

Parameter Description
x Value to compute inverse cosine of.

Return value

Additional information

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

atan()

Description

Compute inverse tangent, double.

Prototype

double atan(double x);

Parameters

Parameter Description
x Value to compute inverse tangent of.

Return value

Additional information

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

atanf()

Description

Compute inverse tangent, float.

Prototype

float atanf(float x);

Parameters

Parameter Description
x Value to compute inverse tangent of.

Return value

Additional information

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

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.

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.

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

Additional information

Calculates the inverse hyperbolic sine of x.

asinhf()

Description

Compute inverse hyperbolic sine, float.

Prototype

float asinhf(float x);

Parameters

Parameter Description
x Value to compute inverse hyperbolic sine of.

Return value

Additional information

Calculates the inverse hyperbolic sine of x.

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

Additional information

Calculates the non-negative inverse hyperbolic cosine of x.

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

Additional information

Calculates the non-negative inverse hyperbolic cosine of x.

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

Additional information

Calculates the non-negative inverse hyperbolic tangent of x.

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

Additional information

Calculates the non-negative inverse hyperbolic tangent of x.

Rounding and remainder functions

Function Description
ceil() Compute smallest integer not less than, double.
ceilf() Compute smallest integer not less than, float.
floor() Compute largest integer not greater than, double.
floorf() Compute largest integer not greater than, float.
fmod() Compute remainder after division, double.
fmodf() Compute remainder after division, float.
modf() Separate integer and fractional parts, double.
modff() Separate integer and fractional parts, float.
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

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

floor()

Description

Compute largest integer not greater than, double.

Prototype

double floor(double x);

Parameters

Parameter Description
x Value to floor.

Return value

floorf()

Description

Compute largest integer not greater than, float.

Prototype

float floorf(float x);

Parameters

Parameter Description
x Value to floor.

Return value

fmod()

Description

Compute remainder after division, double.

Prototype

double fmod(double x,
            double y);

Parameters

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

Return value

Additional information

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

fmodf()

Description

Compute remainder after division, float.

Prototype

float fmodf(float x,
            float y);

Parameters

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

Return value

Additional information

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

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.

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.

Absolute value functions

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

Description

Compute absolute value, double.

Prototype

double fabs(double x);

Parameters

Parameter Description
x Value to compute magnitude of.

Return value

fabsf()

Description

Compute absolute value, float.

Prototype

float fabsf(float x);

Parameters

Parameter Description
x Value to compute magnitude of.

Return value

Fused multiply functions

Function Description
fma() Compute fused multiply-add, double.
fmaf() Compute fused multiply-add, float.
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.

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.

Maximum, minimum, and positive difference functions

Function Description
fmin() Compute minimum, double.
fminf() Compute minimum, float.
fmax() Compute maximum, double.
fmaxf() Compute maximum, float.
fmin()

Description

Compute minimum, double.

Prototype

double fmin(double x,
            double y);

Parameters

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

Return value

fminf()

Description

Compute minimum, float.

Prototype

float fminf(float x,
            float y);

Parameters

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

Return value

fmax()

Description

Compute maximum, double.

Prototype

double fmax(double x,
            double y);

Parameters

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

Return value

fmaxf()

Description

Compute maximum, float.

Prototype

float fmaxf(float x,
            float y);

Parameters

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

Return value

<setjmp.h>

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.

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.

<stdbool.h>

Macros

bool

Description

Macros expanding to support the Boolean type.

Definition

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

Symbols

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

<stddef.h>

Macros

NULL

Description

Null-pointer constant.

Definition

#define NULL    0

Symbols

Definition Description
NULL Null pointer
offsetof

Description

Calculate offset of member from start of structure.

Definition

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

Symbols

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

Types

size_t

Description

Unsigned integral type returned by the sizeof operator.

Type definition

typedef __SEGGER_RTL_SIZE_T size_t;
ptrdiff_t

Description

Signed integral type of the result of subtracting two pointers.

Type definition

typedef __SEGGER_RTL_PTRDIFF_T ptrdiff_t;
wchar_t

Description

Integral type that can hold one wide character.

Type definition

typedef __SEGGER_RTL_WCHAR_T wchar_t;

<stdint.h>

Minima and maxima

Signed integer minima and maxima

Description

Minimum and maximum values for signed integer types.

Definition

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

Symbols

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

Description

Minimum and maximum values for unsigned integer types.

Definition

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

Symbols

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

Description

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

Definition

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

Symbols

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

Description

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

Definition

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

Symbols

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

Description

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

Definition

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

Symbols

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

Description

Minimum and maximum values for pointer-related types.

Definition

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

Symbols

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

Description

Minimum and maximum values for the wint_t type.

Definition

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

Symbols

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

Constant construction macros

Signed integer construction macros

Description

Macros that create constants of type intx_t.

Definition

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

Symbols

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

Description

Macros that create constants of type uintx_t.

Definition

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

Symbols

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

Description

Macros that create constants of type intmax_t and uintmax_t.

Definition

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

Symbols

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

<stdio.h>

Formatted output control strings

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

Composition

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

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

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

Flag characters

The flag characters and their meanings are:

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

The length modifiers and their meanings are:

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

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.

Formatted input control strings

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

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

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

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

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

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

Length modifiers

The length modifiers and their meanings are:

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

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.

Character and string I/O functions

Function Description
getchar() Read character from standard input.
gets() Read string from standard input.
putchar() Write character to standard output.
puts() Write string to standard output.
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.

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 new-line character is read. Any new-line character is discarded, and a null character is written immediately after the last character read into the array.

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 Ch to the standard output stream.

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 new-line character to the output. The terminating null character is not written.

Formatted input functions

Function Description
scanf() Formatted read from standard input.
sscanf() Formatted read from string.
vscanf() Formatted read from standard input, variadic.
vsscanf() Formatted read from string, variadic.
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 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.

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.

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.

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.

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.

Formatted output functions

Function Description
printf() Formatted write to standard output.
sprintf() Formatted write to string.
snprintf() Formatted write to string, limit length.
vprintf() Formatted write to standard output, variadic.
vsprintf() Formatted write to string, variadic.
vsnprintf() Formatted write to string, limit length, variadic.
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.

Notes

This implementation uses the SEGGER RTT service to write to the standard output stream.

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.

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.

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.

Notes

This implementation uses the SEGGER RTT service to write to the standard output stream.

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.

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.

<stdlib.h>

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.

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.

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.

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.

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.

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.

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.

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.

See also

rand()

Memory allocation functions

Function Description
malloc() Allocate space for 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 size and whose value is indeterminate.

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, malloc() 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.

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.

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.

Search and sort functions

Function Description
qsort() Sort array.
bsearch() Search sorted array.
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.

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.

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.

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.

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.

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.

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.

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.

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.
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).

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).

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).

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).

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.

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.

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.

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.

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.

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.

See also

strtof()

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).
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.

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-2008.

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);

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-2008.

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.

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-2008.

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.

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.

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.

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-2008.

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.

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-2008.

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.

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.

<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.
memcpy() Copy memory.
memccpy() Copy memory, specify terminator (POSIX.1).
mempcpy() Copy memory (GNU).
memmove() Copy memory, tolerate overlaps.
strcpy() Copy string.
strncpy() Copy string, limit length.
strlcpy() Copy string, limit length, always zero terminate (BSD).
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).
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 copy.
n Length of destination object in characters.

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.

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 the value of s1.

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.

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.

Notes

Conforms to POSIX.1-2008.

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.

Notes

This is an extension found in GNU libc.

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.

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.

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.

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.

Notes

Commonly found in BSD libraries and contrasts with strncpy() in that the resulting string is always terminated with a null character.

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.

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.

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.

Notes

Commonly found in BSD libraries.

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

Notes

Conforms to POSIX.1-2008 and SC22 TR 24731-2.

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.

Notes

Conforms to POSIX.1-2008 and SC22 TR 24731-2.

Comparison functions

Function Description
memcmp() Compare memory.
strcmp() Compare strings.
strncmp() Compare strings, limit length.
strcasecmp() Compare strings, ignore case (POSIX.1).
strncasecmp() Compare strings, ignore case, limit length (POSIX.1).
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.

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.

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.

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.

Notes

Conforms to POSIX.1-2008.

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.

Notes

Conforms to POSIX.1-2008.

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).
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, reentrant (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.

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 string.

Additional information

Locates the last occurrence of c (converted to a char) in the string pointed to by s.

Notes

Commonly found in Linux and BSD C libraries.

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.

Notes

Commonly found in Linux and BSD C libraries.

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.

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.

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.

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.

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.

Notes

Conforms to POSIX.1-2008.

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.

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.

Notes

Commonly found in Linux and BSD C libraries.

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 for.
s2 String to search.

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.

Notes

This extension is commonly found in Linux and BSD C libraries.

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 for.
s2 String to search.
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.

Notes

This extension is commonly found in Linux and BSD C libraries.

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.

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.

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.

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.

Notes

strtok() maintains static state and is therefore not reentrant and not thread safe. See strtok_r() for a thread-safe and reentrant variant.

See also

strsep(), strtok_r().

strtok_r()

Description

Break string into tokens, reentrant (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 reentrant version of the function strtok() where the state is maintained in the object of type char * pointed to by s3.

Notes

Conforms to POSIX.1-2008 and is commonly found in Linux and BSD C libraries.

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.

Notes

Commonly found in Linux and BSD C libraries.

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.

<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.

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.

Conversion functions

Function Description
ctime() Convert time_t to a string.
ctime_r() Convert time_t to a string, reentrant.
asctime() Convert time_t to a string.
asctime_r() Convert time_t to a string, reentrant.
gmtime() Convert time_t to struct tm.
gmtime_r() Convert time_t to struct tm, reentrant.
localtime() Convert time to local time.
localtime_r() Convert time to local time, reentrant.
strftime() Convert time to a string.
strftime_l() Convert time to a string.
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.

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.

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 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.

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.

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.

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.

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.

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.

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
%% %
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.

<wchar.h>

Copying functions

Function Description
wmemset() Set memory to wide character.
wmemcpy() Copy memory.
wmemccpy() Copy memory, specify terminator (POSIX.1).
wmempcpy() Copy memory (GNU).
wmemmove() Copy memory, tolerate overlaps.
wcscpy() Copy string.
wcsncpy() Copy string, limit length.
wcslcpy() Copy string, limit length, always zero terminate (BSD).
wcscat() Concatenate strings.
wcsncat() Concatenate strings, limit length.
wcslcat() Concatenate strings, limit length, always zero terminate (BSD).
wcsdup() Duplicate string (POSIX.1).
wcsndup() Duplicate string, limit length (GNU).
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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Comparison functions

Function Description
wmemcmp() Compare memory.
wcsncmp() Compare strings, limit length.
wcscasecmp() Compare strings, ignore case (POSIX.1).
wcsncasecmp() Compare strings, ignore case, limit length (POSIX.1).
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.

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.

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.

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.

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.
wcstok_r() Break string into tokens, reentrant (POSIX.1).
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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

wcstok()

Description

Break string into tokens.

Prototype

wchar_t *wcstok(      wchar_t * s1,
                const wchar_t * s2);

Parameters

Parameter Description
s1 Pointer to zero-terminated wide 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 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.

Notes

wcstok() maintains static state and is therefore not reentrant and not thread safe. See wcstok_r() for a thread-safe and reentrant variant.

See also

wcssep(), wcstok_r().

wcstok_r()

Description

Break string into tokens, reentrant (POSIX.1).

Prototype

wchar_t *wcstok_r(      wchar_t  * s1,
                  const wchar_t  * s2,
                        wchar_t ** lasts);

Parameters

Parameter Description
s1 Pointer to zero-terminated wide string to parse.
s2 Pointer to zero-terminated set of separators.
lasts Pointer to pointer to wchar_t that maintains parse state.

Return value

NULL if no further tokens else a pointer to the next token.

Additional information

wcstok_r() is a reentrant version of the function wcstok() where the state is maintained in the object of type wchar_t * pointed to by s3.

Notes

Conforms to POSIX.1-2008 and is commonly found in Linux and BSD C libraries.

See also

wcstok()

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.

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).
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.

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.

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-2008.

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.

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-2008.

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.

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.

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.

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.

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.

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-2008.

<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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

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.

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.

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.

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.

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.

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.

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”.

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.

<xlocale.h>

Locale management

Function Description
newlocale() Duplicate locale data (POSIX.1).
duplocale() Duplicate locale data (POSIX.1).
freelocale() Free locale (POSIX.1).
localeconv_l() Get locale data (POSIX.1).
newlocale()

Description

Duplicate locale data (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-2008.

POSIX.1-2008 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.

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-2008. 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-2008.

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-2008.

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-2008.

Runtime library API

GNU library API

Floating arithmetic

Function Description
__addsf3 Add, float.
__adddf3 Add, double.
__subsf3 Subtract, float.
__subdf3 Subtract, double.
__mulsf3 Multiply, float.
__muldf3 Multiply, double.
__divsf3 Divide, float.
__divdf3 Divide, double.
__addsf3()

Description

Add, float.

Prototype

float __addsf3(float x,
               float y);

Parameters

Parameter Description
x Augend.
y Addend.

Return value

Sum.

__adddf3()

Description

Add, double.

Prototype

double __adddf3(double x,
                double y);

Parameters

Parameter Description
x Augend.
y Addend.

Return value

Sum.

__subsf3()

Description

Subtract, float.

Prototype

float __subsf3(float x,
               float y);

Parameters

Parameter Description
x Minuend.
y Subtrahend.

Return value

Difference.

__subdf3()

Description

Subtract, double.

Prototype

double __subdf3(double x,
                double y);

Parameters

Parameter Description
x Minuend.
y Subtrahend.

Return value

Difference.

__mulsf3()

Description

Multiply, float.

Prototype

float __mulsf3(float x,
               float y);

Parameters

Parameter Description
x Multiplicand.
y Multiplier.

Return value

Product.

__muldf3()

Description

Multiply, double.

Prototype

double __muldf3(double x,
                double y);

Parameters

Parameter Description
x Multiplicand.
y Multiplier.

Return value

Product.

__divsf3()

Description

Divide, float.

Prototype

float __divsf3(float x,
               float y);

Parameters

Parameter Description
x Dividend.
y Divisor.

Return value

Quotient.

__divdf3()

Description

Divide, double.

Prototype

double __divdf3(double x,
                double y);

Parameters

Parameter Description
x Dividend.
y Divisor.

Return value

Quotient.

Floating conversions

Function Description
__fixsfsi Convert float to int.
__fixdfsi Convert double to int.
__fixsfdi Convert float to long long.
__fixdfdi Convert double to long long.
__fixunssfsi Convert float to unsigned.
__fixunsdfsi Convert double to unsigned.
__fixunssfdi Convert float to unsigned long long.
__fixunsdfdi Convert double to unsigned long long.
__floatsisf Convert int to float.
__floatsidf Convert int to double.
__floatdisf Convert long long to float.
__floatdidf Convert long long to double.
__floatunsisf Convert unsigned to float.
__floatunsidf Convert unsigned to double.
__floatundisf Convert unsigned long long to float.
__floatundidf Convert unsigned long long to double.
__extendsfdf2 Extend float to double.
__truncdfsf2 Truncate double to float.
__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.

__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.

__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.

__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.

__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.

__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.

__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.

__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.

__floatsisf()

Description

Convert int to float.

Prototype

float __floatsisf(__SEGGER_RTL_U32 x);

Parameters

Parameter Description
x Integer value to convert.

Return value

Floating value.

__floatsidf()

Description

Convert int to double.

Prototype

double __floatsidf(__SEGGER_RTL_U32 x);

Parameters

Parameter Description
x Integer value to convert.

Return value

Floating value.

__floatdisf()

Description

Convert long long to float.

Prototype

float __floatdisf(__SEGGER_RTL_U64 x);

Parameters

Parameter Description
x Integer value to convert.

Return value

Floating value.

__floatdidf()

Description

Convert long long to double.

Prototype

double __floatdidf(__SEGGER_RTL_U64 x);

Parameters

Parameter Description
x Integer value to convert.

Return value

Floating value.

__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.

__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.

__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.

__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.

__extendsfdf2()

Description

Extend float to double.

Prototype

double __extendsfdf2(float x);

Parameters

Parameter Description
x Float value to extend.

Return value

Double value.

__truncdfsf2()

Description

Truncate double to float.

Prototype

float __truncdfsf2(double x);

Parameters

Parameter Description
x Double value to truncate.

Return value

Float value.

Floating comparisons

Function Description
__eqsf2 Equal, float.
__eqsf2 Equal, float.
__nesf2 Not equal, float.
__nedf2 Not equal, double.
__ltsf2 Less than, float.
__ltdf2 Less than, double.
__lesf2 Less than or equal, float.
__ledf2 Less than or equal, double.
__gtsf2 Greater than, float.
__gtdf2 Greater than, double.
__gesf2 Greater than or equal, float.
__gedf2 Greater than or equal, double.
__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).

__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).

__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).

__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).

__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).

__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).

__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).

__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).

__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).

__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).

__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).

__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).