stdc
--background_C99--
Notes
On AROS standardized C interfaces are implemented with a few shared libraries. A distinction is made between a standard ANSI-C/ISO-C part and a POSIX emulation layer. Here the ANSI-C/ISO-C part is documented. The ANSI-C/ISO-C part is implemented by the stdc.library and the stdcio.library shared libraries. The former implements the part that only depends on exec.library; the latter the parts that depends on other libraries like dos.library and contains mostly I/O related functions. Currently both libraries are disk based but the plan is in the future put stdc.library in ROM and be initialized right after exec so that all modules, also those in ROM can use it. stdcio.library will likely stay disk based. Purpose of these libraries is to provide a base implementation that can be used by compilers. Compilers are free to override functions with their own implementation. The reference used for the developing the two libraries is the ISO/IEC standard document ISO/IEC 9899:1999 also known as C99. Not all functions are implemented but for each function defined in the standard a place in the library is reserved. The order of the functions in the library lookup table is based on the order that they are defined in the standard document. Not all functions are implemented. Not implemented functions either are not available in the library at all or just a stub function is provided. The latter can be used to get programs running without having a proper implementation of a function. Of course target should be to have in the end all functions implemented. Consult the include files and the autodocs to see which functions are not (fully) implemented. The include files provided for the C99 code implement a proper separation of the include files. The includes should only define the prototypes as defined by the standard. This means includes like proto/stdc.h or proto/stdcio.h should not be included in the standard C99 include files. Developers improving or extending these libraries should keep this in mind. In order to use the stdc.library programs need to properly initialize the library using the __stdc_progam_startup() and __stdc_program_end() functions. It is assumed that this is taken care of by the startup code provided by the compiler.
See also
posixc.library/--background_posixc--
--background_locale--
Notes
Currently no real locale support is provided by stdc.library. All locale related functions have a minimal implementation assuming only a "C" locale. Implementing proper locale support will need careful development to have a consistent integration with locale.library. People with ideas can always post on the AROS development mailing list.
See also
locale.h --background_wchar-- --background_c99--
--background_string--
Notes
Contrary to the other include files; almost all string functions are made part of stdc.library include the POSIX and the SAS/C ones. These string functions are most of the small and don't depend on other code. Doing it this way avoids having code that only uses non C99 string functions having a dependency on posixc.library.
See also
--background_locale-- --background_c99--
--background_wchar--
Notes
wchar.h/wctype.h is not implemented by stdc.library. It is left to the compiler to provide their implementation of wchar support. No system functions should thus at the moment use wchar as implementation is compiler dependent.
See also
--background_locale-- --background_c99--
__assert()
Synopsis
void __assert( const char * expr, const char * file, unsigned int line)
Function
This is a function that is used for implementation of the C99 assert() function.
Inputs
expr - The expression to evaluate. The type of the expression does
not matter, only if its zero/NULL or not.
file - Name of the source file.
line - Line number of assert() call.
Result
The function doesn't return.
Notes
Different versions of this function are available. This function is used when a program is using stdc.library but not stdcio.library or posixc.library. Because no normal DOS file I/O is available an attempt will be made to display the assertion in a requester and thus deviating from the C99 standard that says it to go to the error stream.
See also
__assert()
Synopsis
void __assert( const char * expr, const char * file, unsigned int line)
Function
This is a function that is used for implementation of the C99 assert() function.
Inputs
expr - The expression to evaluate. The type of the expression does
not matter, only if its zero/NULL or not.
file - Name of the source file.
line - Line number of assert() call.
Result
The function doesn't return.
Notes
Different versions of this function are available. This function is used when a program is using stdcio.library and not posixc.library.
See also
__cxa_atexit()
Synopsis
int __cxa_atexit( void (*func)(void *, int), void *arg, void *d)
Function
Registers a cleanup function to be called when the program terminates via exit() or when a shared object (DSO) is unloaded. This function is primarily used by C++ compilers to handle destruction of static and global objects associated with shared libraries.
Inputs
func - Pointer to the function to be called on exit or unload.
The function must accept a void pointer and an int as arguments.
arg - Argument to be passed to the function when it is called.
d - The DSO handle with which the function is associated.
Result
Returns 0 on success, or -1 if there is insufficient memory to register the function.
Example
void my_cleanup(void *arg, int status) {
// Perform cleanup
}
__cxa_atexit(my_cleanup, my_data, my_dso_handle);
Notes
The function is called with (arg, status) arguments, where status is usually zero. The `d` parameter is used to manage which functions to call when a specific shared object is unloaded.
Bugs
This function is not intended for use in user code; it is called automatically by the C++ runtime.
See also
__cxa_finalize()
Synopsis
void __cxa_finalize( void *d)
Function
Call all functions registered via __cxa_atexit() that match the specified DSO handle. If the handle is NULL, all registered functions are called in reverse order of registration. This is typically called automatically when a shared object is unloaded or during normal process termination to run global destructors.
Inputs
d - Dynamic shared object (DSO) handle, or NULL to finalize all.
Result
None.
Notes
This function is part of the C++ runtime support and is not meant to be called by user code. It is invoked by the runtime to clean up static or global objects.
Bugs
AROS doesnt support Dynamic shared objects, so the DSO handle will always be NULL.
See also
__fpclassifyd()
Synopsis
int __fpclassifyd( double d)
Function
Classify d as zero, subnormal, normal, infinite or NaN.
Inputs
d - Value to classify.
Result
Return one of the following constants from <math.h>: FP_ZERO - Zero. FP_SUBNORMAL - A finite, nonzero subnormal value. FP_NORMAL - A finite, nonzero value that is not subnormal. FP_INFINITE - Infinity. FP_NAN - Not a number. The sign does not affect the result.
Notes
Use fpclassify() for type-generic classification.
__fpclassifyf()
Synopsis
int __fpclassifyf( float f)
Function
Classify f as zero, subnormal, normal, infinite or NaN.
Inputs
f - Value to classify.
Result
Return one of the following constants from <math.h>: FP_ZERO - Zero. FP_SUBNORMAL - A finite, nonzero subnormal value. FP_NORMAL - A finite, nonzero value that is not subnormal. FP_INFINITE - Infinity. FP_NAN - Not a number. The sign does not affect the result.
Notes
Use fpclassify() for type-generic classification.
__fpclassifyl()
Synopsis
int __fpclassifyl( long double e)
Function
Classify e as zero, subnormal, normal, infinite or NaN.
Inputs
e - Value to classify.
Result
Return one of the following constants from <math.h>: FP_ZERO - Zero. FP_SUBNORMAL - A finite, nonzero subnormal value. FP_NORMAL - A finite, nonzero value that is not subnormal. FP_INFINITE - Infinity. FP_NAN - Not a number. The sign does not affect the result.
Notes
Use fpclassify() for type-generic classification.
Bugs
On ARM and PowerPC builds with an 11-bit long-double exponent, infinity and NaN incorrectly return FP_NORMAL.
__isfinite()
Synopsis
int __isfinite( double d)
Function
Determine whether d is finite.
Inputs
d - Value to classify.
Result
Return 1 for zero, subnormal and normal values; return 0 for infinity and NaN. The sign does not affect the result.
Notes
Include <math.h>. Use isfinite() for type-generic classification.
See also
__isfinitef()
Synopsis
int __isfinitef( float f)
Function
Determine whether f is finite.
Inputs
f - Value to classify.
Result
Return 1 for zero, subnormal and normal values; return 0 for infinity and NaN. The sign does not affect the result.
Notes
Include <math.h>. Use isfinite() for type-generic classification.
See also
__isfinitel()
Synopsis
int __isfinitel( long double e)
Function
Determine whether e is finite.
Inputs
e - Value to classify.
Result
Return 1 for zero, subnormal and normal values; return 0 for infinity and NaN. The sign does not affect the result.
Notes
Include <math.h>. Use isfinite() for type-generic classification.
Bugs
On ARM and PowerPC builds with an 11-bit long-double exponent, infinity and NaN incorrectly return 1.
See also
__isinf()
Synopsis
int __isinf( double d)
Function
Determine whether d is infinite.
Inputs
d - Value to examine.
Result
Return 1 for positive or negative infinity; return 0 for finite values and NaN.
Notes
Include <math.h>. Use isinf() for type-generic calls.
See also
__isinff()
Synopsis
int __isinff( float f)
Function
Determine whether f is infinite.
Inputs
f - Value to examine.
Result
Return 1 for positive or negative infinity; return 0 for finite values and NaN.
Notes
Include <math.h>. Use isinf() for type-generic calls.
See also
__isinfl()
Synopsis
int __isinfl( long double e)
Function
Determine whether e is infinite.
Inputs
e - Value to examine.
Result
Return 1 for positive or negative infinity; return 0 for finite values and NaN.
Notes
Include <math.h>. Use isinf() for type-generic calls.
Bugs
On ARM and PowerPC builds with an 11-bit long-double exponent, this function always returns 0.
See also
__isnan()
Synopsis
int __isnan( double d)
Function
Determine whether d is NaN.
Inputs
d - Value to examine.
Result
Return 1 for NaN; return 0 for finite values and infinity. The sign does not affect the result.
Notes
Include <math.h>. Use isnan() for type-generic calls.
See also
__isnanf()
Synopsis
int __isnanf( float f)
Function
Determine whether f is NaN.
Inputs
f - Value to examine.
Result
Return 1 for NaN; return 0 for finite values and infinity. The sign does not affect the result.
Notes
Include <math.h>. Use isnan() for type-generic calls.
See also
__isnanl()
Synopsis
int __isnanl( long double e)
Function
Determine whether e is NaN.
Inputs
e - Value to examine.
Result
Return 1 for NaN; return 0 for finite values and infinity. The sign does not affect the result.
Notes
Include <math.h>. Use isnan() for type-generic calls.
Bugs
On ARM and PowerPC builds with an 11-bit long-double exponent, this function always returns 0.
See also
__isnormal()
Synopsis
int __isnormal( double d)
Function
Determine whether d is a normal floating-point value.
Inputs
d - Value to classify.
Result
Return 1 for a finite, nonzero value that is not subnormal; return 0 for zero, subnormal values, infinity and NaN. The sign does not affect the result.
Notes
Include <math.h>. Use isnormal() for type-generic classification.
See also
__isnormalf()
Synopsis
int __isnormalf( float f)
Function
Determine whether f is a normal floating-point value.
Inputs
f - Value to classify.
Result
Return 1 for a finite, nonzero value that is not subnormal; return 0 for zero, subnormal values, infinity and NaN. The sign does not affect the result.
Notes
Include <math.h>. Use isnormal() for type-generic classification.
See also
__isnormall()
Synopsis
int __isnormall( long double e)
Function
Determine whether e is a normal floating-point value.
Inputs
e - Value to classify.
Result
Return 1 for a finite, nonzero value that is not subnormal; return 0 for zero, subnormal values, infinity and NaN. The sign does not affect the result.
Notes
Include <math.h>. Use isnormal() for type-generic classification.
Bugs
On ARM and PowerPC builds with an 11-bit long-double exponent, infinity and NaN incorrectly return 1.
See also
__signbit()
Synopsis
int __signbit( double d)
Function
Test the sign bit of d.
Inputs
d - Value to examine.
Result
Return 1 if the sign bit is set; otherwise return 0. This distinguishes negative zero from positive zero and also applies to infinities and NaNs.
Notes
Include <math.h>. Use signbit() for type-generic calls.
See also
__signbitf()
Synopsis
int __signbitf( float f)
Function
Test the sign bit of f.
Inputs
f - Value to examine.
Result
Return 1 if the sign bit is set; otherwise return 0. This distinguishes negative zero from positive zero and also applies to infinities and NaNs.
Notes
Include <math.h>. Use signbit() for type-generic calls.
See also
__signbitl()
Synopsis
int __signbitl( long double e)
Function
Test the sign bit of e.
Inputs
e - Value to examine.
Result
Return 1 if the sign bit is set; otherwise return 0. This distinguishes negative zero from positive zero and also applies to infinities and NaNs.
Notes
Include <math.h>. Use signbit() for type-generic calls.
See also
__stdc_get_errorptr()
Synopsis
int *__stdc_get_errorptr( void)
Function
This function gets the pointer to store error return value for program exit.
Inputs
-
Result
pointer to return value
__stdc_gmtoffset()
Synopsis
int __stdc_gmtoffset( void)
Result
The offset to GMT in minutes
Notes
Will return 0 when locale.library is not loaded into memory yet.
__stdc_jmp2exit()
Synopsis
void __stdc_jmp2exit( int normal, int retcode)
Function
This function directly jumps to the exit of a program.
Inputs
normal - Indicates if exit is normal or not. When it is abnormal no
atexit functions will be called.
retcode - the return code for the program.
Result
-
Notes
In normal operation this function does not return. If this function returns it means that this function was called in a context where jmp_buf for exit was not initialized. Likely cause is a module that opened stdc.library. Be sure to capture this situation.
__stdc_program_end()
Synopsis
void __stdc_program_end( void)
Function
This function is to be called when main() has returned or after program has exited. This allows to stdc.library to do some cleanup that can't be done during closing of the library.
Inputs
-
Result
-
Notes
This function is normally called by the startup code so one should not need to do it oneself. TODO: Maybe this function should be implemented using Tags so that functionality can be extended in the future without breaking backwards compatibility.
__stdc_program_startup()
Synopsis
void __stdc_program_startup( jmp_buf exitjmp, int *errorptr)
Function
This is called during program startup and before calling main. This is to allow stdc.library to do some initialization that couldn't be done when opening the library.
Inputs
exitjmp - jmp_buf to jump to to exit the program errorptr - pointer to store return value of program
Result
-
Notes
This function is normally called by the startup code so one should not need to do it oneself. TODO: Maybe this function should be implemented using Tags so that functionality can be extended in the future without breaking backwards compatibility.
__stdc_set_errorptr()
Synopsis
int *__stdc_set_errorptr( int *errorptr)
Function
This function sets the pointer to store error return value for program exit.
Inputs
errorptr - new pointer to return value
Result
old pointer to return value
__stdc_set_exitjmp()
Synopsis
void __stdc_set_exitjmp( jmp_buf exitjmp, jmp_buf previousjmp)
Function
This function set the jmp_buf to use for directly exiting current program.
Inputs
exitjmp - new jmp_buf for exiting
Result
previous jmp_buf for exiting
__stdcio_get_environptr()
Synopsis
char ***__stdcio_get_environptr( void)
Function
This function the get pointer to the child environ global variable currently used by posixc.library.
Inputs
-
Result
environptr - ptr to the child environ variable (== &environ).
NULL is return if envirion emulation is disabled.
See also
__stdcio_get_envlistptr()
Synopsis
char ***__stdcio_get_envlistptr( void)
Inputs
-
Notes
Private - do not use!
See also
__stdcio_set_environptr()
Synopsis
int __stdcio_set_environptr( char ***environptr)
Function
This function is called to enable environ emulation mode.
Inputs
environptr - ptr to the child environ variable (== &environ).
Result
0 on fail, other value on success
Notes
This function will enable environ emulation. This means that all current DOS local variables are converted to the 'var=value' format and be accessible through char **environ.
Bugs
At the moment only a static list is supported. getenv() and setenv() don't use this yet so changes done with these functions are not reflected in environ. This is still TODO.
See also
__stdcio_set_envlistptr()
Synopsis
int __stdcio_set_envlistptr( char ***envlistptr)
Notes
Private - do not use!
See also
__vcformat()
Synopsis
int __vcformat( void * data, int (* outc)(int, void *), const char * format, va_list args)
Function
Format a list of arguments and call a function for each char to print.
Inputs
data - This is passed to the user callback outc as its second argument.
outc - Call this function for every character that should be
emitted. The function should return EOF on error and
> 0 otherwise.
format - A printf() format string.
args - A list of arguments for the format string.
Result
The number of characters written.
__vwformat()
Synopsis
int __vwformat( void * data, wint_t (* outwc)(wchar_t, void *), const wchar_t * format, va_list args)
Function
Formats a list of arguments according to the provided wide-character format string and emits each resulting wide character through a callback function.
Inputs
data - A user-supplied pointer passed as the second argument to
the outwc() callback function.
outwc - A callback function invoked for each wide character to output.
The callback receives the character and the data pointer.
It should return EOF on error or a positive value on success.
format - A wide-character printf() format string containing
formatting directives.
args - A va_list containing the arguments for the format string.
Result
The number of wide characters successfully written, or a negative value on error.
Notes
This is a generic backend used to implement wide-character printf functions. It handles parsing of printf-style format specifiers and passes formatted output one character at a time to the caller's output function.
Bugs
Some format specifiers may not yet be implemented or fully support wide-character variations.
__vwscanf()
Synopsis
int __vwscanf( void * data, wint_t (* get_wchar)(void *), int (* unget_wchar)(wint_t, void *), const wchar_t * format, va_list args)
Function
Core wide-character scanf parser. Reads formatted wide-character input from the data source using the provided get/unget character functions, parsing according to the given format string, and stores the results into the locations described by the argument list.
Inputs
data - Opaque pointer passed to get_wchar and unget_wchar get_wchar - Function to read the next character from the input unget_wchar - Function to push back a character into the input format - How to convert the input into the arguments args - List of argument pointers to receive results
Result
The number of converted arguments.
See also
_Exit()
Synopsis
void _Exit( int code)
Function
Terminates the running program immediately. The code is returned to the program which has called the running program. In contrast to exit(), this function does not call user exit-handlers added with atexit() or on_exit(). It does, however, close open filehandles.
Inputs
code - Exit code. 0 for success, other values for failure.
Result
None. This function does not return.
Notes
This function must not be used in a shared library or in a threaded application.
See also
abort()
Synopsis
void abort( void)
Function
Causes abnormal program termination. If there is a signal handler for SIGABORT, then the handler will be called. If the handler returns, then the program is aborted anyway.
Inputs
None.
Result
None. This function does not return.
Example
if (fatal_error)
abort ();
Notes
This function must not be used in a shared library or in a threaded application.
Bugs
Signal handling is not implemented yet.
abs()
Synopsis
int abs( int j)
Function
Compute the absolute value of j.
Inputs
j - A signed integer
Result
The absolute value of j.
Example
// returns 1 abs (1); // returns 1 abs (-1);
acos()
Synopsis
double acos( double x)
Function
Computes the principal value of the arc cosine of x.
Inputs
x - a double value in the domain [-1.0, 1.0]
Result
The arc cosine of x, in radians, in the range [0, p].
Example
double y = acos(0.0); // y = p/2 1.57079632679 double z = acos(1.0); // z = 0.0
Notes
acos(x) returns NaN if x is outside the domain [-1,1].
Bugs
None known beyond domain restrictions.
acosf()
Synopsis
float acosf( float x)
Function
Computes the principal value of the arc cosine of x.
Inputs
x - a float value in the domain [-1.0f, 1.0f]
Result
The arc cosine of x, in radians, in the range [0, p].
Example
float y = acosf(0.5f); // y 1.0471975512f (p/3) float z = acosf(-1.0f); // z = p
Notes
acosf(x) returns NaN if x is outside [-1,1].
Bugs
Precision loss near domain boundaries possible.
acosh()
Synopsis
double acosh( double x)
Function
Computes the inverse hyperbolic cosine of x.
Inputs
x - a double value where x >= 1.0
Result
The inverse hyperbolic cosine of x.
Example
double y = acosh(1.0); // y = 0.0 double z = acosh(2.0); // z 1.3169578969
Notes
acosh(x) is defined only for x = 1. Returns NaN and sets errno to EDOM if x < 1. For large x, acosh(x) ln(2x).
Bugs
None known beyond domain restrictions.
acoshf()
Synopsis
float acoshf( float x)
Function
Computes the inverse hyperbolic cosine of x.
Inputs
x - a float value where x >= 1.0f
Result
The inverse hyperbolic cosine of x.
Example
float y = acoshf(1.0f); // y = 0.0f float z = acoshf(3.0f); // z 1.7627471740f
Notes
Defined only for x = 1. Returns NaN and sets errno if input is outside domain. Uses approximations for numerical stability.
Bugs
Minor precision loss near x=1.
acoshl()
Synopsis
long double acoshl( long double x)
Function
Computes the inverse hyperbolic cosine of `x`.
Inputs
x - the value whose inverse hyperbolic cosine is to be calculated.
Must be greater than or equal to 1.
Result
Returns the inverse hyperbolic cosine of `x`. If `x` < 1, returns NaN and sets errno to EDOM.
Example
double r = acosh(2.0); // returns ~1.317
Notes
The result is always non-negative.
Bugs
None known.
acosl()
Synopsis
long double acosl( long double x)
Function
Computes the arc cosine (inverse cosine) of the input value `x`.
Inputs
x - the value whose arc cosine is to be calculated. Must be in the
range [-1, 1].
Result
Returns the arc cosine of `x`, in radians, in the range [0, p]. If `x` is outside the valid domain, returns NaN and sets errno to EDOM.
Example
double angle = acos(0.5); // returns ~1.047 (60 degrees in radians)
Notes
For values outside [-1, 1], the result is a domain error. For x == ±1, the result is 0 or p respectively.
Bugs
None known.
aligned_alloc()
Synopsis
void *aligned_alloc( size_t alignment, size_t size)
Function
Allocate aligned memory.
Inputs
alignment - Alignment of allocated memory. The address of the
allocated memory will be a multiple of this value, which
must be a power of two and a multiple of sizeof(void *).
size - How much memory to allocate.
Result
Returns zero on success. Returns EINVAL if the alignment parameter was not a power of two, or was not a multiple of sizeof(void *). Returns ENOMEM if there was insufficient memory to fulfill the request.
Notes
Memory allocated by aligned_alloc() should be freed with free(). If not, it will be freed when the program terminates. If an error occurs, errno will not be set.
arc4random()
Synopsis
uint32_t arc4random( void)
Function
Return a single 32-bit cryptographically-strong random value. The value is obtained from entropy.resource (a ChaCha20 CSPRNG seeded from software and, where available, CPU hardware entropy). If the resource is not present a self-contained fallback is used so that the function always returns a value.
Inputs
None.
Result
A uniformly-distributed random value in the range [0, 2^32).
Example
uint32_t token = arc4random();
Notes
Unlike rand()/random(), this generator is not seeded by the caller and has no reproducible sequence; it is suitable for keys, nonces, tokens and similar security-sensitive uses.
See also
arc4random_buf()
Synopsis
void arc4random_buf( void *buf, size_t nbytes)
Function
Fill a buffer with cryptographically-strong random bytes. The bytes are obtained from entropy.resource (a ChaCha20 CSPRNG seeded from software and, where available, CPU hardware entropy). If the resource is not present a self-contained fallback is used so that the buffer is always filled.
Inputs
buf - the buffer to fill. nbytes - the number of bytes to write.
Result
None.
Example
unsigned char key[32]; arc4random_buf(key, sizeof(key));
Notes
A NULL buf or a zero nbytes is a harmless no-op.
See also
arc4random_uniform()
Synopsis
uint32_t arc4random_uniform( uint32_t upper_bound)
Function
Return a cryptographically-strong random value, uniformly distributed and free of modulo bias, in the range [0, upper_bound).
Inputs
upper_bound - the exclusive upper bound.
Result
A uniformly-distributed random value in [0, upper_bound). If upper_bound is 0 or 1 the result is 0.
Example
// an unbiased dice roll in 1..6 int roll = 1 + arc4random_uniform(6);
Notes
Rejection sampling is used to avoid the bias a plain arc4random() % upper_bound would introduce when upper_bound does not evenly divide 2^32.
See also
asctime()
Synopsis
char * asctime( const struct tm * tm)
Function
The asctime() function converts the broken-down time value tm into a string. See asctime_r() for details.
Inputs
tm - The broken down time
Result
A statically allocated buffer with the converted time. Note that the contents of the buffer might get lost with the call of any of the date and time functions.
Example
time_t tt; struct tm * tm; char * str; // Get time time (&tt); // Break time up tm = localtime (&tt); // Convert to string str = asctime (tm);
Notes
The returned string is buffered per stdc.library base.
See also
asin()
Synopsis
double asin( double x)
Function
Computes the principal value of the arc sine of x.
Inputs
x - a double value in the domain [-1.0, 1.0]
Result
The arc sine of x, in radians, in the range [-p/2, p/2].
Example
double y = asin(0.0); // y = 0.0 double z = asin(1.0); // z = p/2 1.57079632679
Notes
Returns NaN if |x| > 1 and sets errno to EDOM. Accurate for inputs close to domain boundaries.
Bugs
None known beyond domain checks.
asinf()
Synopsis
float asinf( float x)
Function
Computes the principal value of the arc sine of x.
Inputs
x - a float value in the domain [-1.0f, 1.0f]
Result
The arc sine of x, in radians, in the range [-p/2, p/2].
Example
float y = asinf(0.5f); // y 0.5235987756f (p/6) float z = asinf(-1.0f); // z = -p/2
Notes
Returns NaN if input is outside [-1,1], with errno set. Precision may degrade near domain limits.
Bugs
Minor precision issues near domain edges.
asinh()
Synopsis
double asinh( double x)
Function
Computes the inverse hyperbolic sine of x.
Inputs
x - a double value (any real number)
Result
The inverse hyperbolic sine of x.
Example
double y = asinh(0.0); // y = 0.0 double z = asinh(1.0); // z 0.8813735870
Notes
asinh is defined for all real numbers. For large |x|, asinh(x) ln(2x), ensuring precision. Returns NaN if input is NaN.
Bugs
None known.
asinhf()
Synopsis
float asinhf( float x)
Function
Computes inverse hyperbolic sine (float version).
Inputs
x - real float.
Result
asinhf(x)
Example
float v = asinhf(1.0f); // 0.881373f
Notes
Accurate for small and large x.
Bugs
None known.
asinl()
Synopsis
long double asinl( long double x)
Function
Computes the arc sine (inverse sine) of the input value `x`.
Inputs
x - the value whose arc sine is to be calculated. Must be in the
range [-1, 1].
Result
Returns the arc sine of `x`, in radians, in the range [-p/2, p/2]. If `x` is outside the valid domain, returns NaN and sets errno to EDOM.
Example
double angle = asin(0.5); // returns ~0.524 (30 degrees in radians)
Notes
For values outside [-1, 1], the result is a domain error.
Bugs
None known.
asprintf()
Synopsis
int asprintf( char **restrict str, const char *restrict format, ...)
Function
Analog of sprintf, except that sotrage is allocated for a string large enough to hold the output including the terminating null byte
Inputs
str - Where to store the pointer for the allocated string. format - A printf() format string. ... - Arguments for the format string
Result
The number of characters written, or EOF on error.
See also
assert()
Synopsis
void assert( expr)
Function
Evaluates the expression expr and if it's FALSE or NULL, then printf a message and aborts the program. The message will contain the expression, the name of the file with the assert in it and the line in the file.
Inputs
expr - The expression to evaluate. The type of the expression does
not matter, only if it's zero/NULL or not.
Result
The function doesn't return.
Example
// Make sure that x equals 1 assert (x==1);
Notes
Normally the output is sent to stderr and thus this code should only be called from processes with the context of the process available. In low level modules it is advised to use the ASSERT() macro for aros/debug.h. As a last resort one can use the normal assert() macro but link with the kernelassert static link library to get a version that also outputs to kernel debug output. With this assert also an Alert will be generated in place of abort of the program.
at_quick_exit()
Synopsis
int at_quick_exit( void (*func)(void))
Function
Register a function to be called, without arguments, by quick_exit(). Registered functions are called in the reverse order of registration.
Inputs
func - the function to register.
Result
0 on success, non-zero on failure.
Notes
Handlers registered with at_quick_exit() are independent of those registered with atexit(); only quick_exit() calls them.
See also
atan()
Synopsis
double atan( double x)
Function
Computes the principal value of the arc tangent of x.
Inputs
x - a double value (any real number)
Result
The arc tangent of x, in radians, in the range [-p/2, p/2].
Example
double y = atan(0.0); // y = 0.0 double z = atan(1.0); // z = p/4 0.78539816339
Notes
atan(x) is defined for all real numbers. Returns NaN if input is NaN.
Bugs
None known.
atan2()
Synopsis
double atan2( double y, double x)
Function
Computes the arc tangent of y/x using the signs of both arguments to determine the correct quadrant of the return value.
Inputs
y - numerator (double) x - denominator (double)
Result
The angle ? between the positive x-axis and the point (x,y), in radians, in the range [-p, p].
Example
double angle = atan2(1.0, 1.0); // p/4 (0.78539816339) double angle2 = atan2(-1.0, -1.0); // -3p/4 (-2.35619449019)
Notes
Handles cases where x is zero to avoid division by zero. Returns NaN if either argument is NaN. Returns ±p/2 if x = 0 and y ? 0.
Bugs
None known.
atan2f()
Synopsis
float atan2f( float y, float x)
Function
Computes the arc tangent of y/x with correct quadrant determination.
Inputs
y - numerator (float) x - denominator (float)
Result
The angle ? between the positive x-axis and the point (x,y), in radians, in the range [-p, p].
Example
float angle = atan2f(0.0f, -1.0f); // p float angle2 = atan2f(1.0f, 0.0f); // p/2
Notes
Correctly handles special cases (x = 0, y = 0). Returns NaN if either argument is NaN.
Bugs
None known.
atan2l()
Synopsis
long double atan2l( long double y, long double x)
Function
Computes the arc tangent of y/x considering the signs of both arguments to determine the correct quadrant of the result.
Inputs
y - the vertical component. x - the horizontal component.
Result
Returns angle in radians in the range [-p, p]. Returns NaN and sets errno to EDOM if x and y are both 0.
Example
long double angle = atan2l(1.0L, -1.0L); // returns ~2.356L
Notes
This is the long double precision variant of atan2().
Bugs
None known.
atanf()
Synopsis
float atanf( float x)
Function
Computes the principal value of the arc tangent of x.
Inputs
x - a float value (any real number)
Result
The arc tangent of x, in radians, in the range [-p/2, p/2].
Example
float y = atanf(0.0f); // y = 0.0f float z = atanf(-1.0f); // z = -p/4 -0.78539816339f
Notes
Defined for all real floats. Returns NaN if input is NaN.
Bugs
None known.
atanh()
Synopsis
double atanh( double x)
Function
Computes the inverse hyperbolic tangent of x.
Inputs
x - a double value.
Result
The inverse hyperbolic tangent of x.
Example
double y = atanh(0.5); // y 0.5493061443
Notes
Domain is (-1, 1); outside this range returns NaN. Returns ±Inf if x is ±1. Returns NaN if input is NaN. The function satisfies atanh(x) = 0.5 * ln((1+x)/(1-x)).
Bugs
May lose precision near domain boundaries.
atanhf()
Synopsis
float atanhf( float x)
Function
Computes the inverse hyperbolic tangent of x (float version).
Inputs
x - value in range (-1, 1).
Result
atanhf(x)
Example
float v = atanhf(0.5f); // 0.5493f
Notes
Returns NaN for |x| = 1. Very large values close to 1 may result in loss of precision.
Bugs
None known.
atanhl()
Synopsis
long double atanhl( long double x)
Function
Computes the inverse hyperbolic tangent of `x`.
Inputs
x - the value whose inverse hyperbolic tangent is to be calculated.
Must be in the range (-1, 1).
Result
Returns the inverse hyperbolic tangent of `x`. Returns NaN and sets errno to EDOM if |x| > 1. Returns ±infinity and sets errno to ERANGE if |x| == 1.
Example
double r = atanh(0.5); // returns ~0.549
Notes
The function is odd: atanh(-x) = -atanh(x).
Bugs
None known.
atanl()
Synopsis
long double atanl( long double x)
Function
Computes the arc tangent of x in radians.
Inputs
x - a long double value.
Result
Returns value in range [-p/2, p/2].
Example
long double r = atanl(1.0L); // returns ~0.785L
Notes
Long double precision version of atan().
Bugs
None known.
atexit()
Synopsis
int atexit( void (*func)(void))
Function
Registers the given function to be called at normal process termination.
Inputs
func - function to be called.
See also
atof()
Synopsis
double atof( const char * str)
Function
Convert a string of digits into a double.
Inputs
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'.
Result
The value of string str.
atoi()
Synopsis
int atoi( const char * str)
Function
Convert a string of digits into an integer.
Inputs
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'.
Result
The value of string str.
Example
// returns 1
atoi (" \t +1");
// returns 1
atoi ("1");
// returns -1
atoi (" \n -1");
atol()
Synopsis
long atol( const char * str)
Function
Convert a string of digits into an long integer.
Inputs
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'.
Result
The value of string str.
Example
// returns 1
atol (" \t +1");
// returns 1
atol ("1");
// returns -1
atol (" \n -1");
atoll()
Synopsis
long long atoll( const char * str)
Function
Convert a string of digits into an long long integer.
Inputs
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'.
Result
The value of string str.
Example
// returns 1
atoll (" \t +1");
// returns 1
atoll ("1");
// returns -1
atoll (" \n -1");
bsearch()
Synopsis
void * bsearch( const void * key, const void * base, size_t count, size_t size, int (* comparefunction)(const void *, const void *))
Function
Search in a sorted array for an entry key.
Inputs
key - Look for this key.
base - This is the address of the first element in the array
to be searched. Note that the array *must* be sorted.
count - The number of elements in the array
size - The size of one element
comparefunction - The function which is called when two elements
must be compared. The function gets the addresses of two
elements of the array and must return 0 is both are equal,
< 0 if the first element is less than the second and > 0
otherwise.
Result
A pointer to the element which equals key in the array or NULL if no such element could be found.
btowc()
Synopsis
t_t btowc( int c) FUNCTION The btowc() function converts a single byte character (in the range of unsigned char) to its corresponding wide character representation, according to the current multibyte encoding in the current locale. If the input is EOF or does not correspond to a valid single-byte multibyte character, WEOF is returned.
Inputs
c - A single byte character as an int (must be representable as
unsigned char or EOF).
Result
Returns the corresponding wide character (wint_t) if the conversion succeeds. Returns WEOF if the input is EOF or an invalid multibyte sequence.
Example
wint_t wc = btowc((int)'A');
Notes
This function only works for single-byte multibyte characters. It is intended to be used with byte input where the encoding may vary depending on the locale. It uses mbrtowc() internally with a zero-initialized conversion state.
Bugs
If called with a multibyte encoding that requires more than one byte per character (e.g., UTF-8 for non-ASCII), this function will fail for non-ASCII characters.
See also
c16rtomb()
Synopsis
size_t c16rtomb( char * restrict s, char16_t c16, mbstate_t * restrict ps)
Function
Converts a 16-bit (UTF-16) code unit to its multibyte representation. A high surrogate is buffered until the following low surrogate is supplied, at which point the combined code point is emitted.
Inputs
s - Where to store the multibyte sequence (may be NULL). c16 - The UTF-16 code unit to convert. ps - Conversion state (a static internal state is used if NULL).
Result
The number of bytes stored (0 when a high surrogate is buffered and no output is produced yet), or (size_t)-1 on an encoding error (errno = EILSEQ).
Notes
Only UTF-8 output is supported.
See also
c32rtomb()
Synopsis
size_t c32rtomb( char * restrict s, char32_t c32, mbstate_t * restrict ps)
Function
Converts a single 32-bit (UTF-32) character to its multibyte representation.
Inputs
s - Where to store the multibyte sequence (may be NULL). c32 - The character to convert. ps - Conversion state (a static internal state is used if NULL).
Result
The number of bytes stored, or (size_t)-1 on an encoding error (errno = EILSEQ).
Notes
char32_t holds a complete Unicode code point, so on AROS - where wchar_t is 32 bits wide - this is equivalent to wcrtomb().
See also
cabs()
Synopsis
double complex cabs( double complex z)
Function
Computes the magnitude (absolute value) of a complex number.
Inputs
z - complex number.
Result
The magnitude sqrt(real(z)^2 + imag(z)^2).
Example
double complex z = 3.0 + 4.0*I; double r = cabs(z); // r = 5.0
Notes
Avoids overflow/underflow by scaling.
Bugs
None known.
cabsf()
Synopsis
float cabsf( float complex z)
Function
Computes magnitude of complex float.
Inputs
z - complex number.
Result
sqrt(Re(z)^2 + Im(z)^2)
Example
float complex z = 3.0f + 4.0f*I; float v = cabsf(z); // 5.0
Notes
Uses scaling to avoid overflow/underflow.
Bugs
None known.
See also
cabsl()
Synopsis
long double cabsl( long double x)
Function
Computes absolute value (modulus) of complex long double number.
Inputs
x - complex number (real and imaginary parts)
Result
Returns magnitude sqrt(real² + imag²).
Example
long double r = cabsl(3.0 + 4.0iL); // 5.0L
Notes
Scales input to prevent overflow/underflow.
Bugs
None known.
calloc()
Synopsis
void * calloc( size_t count, size_t size)
Function
Allocate size bytes of memory, clears the memory (sets all bytes to 0) and returns the address of the first byte.
Inputs
count - How many time size size - How much memory to allocate.
Result
A pointer to the allocated memory or NULL. If you don't need the memory anymore, you can pass this pointer to free(). If you don't, the memory will be freed for you when the application exits.
carg()
Synopsis
double carg( double complex z)
Function
Return the principal argument of z, in radians, with a branch cut along the negative real axis. The angle is calculated by atan2(cimag(z), creal(z)).
Inputs
z - Complex input value.
Result
An angle in the interval [-pi, pi]. The signs of zero select the side of the branch cut. With a negative real component, imaginary +0 gives +pi and imaginary -0 gives -pi. An imaginary zero with positive real part is preserved. Infinite components select the corresponding axis or quadrant angle; a NaN component produces NaN.
Notes
Include <complex.h>.
cargf()
Synopsis
float cargf( float complex z)
Function
Return the principal argument of z, in radians, with a branch cut along the negative real axis. The angle is calculated by atan2f(cimagf(z), crealf(z)).
Inputs
z - Complex input value.
Result
An angle in the interval [-pi, pi]. The signs of zero select the side of the branch cut. With a negative real component, imaginary +0 gives +pi and imaginary -0 gives -pi. An imaginary zero with positive real part is preserved. Infinite components select the corresponding axis or quadrant angle; a NaN component produces NaN.
Notes
Include <complex.h>.
cargl()
Synopsis
long double cargl( long double complex z)
Function
Return the principal argument of z, in radians, with a branch cut along the negative real axis. The angle is calculated by atan2l(cimagl(z), creall(z)).
Inputs
z - Complex input value.
Result
An angle in the interval [-pi, pi]. The signs of zero select the side of the branch cut. With a negative real component, imaginary +0 gives +pi and imaginary -0 gives -pi. An imaginary zero with positive real part is preserved. Infinite components select the corresponding axis or quadrant angle; a NaN component produces NaN. Signed-zero pairs differ on targets using the separate long double implementation; see BUGS.
Notes
Include <complex.h>.
Bugs
On targets with a separate long double implementation, atan2l() treats both signed-zero components as a domain error, sets errno to EDOM and returns NaN if execution continues. It requests FE_INVALID, but the exception may not be raised by every AROS target. Where cargl() aliases carg(), the double behavior applies.
cbrt()
Synopsis
double cbrt( double x)
Function
Computes the cube root of x.
Inputs
x - a double value (any real number)
Result
The cube root of x.
Example
double y = cbrt(27.0); // y = 3.0 double z = cbrt(-8.0); // z = -2.0
Notes
Defined for all real numbers including negative values. cbrt(-8.0) returns -2.0. Returns NaN if input is NaN.
Bugs
None known.
cbrtf()
Synopsis
float cbrtf( float x)
Function
Computes the cube root of x.
Inputs
x - a float value (any real number)
Result
The cube root of x.
Example
float y = cbrtf(8.0f); // y = 2.0f float z = cbrtf(-27.0f); // z = -3.0f
Notes
Works for negative and positive values. Returns NaN if input is NaN.
Bugs
None known.
cbrtl()
Synopsis
long double cbrtl( long double x)
Function
Computes the cube root of a long double value.
Inputs
x - input value.
Result
Returns the cube root of x.
Example
long double r = cbrtl(-8.0L); // returns -2.0L
Notes
Works with negative values as well.
Bugs
None known.
ccosh()
Synopsis
double complex ccosh( double complex z)
Function
Return the complex hyperbolic cosine of z.
Inputs
z - Double complex value x + i*y, with y in radians.
Result
An approximation to cosh(x) * cos(y) + i*sinh(x) * sin(y) in double complex. For finite x and signed-zero y, returns cosh(x) with imaginary zero x*y. For infinite x and signed-zero y, returns positive infinity with a zero whose sign is the product of the signs of x and y. NaN x with signed-zero y returns NaN with the same zero-sign rule. For zero x and infinite or NaN y, returns NaN with an imaginary zero whose sign is the product of the input signs. For finite nonzero x and infinite or NaN y, both components are NaN. For infinite x and finite nonzero y, evaluates infinity*cos(y) + i*x*sin(y). For infinite x and infinite or NaN y, returns positive infinity + i*NaN. For NaN x and nonzero y, both components are NaN.
Notes
Include <complex.h>. Each component can overflow or underflow independently. Use round-to-nearest mode for trigonometric argument reduction. Floating-point exceptions can occur; enabled traps may prevent return. Overflow in the real cosh(x) call for zero y sets errno to ERANGE and requests FE_OVERFLOW. Other paths can overflow without setting errno.
Bugs
Large finite real parts can reach undefined signed-shift arithmetic in exp(). Results on those paths are not portable.
See also
ccoshf()
Synopsis
float complex ccoshf( float complex z)
Function
Return the complex hyperbolic cosine of z.
Inputs
z - Float complex value x + i*y, with y in radians.
Result
An approximation to cosh(x) * cos(y) + i*sinh(x) * sin(y) in float complex. For finite x and signed-zero y, returns cosh(x) with imaginary zero x*y. For infinite x and signed-zero y, returns positive infinity with a zero whose sign is the product of the signs of x and y. NaN x with signed-zero y returns NaN with the same zero-sign rule. For zero x and infinite or NaN y, returns NaN with an imaginary zero whose sign is the product of the input signs. For finite nonzero x and infinite or NaN y, both components are NaN. For infinite x and finite nonzero y, evaluates infinity*cos(y) + i*x*sin(y). For infinite x and infinite or NaN y, returns positive infinity + i*NaN. For NaN x and nonzero y, both components are NaN.
Notes
Include <complex.h>. Each component can overflow or underflow independently. Use round-to-nearest mode for trigonometric argument reduction. Floating-point exceptions can occur; enabled traps may prevent return. The function does not assign errno.
Bugs
Large finite real parts can reach undefined signed-shift arithmetic in expf(). Results on those paths are not portable.
See also
ceil()
Synopsis
double ceil( double x)
Function
Returns the smallest integer value greater than or equal to x.
Inputs
x - input floating point number.
Result
The ceiling of x as a double.
Example
double val = ceil(2.3); // val == 3.0
Notes
If x is already integral, returns x unchanged. Domain: all real numbers.
Bugs
None known.
ceilf()
Synopsis
float ceilf( float x)
Function
Returns smallest integer not less than x.
Inputs
x - input float
Result
Ceiling of x.
Example
float r = ceilf(2.3f); // 3.0f float r2 = ceilf(-2.3f); // -2.0f
Notes
Rounds up fractional values.
Bugs
None known.
ceill()
Synopsis
long double ceill( long double x)
Function
Returns the smallest integer value greater than or equal to x as long double.
Inputs
x - input long double number.
Result
The ceiling of x as a long double.
Example
long double val = ceill(2.3L); // val == 3.0L
Notes
If x is integral, returns x. Domain: all real numbers.
Bugs
None known.
cexp()
Synopsis
double complex cexp( double complex z)
Function
Compute the complex exponential of z.
Inputs
z - Complex exponent.
Result
Return the complex exponential. For finite z = x + i*y, the real and imaginary components are exp(x)*cos(y) and exp(x)*sin(y). When the imaginary component is zero, the result retains its sign in the imaginary component.
Notes
Include <complex.h>. Components can overflow or underflow; infinite or NaN inputs have corresponding exceptional results.
cexpf()
Synopsis
float complex cexpf( float complex z)
Function
Compute the float complex exponential of z.
Inputs
z - Complex exponent.
Result
Return the complex exponential. For finite z = x + i*y, the real and imaginary components are expf(x)*cosf(y) and expf(x)*sinf(y). When the imaginary component is zero, the result retains its sign in the imaginary component.
Notes
Include <complex.h>. Components can overflow or underflow; infinite or NaN inputs have corresponding exceptional results.
cimag()
Synopsis
double cimag( double complex z)
Function
Return the imaginary component of z.
Inputs
z - Complex input value.
Result
The imaginary component of z, including its sign. Signed zero, infinity and NaN retain their respective classifications.
Notes
Include <complex.h>.
cimagf()
Synopsis
float cimagf( float complex z)
Function
Return the imaginary component of z.
Inputs
z - Complex input value.
Result
The imaginary component of z, including its sign. Signed zero, infinity and NaN retain their respective classifications.
Notes
Include <complex.h>.
cimagl()
Synopsis
long double cimagl( long double complex z)
Function
Return the imaginary component of z.
Inputs
z - Complex input value.
Result
The imaginary component of z, including its sign. Signed zero, infinity and NaN retain their respective classifications.
Notes
Include <complex.h>. When LDBL_MANT_DIG equals DBL_MANT_DIG, cimagl() aliases cimag().
clearerr()
Synopsis
void clearerr( FILE * stream)
Function
Clear EOF and error flag in a stream. You must call this for example after you have read the file until EOF, then appended something to it and want to continue reading.
Inputs
stream - The stream to be reset.
Result
None.
See also
clock()
Synopsis
clock_t clock( void)
Function
clock() returns an approximation of the time passed since the program was started
Result
The time passed in CLOCKS_PER_SEC units. To get the number of seconds divide by CLOCKS_PER_SEC.
Notes
Reference point is set when stdc.library is opened. If you use the function from another shared library the reference point is thus when this library opened stdc.library
See also
conj()
Synopsis
double complex conj( double complex z)
Function
Return the complex conjugate of z.
Inputs
z - Complex input value.
Result
A complex value with the real component unchanged and the sign of the imaginary component reversed, including signed zero and infinity. NaN components remain NaNs.
Notes
Include <complex.h>.
conjf()
Synopsis
float complex conjf( float complex z)
Function
Return the complex conjugate of z.
Inputs
z - Complex input value.
Result
A complex value with the real component unchanged and the sign of the imaginary component reversed, including signed zero and infinity. NaN components remain NaNs.
Notes
Include <complex.h>.
conjl()
Synopsis
long double complex conjl( long double complex z)
Function
Return the complex conjugate of z.
Inputs
z - Complex input value.
Result
A complex value with the real component unchanged and the sign of the imaginary component reversed, including signed zero and infinity. NaN components remain NaNs.
Notes
Include <complex.h>. When LDBL_MANT_DIG is 53, conjl() aliases conj().
copysignl()
Synopsis
long double copysignl( long double x, long double y)
Function
Return the magnitude of x with the sign bit of y.
Inputs
x - Value supplying the magnitude. y - Value supplying the sign bit.
Result
The magnitude of x with the sign of y, including the sign of zero, infinity or NaN. No numerical comparison with y is made.
Notes
Include <math.h>. A NaN input retains its NaN classification; NaN payload behavior depends on the target representation. On equal-precision long double targets, copysignl() aliases copysign().
See also
cos()
Synopsis
double cos( double x)
Function
Computes the cosine of x (x in radians).
Inputs
x - a double value representing an angle in radians.
Result
The cosine of the angle x.
Example
double y = cos(0.0); // y = 1.0 double z = cos(M_PI / 2.0); // z 0.0
Notes
The function is periodic with period 2p. Returns NaN if input is NaN. Uses argument reduction to improve precision for large inputs.
Bugs
Slight loss of precision for very large inputs.
cosf()
Synopsis
float cosf( float x)
Function
Computes the cosine of x (x in radians).
Inputs
x - a float value representing an angle in radians.
Result
The cosine of the angle x.
Example
float y = cosf(0.0f); // y = 1.0f float z = cosf(3.14159f / 2); // z 0.0f
Notes
Periodic with period 2p. Returns NaN if input is NaN. May lose precision for large magnitude inputs.
Bugs
Precision degradation on large inputs.
cosh()
Synopsis
double cosh( double x)
Function
Computes the hyperbolic cosine of x.
Inputs
x - a double value.
Result
The hyperbolic cosine of x, defined as (e^x + e^(-x)) / 2.
Example
double y = cosh(0.0); // y = 1.0 double z = cosh(1.0); // z 1.5430806348
Notes
cosh(x) = 1 for all real x. Returns NaN if input is NaN. May overflow for large |x|, resulting in +Inf.
Bugs
Overflow for large inputs.
coshf()
Synopsis
float coshf( float x)
Function
Computes the hyperbolic cosine of x.
Inputs
x - a float value.
Result
The hyperbolic cosine of x, (e^x + e^(-x)) / 2.
Example
float y = coshf(0.0f); // y = 1.0f float z = coshf(1.0f); // z 1.543081f
Notes
Returns values = 1. Returns NaN if input is NaN. May overflow to +Inf for large |x|.
Bugs
Overflow for large magnitude inputs.
coshl()
Synopsis
long double coshl( long double x)
Function
Computes the hyperbolic cosine of x.
Inputs
x - input angle in radians.
Result
Returns the hyperbolic cosine of x.
Example
long double r = coshl(0.0L); // returns 1.0L
Notes
Returns positive values = 1.
Bugs
None known.
cosl()
Synopsis
long double cosl( long double x)
Function
Computes the cosine of x (x in radians).
Inputs
x - angle in radians.
Result
Returns the cosine of x.
Example
double c = cos(0.0); // returns 1.0
Notes
Result is in the range [-1, 1].
Bugs
None known.
cproj()
Synopsis
double complex cproj( double complex z)
Function
Project z onto the Riemann sphere.
Inputs
z - Complex input value.
Result
If either component is infinite, positive real infinity with an imaginary zero carrying the sign of the original imaginary component. Otherwise z is returned unchanged, including a NaN component when neither part is infinite.
Notes
Include <complex.h>.
cprojf()
Synopsis
float complex cprojf( float complex z)
Function
Project z onto the Riemann sphere.
Inputs
z - Complex input value.
Result
If either component is infinite, positive real infinity with an imaginary zero carrying the sign of the original imaginary component. Otherwise z is returned unchanged, including a NaN component when neither part is infinite.
Notes
Include <complex.h>.
cprojl()
Synopsis
long double complex cprojl( long double complex z)
Function
Project z onto the Riemann sphere.
Inputs
z - Complex input value.
Result
If either component is infinite, positive real infinity with an imaginary zero carrying the sign of the original imaginary component. Otherwise z is returned unchanged, including a NaN component when neither part is infinite.
Notes
Include <complex.h>. When LDBL_MANT_DIG is 53, cprojl() aliases cproj().
creal()
Synopsis
double creal( double complex z)
Function
Return the real component of z.
Inputs
z - Complex input value.
Result
The real component of z, including its sign. Signed zero, infinity and NaN retain their respective classifications.
Notes
Include <complex.h>. When LDBL_MANT_DIG is 53, creal() aliases creal().
crealf()
Synopsis
float crealf( float complex z)
Function
Return the real component of z.
Inputs
z - Complex input value.
Result
The real component of z, including its sign. Signed zero, infinity and NaN retain their respective classifications.
Notes
Include <complex.h>.
creall()
Synopsis
long double creall( long double complex z)
Function
Return the real component of z.
Inputs
z - Complex input value.
Result
The real component of z, including its sign. Signed zero, infinity and NaN retain their respective classifications.
Notes
Include <complex.h>. When LDBL_MANT_DIG is 53, creall() aliases creal().
csinf()
Synopsis
float complex csinf( float complex z)
Function
Return the complex sine of z.
Inputs
z - Float complex value x + i*y, with x in radians.
Result
An approximation to sin(x) * cosh(y) + i*cos(x) * sinh(y) in float complex. For signed-zero x and infinite or NaN y, retains x as the real component. The imaginary component is infinity with the sign of y, or NaN, respectively. For infinite or NaN x and signed-zero y, returns NaN with that same imaginary zero. For infinite or NaN x and finite nonzero y, both components are NaN. For finite nonzero x and infinite y, evaluates infinity*sin(x) + i*y*cos(x). For infinite or NaN x and infinite y, returns NaN + i*y. For nonzero x and NaN y, both components are NaN.
Notes
Include <complex.h>. Each component can overflow or underflow independently. Use round-to-nearest mode for trigonometric argument reduction. Floating-point exceptions can occur; enabled traps may prevent return. The function does not assign errno.
Bugs
Large finite imaginary parts can reach undefined signed-shift arithmetic in expf(). Results on those paths are not portable.
See also
csinh()
Synopsis
double complex csinh( double complex z)
Function
Return the complex hyperbolic sine of z.
Inputs
z - Double complex value x + i*y, with y in radians.
Result
An approximation to sinh(x) * cos(y) + i*cosh(x) * sin(y) in double complex. For signed-zero y, returns sinh(x) with that same imaginary zero; infinite or NaN x is retained in the real component. For zero x and infinite or NaN y, returns x + i*NaN. For finite nonzero x and infinite or NaN y, both components are NaN. For infinite x and finite nonzero y, evaluates x*cos(y) + i*infinity*sin(y). For infinite x and infinite or NaN y, returns x + i*NaN. For NaN x and nonzero y, both components are NaN.
Notes
Include <complex.h>. Each component can overflow or underflow independently. Use round-to-nearest mode for trigonometric argument reduction. Floating-point exceptions can occur; enabled traps may prevent return. Do not use errno alone to detect component overflow.
Bugs
Large finite real parts can reach undefined signed-shift arithmetic in exp(). Results on those paths are not portable.
See also
csinhf()
Synopsis
float complex csinhf( float complex z)
Function
Return the complex hyperbolic sine of z.
Inputs
z - Float complex value x + i*y, with y in radians.
Result
An approximation to sinh(x) * cos(y) + i*cosh(x) * sin(y) in float complex. For signed-zero y, returns sinh(x) with that same imaginary zero; infinite or NaN x is retained in the real component. For zero x and infinite or NaN y, returns x + i*NaN. For finite nonzero x and infinite or NaN y, both components are NaN. For infinite x and finite nonzero y, evaluates x*cos(y) + i*infinity*sin(y). For infinite x and infinite or NaN y, returns x + i*NaN. For NaN x and nonzero y, both components are NaN.
Notes
Include <complex.h>. Each component can overflow or underflow independently. Use round-to-nearest mode for trigonometric argument reduction. Floating-point exceptions can occur; enabled traps may prevent return. The function does not assign errno.
Bugs
Large finite real parts can reach undefined signed-shift arithmetic in expf(). Results on those paths are not portable.
csqrtl()
Synopsis
long double complex csqrtl( long double complex z)
Function
Return the principal square root of a complex number.
Inputs
z - Complex argument with long double components.
Result
An approximation to the square root of z, with a nonnegative real part. For finite inputs, the imaginary part has the sign of the input imaginary part, subject to the limitations below. At complex zero, the real part is positive zero and the imaginary part retains its sign. On the negative real axis, the sign of the imaginary zero selects the side of the branch cut. An infinite imaginary part returns positive infinity plus the original imaginary infinity, even when the real part is NaN. For a finite imaginary part, positive real infinity returns positive infinity and a signed imaginary zero; negative real infinity returns positive real zero and a signed imaginary infinity. Other NaN inputs return two NaNs, except that a positive infinite real part remains positive infinity, and a negative infinite real part produces an imaginary infinity with the sign of the input imaginary NaN.
Notes
Include <complex.h>. Extended-precision targets use sqrtl() and hypotl(). Where long double has the same precision as double, csqrtl() aliases csqrt(). Floating-point exceptions may occur, and enabled traps may prevent return. The extended-precision path relies on the floating-point environment support used by sqrtl(). On m68k, that dependency can clear or change errno.
Bugs
Very small finite components can underflow internally before the square root is taken. A purely imaginary argument whose magnitude is the smallest positive subnormal can produce an infinite imaginary result in round-to-nearest mode. The m68k and AArch64 floating-point environment stubs do not provide the rounding and exception control required by sqrtl(). Correct rounding and environment preservation are not assured on those paths.
See also
ctanhf()
Synopsis
float complex ctanhf( float complex z)
Function
Return the complex hyperbolic tangent of z.
Inputs
z - Float complex value x + i*y, with y in radians.
Result
An approximation to sinh(z) / cosh(z) in float complex. For infinite x, the real part is 1 with the sign of x and the imaginary part is zero. For finite y, that zero has the sign of sin(y) * cos(y); for infinite y, it has the sign of y. Its sign is unspecified when y is NaN. For NaN x and a signed-zero y, returns NaN with that same imaginary zero. For NaN x and nonzero y, both components are NaN. For finite x and infinite or NaN y, both components are NaN.
Notes
Include <complex.h>. The mathematical function has poles at x = 0 and y = (k + 1/2) * pi for integer k. Rounded arguments near these poles can produce large results. Use round-to-nearest mode for argument reduction. Floating-point arithmetic can raise exceptions; enabled traps may prevent return. The function does not assign errno.
Bugs
Large finite real parts can reach undefined signed-shift arithmetic in expf(). Results on those paths are not portable.
See also
ctime()
Synopsis
char * ctime( const time_t * tt)
Function
The ctime() function converts the broken-down time value tt into a string. See ctime_r() for details.
Inputs
tt - Convert this time.
Result
A statically allocated buffer with the converted time. Note that the contents of the buffer might get lost with the call of any of the date and time functions.
Example
time_t tt; char * str; // Get time time (&tt); // Convert to string str = ctime (&tt);
Notes
This function must not be used in a shared library or in a threaded application. Use ctime_r() instead.
See also
difftime()
Synopsis
double difftime( time_t time2, time_t time1)
Function
difftime() returns the number of seconds elapsed between time time2 and time time1.
Inputs
time2 - time value from which time1 is subtracted time1 - time value that is subtracted from time2
Result
The number of seconds elapsed in double precision.
Example
time_t tt1, tt2; double secs; time (&tt1); ... time (&tt2); secs = difftime(tt2, tt1);
See also
div()
Synopsis
div_t div( int numer, int denom)
Function
Compute quotient en remainder of two int variables
Inputs
numer = the numerator denom = the denominator
Result
a struct with two ints quot and rem with
quot = numer / denom and rem = numer % denom.
typedef struct div_t {
int quot;
int rem;
} div_t;
NOTES
See also
erf()
Synopsis
double erf( double x)
Function
Computes the error function of x.
Inputs
x - input value.
Result
Returns the probability integral of the Gaussian distribution from 0 to x.
Example
double val = erf(1.0);
Notes
Used in probability, statistics, and partial differential equations.
Bugs
None known.
erfc()
Synopsis
double erfc( double x)
Function
Computes the complementary error function of x.
Inputs
x - a double value.
Result
The complementary error function, defined as 1 - erf(x).
Example
double y = erfc(0.0); // y = 1.0 double z = erfc(1.0); // z 0.157299
Notes
erfc(x) approaches 0 as x ? 8 and 2 as x ? -8. Returns NaN if input is NaN. Useful for calculating tail probabilities in statistics.
Bugs
Accuracy can degrade for very large negative inputs.
erfcf()
Synopsis
float erfcf( float x)
Function
Computes the complementary error function of x.
Inputs
x - a float value.
Result
The complementary error function of x.
Example
float y = erfcf(0.0f); // y = 1.0f float z = erfcf(1.0f); // z 0.157299f
Notes
Defined as 1 - erf(x). Returns NaN if input is NaN.
Bugs
Reduced accuracy for large negative inputs.
erfcl()
Synopsis
long double erfcl( long double x)
Function
Computes the complementary error function of x.
Inputs
x - a long double value.
Result
Returns 1 - erf(x).
Example
long double r = erfcl(0.0L); // returns 1.0L
Notes
Useful for calculating tail probabilities.
Bugs
None known.
erfclf()
Synopsis
float erfclf( float x)
Function
Computes the complementary error function (long double variant).
Inputs
x - input value.
Result
The complementary error function value.
Example
float val = erfclf(0.0f); // val == 1.0f
Notes
Similar to erfcf(), but for long double precision.
Bugs
None known.
erff()
Synopsis
float erff( float x)
Function
Computes the error function erf(x).
Inputs
x - input float
Result
Value of erf(x).
Example
float r = erff(1.0f); // 0.8427008f
Notes
Common in statistics and PDEs.
Bugs
None known.
erfl()
Synopsis
long double erfl( long double x)
Function
Computes the error function of x.
Inputs
x - a long double value.
Result
Returns erf(x).
Example
long double r = erfl(0.0L); // returns 0.0L
Notes
Related to Gaussian integrals.
Bugs
None known.
exit()
Synopsis
void exit( int code)
Function
Terminates the running program. The code is returned to the program which has called the running program.
Inputs
code - Exit code. 0 for success, other values for failure.
Result
None. This function does not return.
Notes
This function must not be used in a shared library or in a threaded application.
- EXAMPLE
- if (no_problems)
- exit (0);
- if (warning)
- exit (5);
- if (error)
- exit (10);
- if (fatal)
- exit (20);
exp()
Synopsis
double exp( double x)
Function
Computes the exponential function of x, e raised to the power x.
Inputs
x - a double value.
Result
The value of e^x.
Example
double y = exp(0.0); // y = 1.0 double z = exp(1.0); // z 2.718281828
Notes
Returns +Inf if x is large and positive (overflow). Returns 0 if x is large and negative (underflow). Returns NaN if input is NaN.
Bugs
Precision may degrade for very large magnitude inputs.
exp10()
Synopsis
double exp10( double x)
Function
Computes 10 raised to the power of x (10^x).
Inputs
x - the exponent to raise 10 to.
Result
The value of 10 raised to the power x.
Example
double val = exp10(2.0); // val == 100.0
Notes
Internally implemented as exp(x * M_LN10). Domain: all real numbers.
Bugs
Accuracy depends on the precision of the underlying exp() implementation.
exp10f()
Synopsis
float exp10f( float x)
Function
Computes 10^x using exp(x * ln(10)).
Inputs
x - exponent.
Result
10^x
Example
float v = exp10f(2.0f); // 100.0
Notes
Domain: all real numbers.
Bugs
None known.
expf()
Synopsis
float expf( float x)
Function
Computes the exponential function of x, e raised to the power x.
Inputs
x - a float value.
Result
The value of e^x.
Example
float y = expf(0.0f); // y = 1.0f float z = expf(1.0f); // z 2.7182817f
Notes
Returns +Inf on overflow, 0 on underflow. Returns NaN if input is NaN.
Bugs
Precision loss for very large magnitude inputs.
expl()
Synopsis
long double expl( long double x)
Function
Computes e raised to the power x.
Inputs
x - exponent.
Result
Returns e^x. Sets errno to ERANGE and raises FE_OVERFLOW on overflow.
Example
double val = exp(1.0); // returns e (~2.71828)
Notes
Uses IEEE 754 semantics.
Bugs
None known.
expm1()
Synopsis
double expm1( double x)
Function
Computes e^x - 1 with higher precision than using exp(x) - 1 directly, especially for small values of x.
Inputs
x - a double value.
Result
The value of e^x - 1.
Example
double y = expm1(0.0); // y = 0.0 double z = expm1(1e-10); // z 1e-10
Notes
Provides better accuracy for small x where exp(x) is close to 1. Returns NaN if input is NaN. Returns -1 if x is large negative (underflow).
Bugs
None known.
expm1f()
Synopsis
float expm1f( float x)
Function
Computes e^x - 1 with improved precision for small x.
Inputs
x - a float value.
Result
The value of e^x - 1.
Example
float y = expm1f(0.0f); // y = 0.0f float z = expm1f(1e-7f); // z 1e-7f
Notes
Especially accurate for values of x near zero. Returns NaN if input is NaN.
Bugs
None known.
fabs()
Synopsis
double fabs( double x)
Function
Computes the absolute value of a double.
Inputs
x - a double value.
Result
Absolute value of x.
Example
double a = fabs(-5.0); // 5.0 double b = fabs(3.2); // 3.2
Notes
Handles special cases like negative zero and NaN.
Bugs
None known.
fabsf()
Synopsis
float fabsf( float x)
Function
Returns absolute value of x.
Inputs
x - value.
Result
Absolute value.
Example
float v = fabsf(-3.14f); // 3.14
Notes
Clears sign bit.
Bugs
None known.
See also
fabsl()
Synopsis
long double fabsl( long double x)
Function
Returns absolute value of x.
Inputs
x - input long double
Result
Absolute value (non-negative) of x.
Example
long double r = fabsl(-3.5L); // 3.5L
Notes
Works for all real numbers.
Bugs
None known.
fclose()
Synopsis
int fclose( FILE * stream)
Function
Closes a stream.
Inputs
stream - Stream to close.
Result
Upon successful completion 0 is returned. Otherwise, EOF is returned and the global variable errno is set to indicate the error. In either case no further access to the stream is possible.
See also
fdim()
Synopsis
double fdim( double x, double y)
Function
Return the positive difference between x and y.
Inputs
x - First double operand. y - Second double operand.
Result
Return x - y when x is greater than y; otherwise return +0. If x is NaN, return x; otherwise if y is NaN, return y. The subtraction may overflow to infinity or round to a finite result according to the floating-point environment.
Notes
Include <math.h>. This is not an absolute difference. Unlike fmax(x - y, 0), the subtraction is evaluated only when x > y. Subtraction may raise floating-point exceptions, but this implementation does not set errno on overflow. NaN payload and signaling behavior are not guaranteed.
fdimf()
Synopsis
float fdimf( float x, float y)
Function
Return the positive difference between x and y.
Inputs
x - First float operand. y - Second float operand.
Result
Return x - y when x is greater than y; otherwise return +0. If x is NaN, return x; otherwise if y is NaN, return y. The subtraction may overflow to infinity or round to a finite result according to the floating-point environment.
Notes
Include <math.h>. This is not an absolute difference. Unlike fmax(x - y, 0), the subtraction is evaluated only when x > y. Subtraction may raise floating-point exceptions, but this implementation does not set errno on overflow. NaN payload and signaling behavior are not guaranteed.
fdiml()
Synopsis
long double fdiml( long double x, long double y)
Function
Return the positive difference between x and y.
Inputs
x - First long double operand. y - Second long double operand.
Result
Return x - y when x is greater than y; otherwise return +0. If x is NaN, return x; otherwise if y is NaN, return y. The subtraction may overflow to infinity or round to a finite result according to the floating-point environment.
Notes
Include <math.h>. This is not an absolute difference. Unlike fmax(x - y, 0), the subtraction is evaluated only when x > y. Subtraction may raise floating-point exceptions, but this implementation does not set errno on overflow. NaN payload and signaling behavior are not guaranteed.
feclearexcept()
Synopsis
int feclearexcept( int excepts)
Function
Clear the selected floating-point exception flags.
Inputs
excepts - Zero, a supported FE_* exception constant, or a
bitwise OR of those constants. Use FE_ALL_EXCEPT
to select every supported exception.
Result
Zero on success; -1 in the generic fallback. See BUGS for implementations that report success without clearing flags.
Notes
Include <fenv.h>. Clearing flags does not disable exception traps. On x86, clears selected flags in x87 and, when available, SSE. On PowerPC, selecting FE_INVALID also clears its associated invalid-operation cause flags.
Bugs
On AArch64, ARM soft-float and RISC-V soft-float, the function returns zero without accessing exception flags. On m68k, only a software environment is accessed; hardware floating-point exceptions are not tracked. The generic fallback is unimplemented and returns -1.
See also
fegetenv()
Synopsis
int fegetenv( fenv_t *envp)
Function
Save the current floating-point environment.
Inputs
envp - Non-NULL pointer to writable storage for a fenv_t.
Result
Zero on completion; -1 in the generic fallback. A supported implementation writes the environment to *envp. See BUGS before relying on the output after a zero return.
Notes
Include <fenv.h>. Keep the saved representation unchanged for a later fesetenv() or feupdateenv() call on the same architecture and ABI. It is not a portable file format. On x86, saves x87 state and available SSE control/status state. The x87 control word is restored after the save, so its exception-mask settings are preserved.
Bugs
On AArch64, ARM soft-float and RISC-V soft-float, returns zero without writing *envp. The object retains its previous contents. On m68k, saves only the software environment, not hardware floating-point state. The generic fallback returns -1 without writing *envp.
See also
fegetexceptflag()
Synopsis
int fegetexceptflag( fexcept_t *flagp, int excepts)
Function
Save the selected floating-point exception flags without clearing them.
Inputs
flagp - Non-NULL pointer to writable storage for a fexcept_t.
excepts - Zero, a supported FE_* exception constant, or their
bitwise OR. FE_ALL_EXCEPT selects all supported flags.
Result
Zero on success; -1 in the generic fallback. The saved representation is written to *flagp. See BUGS for stub behavior.
Notes
Include <fenv.h>. Pass the saved value to fesetexceptflag() with a mask containing only flags included in this call. The representation is architecture-dependent. On x86, combines x87 and available SSE flags. The saved value does not preserve which unit reported each flag.
Bugs
On AArch64, ARM soft-float and RISC-V soft-float, writes zero to *flagp and returns zero without reading exception state. On m68k, only a software environment is accessed; hardware floating-point exceptions are not tracked. The generic fallback returns -1 without accessing *flagp.
See also
feholdexcept()
Synopsis
int feholdexcept( fenv_t *envp)
Function
Save the floating-point environment, clear exception flags, and disable exception traps where supported.
Inputs
envp - Non-NULL pointer to writable storage for a fenv_t.
Result
Zero on completion; -1 on RISC-V hardware-float and in the generic fallback. See BUGS before relying on a zero return.
Notes
Include <fenv.h>. On x86 and ARM VFP, preserves the rounding mode while clearing exception flags and disabling traps. Use fesetenv() to restore the saved environment, or feupdateenv() to retain exceptions raised in the meantime.
Bugs
On PowerPC, the saved value does not preserve the environment representation. Do not use it to restore the previous state. On m68k, copies only the software environment to *envp and sets errno to zero. It neither clears exception flags nor disables hardware traps. On AArch64, ARM soft-float and RISC-V soft-float, writes zero to *envp without saving or changing floating-point state. On RISC-V hardware-float and in the generic fallback, returns -1 without writing *envp or changing the environment.
See also
feof()
Synopsis
int feof( FILE * stream)
Function
Test the EOF-Flag of a stream. This flag is set automatically by any function which recognises EOF. To clear it, call clearerr().
Inputs
stream - The stream to be tested.
Result
!= 0, if the stream is at the end of the file, 0 otherwise.
See also
feraiseexcept()
Synopsis
int feraiseexcept( int excepts)
Function
Request the selected floating-point exceptions.
Inputs
excepts - Zero, a supported FE_* exception constant, or their
bitwise OR. FE_ALL_EXCEPT selects all supported
exceptions.
Result
Zero on completion in the architecture-specific implementations; -1 in the generic fallback. See BUGS: zero does not establish that an exception was raised.
Notes
Include <fenv.h>. Enabled floating-point traps may prevent normal completion. Do not rely on a particular delivery order when requesting several exceptions. On x86, sets the selected x87 and available SSE flags, then waits for pending x87 exceptions. Unselected flags are retained.
Bugs
On AArch64, ARM soft-float and RISC-V soft-float, returns zero without changing exception state. On m68k, does not set exception flags. A selection containing FE_OVERFLOW or FE_UNDERFLOW sets errno to ERANGE; any other nonzero selection sets errno to EDOM. Zero leaves errno unchanged. The function returns zero in each case. ARM VFP and RISC-V hardware-float paths only set exception status flags. The generic fallback is unimplemented and returns -1.
ferror()
Synopsis
int ferror( FILE * stream)
Function
Test the error flag of a stream. This flag is set automatically by any function that detects an error. To clear it, call clearerr().
Inputs
stream - The stream to be tested.
Result
!= 0, if the stream had an error, 0 otherwise.
See also
fesetenv()
Synopsis
int fesetenv( const fenv_t *envp)
Function
Replace the floating-point environment with a saved or default environment.
Inputs
envp - Non-NULL pointer to an unchanged environment saved by
fegetenv() or feholdexcept() on the same architecture
and ABI, or FE_DFL_ENV where supported. See BUGS for m68k.
Result
Zero on completion; -1 in the generic fallback. See BUGS for implementations that report success without changing state.
Notes
Include <fenv.h>. Replaces the stored control settings and exception flags; it does not merge current exception flags into the saved state. Use feupdateenv() when that is required. On x86, restores x87 state and available SSE control/status state. The x87 tag word is also restored; floating-point register values themselves are not restored.
Bugs
On m68k, only the software environment is replaced. Do not pass FE_DFL_ENV or FE_NOMASK_ENV: these special pointer values are dereferenced instead of recognized and may cause an invalid memory access. On AArch64, ARM soft-float and RISC-V soft-float, returns zero without reading *envp or changing the environment. The generic fallback is unimplemented and returns -1.
See also
fesetexceptflag()
Synopsis
int fesetexceptflag( const fexcept_t *flagp, int excepts)
Function
Restore selected floating-point exception flags from a saved representation.
Inputs
flagp - Non-NULL pointer to a value saved by fegetexceptflag().
excepts - Zero, a supported FE_* exception constant, or their
bitwise OR. FE_ALL_EXCEPT selects all supported flags.
Select only flags included when the value was saved.
Result
Zero on success; -1 in the generic fallback. See BUGS for implementations that return zero without restoring flags.
Notes
Include <fenv.h>. Replaces selected flags with their saved values. Unselected flags are preserved, except as noted below. This function restores flag state rather than performing the exceptional operations used by feraiseexcept(). On x86, installs the selected saved flags in both x87 and available SSE state. It does not restore their original distribution between the two units.
Bugs
On PowerPC, selecting FE_INVALID also replaces every other flag in FE_ALL_EXCEPT. Flags outside the requested selection can therefore be cleared or changed. On AArch64, ARM soft-float and RISC-V soft-float, returns zero without reading *flagp or changing exception state. On m68k, only a software environment is accessed; hardware floating-point exceptions are not tracked. The generic fallback returns -1 without accessing *flagp.
See also
fetestexcept()
Synopsis
int fetestexcept( int excepts)
Function
Test the selected floating-point exception flags without clearing them.
Inputs
excepts - Zero, a supported FE_* exception constant, or a
bitwise OR of those constants. Use FE_ALL_EXCEPT
to select every supported exception.
Result
The bitwise OR of the selected flags that are set, or zero if none are set. The generic fallback returns -1. See BUGS before treating a zero result as evidence of clear flags.
Notes
Include <fenv.h>. On x86, reports a flag if it is set in either x87 or, when available, SSE. The result does not identify which unit raised it.
Bugs
On AArch64, ARM soft-float and RISC-V soft-float, the function returns zero without accessing exception flags. On m68k, only a software environment is accessed; hardware floating-point exceptions are not tracked. The generic fallback is unimplemented and returns -1.
See also
feupdateenv()
Synopsis
int feupdateenv( const fenv_t *envp)
Function
Restore a floating-point environment and retain the currently raised exception flags.
Inputs
envp - Non-NULL pointer to an unchanged environment saved by
a working fegetenv() or feholdexcept() implementation
on the same architecture and ABI, or FE_DFL_ENV where
supported. See BUGS for m68k.
Result
Zero if the call returns; -1 in the generic fallback. See BUGS for implementations that do not restore state or retain current flags.
Notes
Include <fenv.h>. Restores the saved control settings and combines the saved and current exception flags. Restoring enabled traps can cause an exception before the call returns. On x86, combines current x87 and available SSE exception flags and raises them through feraiseexcept() after restoring the environment. The flags lose their original unit association. See feraiseexcept() for exception-delivery limitations.
Bugs
On m68k, replaces only the software environment. Current flags are not merged into the restored flags. Instead, current overflow or underflow sets errno to ERANGE; any other nonzero software status sets it to EDOM. A zero status leaves errno unchanged. Do not pass FE_DFL_ENV or FE_NOMASK_ENV: these values are dereferenced and may cause an invalid memory access. On AArch64, ARM soft-float and RISC-V soft-float, returns zero without reading *envp or changing the environment. The generic fallback is unimplemented and returns -1.
fflush()
Synopsis
int fflush( FILE * stream)
Function
Flush a stream. If the stream is an input stream, then the stream is synchronized for unbuffered I/O. If the stream is an output stream, then any buffered data is written.
Inputs
stream - Flush this stream. May be NULL. In this case, all
output streams are flushed.
Result
0 on success or EOF on error.
fgetc()
Synopsis
int fgetc( FILE * stream)
Function
Read one character from the stream. If there is no character available or an error occurred, the function returns EOF.
Inputs
stream - Read from this stream
Result
The character read or EOF on end of file or error. If EOF is returned feof() and ferror() indicate if it was an end-of-file situation or an error.
fgetpos()
Synopsis
int fgetpos( FILE * stream, fpos_t * pos)
Function
Get the current position in a stream. This function is equivalent to ftell(). However, on some systems fpos_t may be a complex structure, so this routine may be the only way to portably get the position of a stream.
Inputs
stream - The stream to get the position from. pos - Pointer to the fpos_t position structure to fill.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
See also
fgets()
Synopsis
char * fgets( char * buffer, int size, FILE * stream)
Function
Read one line of characters from the stream into the buffer.
Reading will stop, when a newline ('\n') is encountered, EOF
or when the buffer is full. If a newline is read, then it is
put into the buffer. The last character in the buffer is always
'\0' (Therefore at most size-1 characters can be read in one go).
Inputs
buffer - Write characters into this buffer size - This is the size of the buffer in characters. stream - Read from this stream
Result
buffer or NULL in case of an error or EOF.
Example
// Read a file line by line
char line[256];
// Read until EOF
while (fgets (line, sizeof (line), fh))
{
// Evaluate the line
}
fgetwc()
Synopsis
wint_t fgetwc( FILE * stream)
Function
Read the next wide character from the specified stream. Supports UTF-8 decoding if the stream is byte-oriented. Returns a pushed-back wide character if present via ungetwc.
Inputs
stream - Pointer to the input stream.
Result
Returns the next wide character as a wint_t. Returns WEOF on end-of-file or error.
Notes
The function handles UTF-8 sequences up to 4 bytes. If a wide character has been pushed back with ungetwc, it is returned first.
fgetws()
Synopsis
wchar_t *fgetws( wchar_t *ws, int n, FILE *stream)
Function
Reads a wide-character string from the specified stream. Converts UTF-8 input bytes to wide characters and stores up to n-1 wide characters. Null-terminates the string.
Inputs
ws - Buffer to store the wide string. n - Maximum number of wide characters to read (including null terminator). stream - Input stream to read from.
Result
Returns ws on success, or NULL on error or end of file.
Notes
Handles UTF-8 decoding and stream buffering.
floor()
Synopsis
double floor( double x)
Function
Returns the largest integer value less than or equal to x.
Inputs
x - input floating point number.
Result
The floor of x as a double.
Example
double val = floor(2.7); // val == 2.0
Notes
If x is integral, returns x. Domain: all real numbers.
Bugs
None known.
floorf()
Synopsis
float floorf( float x)
Function
Returns largest integer <= x.
Inputs
x - value.
Result
Floor of x.
Example
float v = floorf(-2.3f); // -3.0
Notes
Handles negatives and special values.
Bugs
None known.
floorl()
Synopsis
long double floorl( long double x)
Function
Returns the largest integer value less than or equal to x as a long double.
Inputs
x - input long double number.
Result
The floor of x as a long double.
Example
long double val = floorl(2.7L); // val == 2.0L
Notes
If x is integral, returns x. Domain: all real numbers.
Bugs
None known.
fma()
Synopsis
double fma( double x, double y, double z)
Function
Compute x * y + z with one final rounding to double precision.
Inputs
x, y - Multiplicands. z - Addend.
Result
The fused result in the current rounding direction, subject to the implementation limits below. This can differ from evaluating x * y and then adding z as two separately rounded operations.
Notes
Include <math.h>. Zero times infinity and an infinite product added to an oppositely signed infinity produce NaN through invalid arithmetic. NaN operands propagate without a payload guarantee. Finite results can underflow or overflow; floating-point exceptions may be raised. The software path temporarily selects round-to-nearest and restores the incoming rounding mode before normal return. Exception flags are not restored to their previous values, and enabled traps may interrupt the operation. This entry point does not explicitly report errors through errno.
Bugs
The software algorithm requires double-precision intermediate rounding. On x87, it does not establish that precision itself; extended-precision evaluation can invalidate its error-free transformations. The m68k FPU library-vector replacement uses single-precision operand and result moves with separate multiply and add instructions. It does not implement this double-precision fused contract.
See also
fmaf()
Synopsis
float fmaf( float x, float y, float z)
Function
Multiply x by y and add z without rounding the product to float first.
Inputs
x - First factor. y - Second factor. z - Value to add to the product.
Result
The value of x*y + z as a float, subject to the rounding limitations below. A zero multiplied by infinity, or an infinite product added to an infinity of the opposite sign, produces NaN. NaN operands produce NaN.
Notes
Include <math.h>. The calculation uses the current rounding mode. A correction in round-to-nearest mode temporarily selects round-toward-zero, then requests round-to-nearest again before returning. The function does not assign errno. Floating-point exceptions can occur; enabled traps may prevent return.
Bugs
Correct rounding requires working floating-point environment support and compiler support for dynamic rounding. Failed rounding-mode changes are not reported. On m68k and AArch64, fegetround() returns -1, so the correction for double rounding is skipped. Some results can differ from a single correctly rounded operation.
See also
fmal()
Synopsis
long double fmal( long double x, long double y, long double z)
Function
Compute x * y + z with one final rounding to long double precision.
Inputs
x, y - Multiplicands. z - Addend.
Result
The fused long double result in the current rounding direction, subject to the implementation limits below. Special-value behavior and floating-point side effects follow the fma() contract.
Notes
Include <math.h>. On targets where long double and double have equal precision, this function aliases the double implementation. Otherwise the software algorithm uses the target long double format; it requires intermediate arithmetic at that format's precision. The routine temporarily uses round-to-nearest and restores the incoming rounding mode before normal return. It does not establish the x87 precision-control setting for long double evaluation.
Bugs
The extended-precision implementation calls double-precision ldexp() in its round-to-nearest subnormal-result path. The conversion and scaling can discard long double precision and turn a representable nonzero result into zero. Do not rely on correct fused rounding in this range. Equal-precision aliases inherit the fma() limitations.
fmax()
Synopsis
double fmax( double x, double y)
Function
Return the larger numeric operand, ignoring a lone NaN.
Inputs
x - First double operand. y - Second double operand.
Result
The larger value for numeric operands. For opposite-signed zeros, return +0. If one operand is NaN, return the other. If both are NaNs, return a NaN.
Notes
Include <math.h>. For two NaNs, this implementation evaluates x + y, which may raise FE_INVALID. The sign of zero and NaN handling differ from a simple conditional comparison. NaN payloads are not guaranteed.
fmaxf()
Synopsis
float fmaxf( float x, float y)
Function
Return the larger numeric operand, ignoring a lone NaN.
Inputs
x - First float operand. y - Second float operand.
Result
The larger value for numeric operands. For opposite-signed zeros, return +0. If one operand is NaN, return the other. If both are NaNs, return a NaN.
Notes
Include <math.h>. For two NaNs, the second argument is returned. The sign of zero and NaN handling differ from a simple conditional comparison. Signaling NaNs may affect the floating-point exception state; NaN payloads are not guaranteed.
fmaxl()
Synopsis
long double fmaxl( long double x, long double y)
Function
Return the larger numeric operand, ignoring a lone NaN.
Inputs
x - First long double operand. y - Second long double operand.
Result
The larger value for numeric operands. For opposite-signed zeros, return +0. If one operand is NaN, return the other. If both are NaNs, return a NaN.
Notes
Include <math.h>. For two NaNs, this implementation evaluates x + y, which may raise FE_INVALID. The sign of zero and NaN handling differ from a simple conditional comparison. NaN payloads are not guaranteed. Where long double has double precision, the double implementation supplies the long double symbol.
fmin()
Synopsis
double fmin( double x, double y)
Function
Return the smaller numeric operand, ignoring a lone NaN.
Inputs
x - First double operand. y - Second double operand.
Result
The smaller value for numeric operands. For opposite-signed zeros, return -0. If one operand is NaN, return the other. If both are NaNs, return a NaN.
Notes
Include <math.h>. For two NaNs, the second argument is returned. The sign of zero and NaN handling differ from a simple conditional comparison. Signaling NaNs may affect the floating-point exception state; NaN payloads are not guaranteed.
fminf()
Synopsis
float fminf( float x, float y)
Function
Return the smaller numeric operand, ignoring a lone NaN.
Inputs
x - First float operand. y - Second float operand.
Result
The smaller value for numeric operands. For opposite-signed zeros, return -0. If one operand is NaN, return the other. If both are NaNs, return a NaN.
Notes
Include <math.h>. For two NaNs, the second argument is returned. The sign of zero and NaN handling differ from a simple conditional comparison. Signaling NaNs may affect the floating-point exception state; NaN payloads are not guaranteed.
fminl()
Synopsis
long double fminl( long double x, long double y)
Function
Return the smaller numeric operand, ignoring a lone NaN.
Inputs
x - First long double operand. y - Second long double operand.
Result
The smaller value for numeric operands. For opposite-signed zeros, return -0. If one operand is NaN, return the other. If both are NaNs, return a NaN.
Notes
Include <math.h>. For two NaNs, the second argument is returned. The sign of zero and NaN handling differ from a simple conditional comparison. Signaling NaNs may affect the floating-point exception state; NaN payloads are not guaranteed. Where long double has double precision, the double implementation supplies the long double symbol.
fmod()
Synopsis
double fmod( double x, double y)
Function
Computes the floating-point remainder of x / y.
Inputs
x - numerator. y - denominator (non-zero).
Result
The remainder r = x - n*y, where n = trunc(x/y).
Example
double r = fmod(5.3, 2.0); // r = 1.3 double s = fmod(-5.3, 2.0); // s = -1.3
Notes
Behavior undefined if y == 0. Result has same sign as x.
Bugs
None known.
See also
fmodf()
Synopsis
float fmodf( float x, float y)
Function
Computes remainder of x / y.
Inputs
x - numerator. y - denominator.
Result
Floating-point remainder.
Example
float v = fmodf(5.3f, 2.0f); // 1.3
Notes
Result sign matches x. y=0 returns NaN.
Bugs
None known.
See also
fmodl()
Synopsis
long double fmodl( long double x, long double y)
Function
Computes floating-point remainder for long double precision.
Inputs
x - numerator. y - denominator (non-zero).
Result
Floating-point remainder.
Example
long double r = fmodl(5.3L, 2.0L); // r = 1.3L
Notes
Same rules as fmod().
Bugs
None known.
fopen()
Synopsis
FILE * fopen( const char * restrict pathname, const char * restrict mode)
Function
Opens a file with the specified name in the specified mode.
Inputs
pathname - Path and filename of the file you want to open.
mode - How to open the file:
r: Open for reading. The stream is positioned at the
beginning of the file.
r+: Open for reading and writing. The stream is positioned
at the beginning of the file.
w: Open for writing. If the file doesn't exist, then
it is created. If it does already exist, then
it is truncated. The stream is positioned at the
beginning of the file.
w+: Open for reading and writing. If the file doesn't
exist, then it is created. If it does already
exist, then it is truncated. The stream is
positioned at the beginning of the file.
a: Open for writing. If the file doesn't exist, then
it is created. The stream is positioned at the
end of the file.
a+: Open for reading and writing. If the file doesn't
exist, then it is created. The stream is positioned
at the end of the file.
b: Open in binary more. This has no effect and is ignored.
Result
A pointer to a FILE handle or NULL in case of an error. When NULL is returned, then errno is set to indicate the error.
Bugs
Currently errno is not set on error.
fprintf()
Synopsis
int fprintf( FILE * restrict fh, const char * restrict format, ...)
Function
Format a string with the specified arguments and write it to the stream.
Inputs
fh - Write to this stream format - How to format the arguments ... - The additional arguments
Result
The number of characters written to the stream or EOF on error.
fputc()
Synopsis
int fputc( int c, FILE * stream)
Function
Write one character to the specified stream.
Inputs
c - The character to output stream - The character is written to this stream
Result
The character written or EOF on error.
fputs()
Synopsis
int fputs( const char * str, FILE * stream)
Function
Write a string to the specified stream.
Inputs
str - Output this string... fh - ...to this stream
Result
> 0 on success and EOF on error.
fputwc()
Synopsis
wint_t fputwc( wint_t wc, FILE * stream)
Function
Write a wide character to the specified stream. Converts the wide character to UTF-8 and writes the byte sequence.
Inputs
wc - Wide character to write. stream - Pointer to the output stream.
Result
Returns the wide character written, or WEOF on error.
Notes
Handles conversion from wchar_t (Unicode code point) to UTF-8.
fputws()
Synopsis
wint_t fputws( const wchar_t *ws, FILE *stream)
Function
Write a wide-character string to the specified stream. Converts each wide character to UTF-8 and writes the sequence of bytes.
Inputs
ws - Pointer to the null-terminated wide-character string to write. stream - Pointer to the output stream.
Result
Returns a non-negative number on success, or WEOF on error.
Notes
The null terminator is not written. Uses fputwc internally for each wide character.
fread()
Synopsis
size_t fread( void * restrict buf, size_t size, size_t nblocks, FILE * restrict stream)
Function
Read an amount of bytes from a stream.
Inputs
buf - The buffer to read the bytes into size - Size of one block to read nblocks - The number of blocks to read stream - Read from this stream
Result
The number of blocks read. This may range from 0 when the stream contains no more blocks up to nblocks. In case of an error, 0 is returned.
free()
Synopsis
void free( void * memory)
Function
Return memory allocated with malloc() or a similar function to the system.
Inputs
memory - The result of the previous call to malloc(), etc. or
NULL.
Result
None.
See also
freopen()
Synopsis
FILE *freopen( const char * restrict path, const char * restrict mode, FILE * restrict stream )
Function
Opens the file whose name is the string pointed to by path and associates the stream pointed to by stream with it.
Inputs
path - the file to open, NULL to only change the mode of the stream.
mode - Mode to open file, see fopen for description of the string.
When path is NULL end-of-file and error indicator will be
cleared and indication if stream is read and/or write.
No change to position in file or no truncation will be
performed.
stream - the stream to which the file will be associated.
Result
NULL on error or stream. When NULL is returned input stream is not changed.
frexp()
Synopsis
double frexp( double x, int *exp)
Function
Breaks the floating-point number x into its normalized fraction and an integral power of two. The fraction is returned, and the power of two is stored in *exp.
Inputs
x - input floating point number. exp - pointer to integer where exponent will be stored.
Result
The normalized fraction part of x in the range [0.5, 1.0) or zero.
Example
int e; double frac = frexp(8.0, &e); // frac=0.5, e=4 (8.0 = 0.5 * 2^4)
Notes
Handles zero, infinity, NaN properly. Domain: all real numbers.
Bugs
None known.
frexpf()
Synopsis
float frexpf( float x, int *eptr)
Function
Decompose x into a normalized binary fraction and exponent. For finite nonzero x, return m and store e such that x = m * 2^e and 0.5 <= |m| < 1.
Inputs
x - Value to decompose. eptr - Writable pointer receiving the integer exponent.
Result
The signed fraction m. For zero, return the signed zero and store 0 in *eptr. For infinity or NaN, return x and store 0.
Notes
Include <math.h>. eptr must not be NULL. For example, an input of 12 yields a fraction of 0.75 and an exponent of 4.
frexpl()
Synopsis
long double frexpl( long double x, int *ex)
Function
Decompose x into a normalized binary fraction and exponent. For finite nonzero x, return m and store e such that x = m * 2^e and 0.5 <= |m| < 1.
Inputs
x - Value to decompose. ex - Writable pointer receiving the integer exponent.
Result
The signed fraction m. For zero, return the signed zero and store 0 in *ex. For infinity or NaN, return x; the separate long double implementation leaves *ex unchanged.
Notes
Include <math.h>. ex must not be NULL. On targets where frexpl() aliases frexp(), nonfinite inputs instead store 0. Do not use the exponent output for a nonfinite input.
fscanf()
Synopsis
int fscanf( FILE * restrict fh, const char * restrict format, ...)
Function
Scan a string with the specified arguments and write the results in the specified parameters.
Inputs
fh - Read from this stream format - How to convert the input into the arguments ... - Write the result in these arguments
Result
The number of converted arguments.
See also
fseek()
Synopsis
int fseek( FILE * stream, long offset, int whence)
Function
Change the current position in a stream.
Inputs
stream - Modify this stream
offset, whence - How to modify the current position. whence
can be SEEK_SET, then offset is the absolute position
in the file (0 is the first byte), SEEK_CUR then the
position will change by offset (ie. -5 means to move
5 bytes to the beginning of the file) or SEEK_END.
SEEK_END means that the offset is relative to the
end of the file (-1 is the last byte and 0 is
the EOF).
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
Notes
The seek is handled by the files system so effects of what happens when seeking after end of file may differ between file systems.
Bugs
Not fully compatible with ISO fseek, especially in 'ab' and 'a+b' modes
fsetpos()
Synopsis
int fsetpos( FILE * stream, const fpos_t * pos)
Function
Change the current position in a stream. This function is equivalent to fseek() with whence set to SEEK_SET. However, on some systems fpos_t may be a complex structure, so this routine may be the only way to portably reposition a stream.
Inputs
stream - Modify this stream pos - The new position in the stream.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
See also
ftell()
Synopsis
long int ftell( FILE * stream)
Function
Tell the current position in a stream.
Inputs
stream - Obtain position of this stream
Result
The position on success and -1 on error. If an error occurred, the global variable errno is set.
fwide()
Synopsis
int fwide( FILE *stream, int mode)
Function
Sets or queries the orientation of the given stream for wide or byte I/O. If mode > 0, sets stream orientation to wide-character. If mode < 0, sets stream orientation to byte-oriented. If mode == 0, returns current orientation without changing it.
Inputs
stream - The stream to query or set orientation. mode - Orientation mode to set or 0 to query.
Result
Returns positive value if stream is wide-oriented, negative if byte-oriented, or 0 if no orientation is set.
Notes
Orientation is locked after first I/O operation.
fwprintf()
Synopsis
int fwprintf( struct __sFILE * restrict stream, const wchar_t * restrict format, ...)
Function
Format a variable list of arguments according to a wide-character format string and write the output to the given stream.
Inputs
stream - Output stream. format - A wide-character printf() format string. ... - Additional arguments matching the format specifiers.
Result
The number of wide characters written to the stream, or a negative value if an error occurs.
Notes
This function uses wide-character output and formatting, similar to printf(), but targeting wchar_t output streams.
See also
fwrite()
Synopsis
size_t fwrite( const void * restrict buf, size_t size, size_t nblocks, FILE * restrict stream)
Function
Write an amount of bytes to a stream.
Inputs
buf - The buffer to write to the stream size - Size of one block to write nblocks - The number of blocks to write stream - Write to this stream
Result
The number of blocks written. If no error occurred, this is nblocks. Otherwise examine errno for the reason of the error.
fwscanf()
Synopsis
int fwscanf( FILE * restrict stream, const wchar_t * restrict format, ...)
Function
Reads formatted wide-character input from the given file stream and stores the results into the provided argument locations.
Inputs
stream - Read from this wide-character file stream format - How to convert the input into the arguments ... - Write the result in these arguments
Result
The number of converted arguments.
gamma()
Synopsis
double gamma( double x)
Function
Computes the gamma function G(x), which extends the factorial function to real and complex numbers.
Inputs
x - input value.
Result
The value of the gamma function at x.
Example
double val = gamma(5.0); // val == 24.0 (factorial 4!)
Notes
Domain excludes non-positive integers (poles). Returns infinity or NaN on poles. Uses Lanczos approximation or similar.
Bugs
Precision varies for large arguments. Overflow on large positive values.
gamma_r()
Synopsis
double gamma_r( double x, int *signgamp)
Function
Return the natural logarithm of the absolute value of Gamma(x), and store its sign separately.
Inputs
x - Double argument.
signgamp - Non-NULL pointer to writable int storage. The
function writes this object for every argument,
including poles and nonfinite values.
Result
An approximation to log(|Gamma(x)|) in double. For finite nonpole arguments, *signgamp is +1 or -1 according to the sign of Gamma(x), subject to BUGS. Returns zero for x equal to 1 or 2. Both signs of zero and negative integers are poles and return positive infinity. Either infinity returns positive infinity; NaN returns NaN. At negative zero, *signgamp is -1. At positive zero, negative integer poles, either infinity and NaN, it is +1. These special-case values do not indicate a valid finite Gamma value or successful evaluation.
Notes
Include <math.h>. This is the historical name for lgamma_r(). It has the same result and sign output. Use tgamma() when you need Gamma(x) itself. The result can be negative even when *signgamp is positive. The signgam variable is not used as implicit output. Passing &signgam explicitly still writes that object. Use separate output storage for independent concurrent calls. The function does not assign errno. Pole arithmetic can raise divide-by-zero; other arithmetic can raise overflow or inexact. Enabled traps may prevent return.
Bugs
Large negative noninteger arguments can produce an incorrect Gamma sign. For example, x equal to -1125899906842625.5 can report -1 although Gamma(x) is positive.
See also
gammaf_r()
Synopsis
float gammaf_r( float x, int *signgamp)
Function
Return the natural logarithm of the absolute value of Gamma(x), and store its sign separately.
Inputs
x - Float argument.
signgamp - Non-NULL pointer to writable int storage. The
function writes this object for every argument,
including poles and nonfinite values.
Result
An approximation to log(|Gamma(x)|) in float. For finite nonpole arguments, *signgamp is +1 or -1 according to the sign of Gamma(x), subject to BUGS. Returns zero for x equal to 1 or 2. Both signs of zero and negative integers are poles and return positive infinity. Either infinity returns positive infinity; NaN returns NaN. At negative zero, *signgamp is -1. At positive zero, negative integer poles, either infinity and NaN, it is +1. These special-case values do not indicate a valid finite Gamma value or successful evaluation.
Notes
Include <math.h>. This is the historical name for lgammaf_r(). It has the same result and sign output. Use tgammaf() when you need Gamma(x) itself. The result can be negative even when *signgamp is positive. The signgam variable is not used as implicit output. Passing &signgam explicitly still writes that object. Use separate output storage for independent concurrent calls. The function does not assign errno. Pole arithmetic can raise divide-by-zero; other arithmetic can raise overflow or inexact. Enabled traps may prevent return.
Bugs
Large negative noninteger arguments can produce an incorrect Gamma sign. For example, x equal to -2097153.5f can report -1 although Gamma(x) is positive.
See also
getc()
Synopsis
int getc( FILE * stream)
Function
Read one character from the stream. If there is no character available or an error occurred, the function returns EOF.
Inputs
stream - Read from this stream
Result
The character read or EOF on end of file or error.
getchar()
Synopsis
int getchar(
Function
Read one character from the standard input stream. If there is no character available or an error occurred, the function returns EOF.
Result
The character read or EOF on end of file or error.
getenv()
Synopsis
char *getenv( const char *name)
Function
Get an environment variable.
Inputs
name - Name of the environment variable.
Result
Pointer to the variable's value, or NULL on failure. When no memory is available errno will be set to ENOMEM.
Notes
The returned contents of the environment variable is cached per StdCIOBase. So the returned value is valid and does not change until a next call to getenv on the same StdCIOBase.
gets()
Synopsis
char * gets( char * buffer)
Function
Read one line of characters from the standard input stream into
the buffer. Reading will stop, when a newline ('\n') is encountered,
EOF or when the buffer is full. If a newline is read, then it is
replaced by '\0'. The last character in the buffer is always '\0'.
Inputs
buffer - Write characters into this buffer
Result
buffer when successful. NULL in case of an error or when EOF without any characters read. In the latter case buffer array is unchanged.
Bugs
Never use this function. gets() does not know how large the buffer is and will continue to store characters past the end of the buffer if it has not encountered a newline or EOF yet. Use fgets() instead.
See also
getwc()
Synopsis
wint_t getwc( FILE *stream)
Function
Read a wide character by calling fgetwc(). Return a pending character from ungetwc() first, without reading bytes. Otherwise decode one one-to-four-byte UTF-8 sequence from the stream.
Inputs
stream - Open input stream. The stream remains owned by the caller.
Result
The decoded or pushed-back value, or WEOF on end-of-file or error. NULL stream returns WEOF and sets errno to EINVAL. An invalid lead byte, invalid continuation byte or incomplete sequence sets EILSEQ. A stream not open for reading normally returns WEOF with EACCES and its error indicator set; a pending wide pushback is returned first.
Notes
Include <wchar.h>. This is a function wrapper and evaluates its argument once. It does not close the stream or allocate a returned object. Decoding is fixed to UTF-8 and does not use the current locale's encoding. Bytes consumed before a decoding error are not restored, including an invalid continuation byte. A byte I/O error encountered after a multibyte lead byte is reported as EILSEQ by the decoder. feof() and ferror() reflect the underlying byte read. A decoding error does not itself set the stream error indicator; inspect errno when WEOF is returned. Successful reads do not clear earlier indicators or errno. Returning a pushed-back character does not clear an EOF flag left by this implementation of ungetwc(). Use a valid stream in DOS process context with the C runtime active. Reading can block in the underlying file handler. No timeout or cancellation mechanism is supplied. Coordinate access to the stream; this wrapper adds no locking around a complete multibyte sequence.
Bugs
The decoder checks byte prefixes but does not reject overlong forms, surrogate code points or values above U+10FFFF. Do not use this call as a strict UTF-8 validator. Neither this wrapper nor fgetwc() sets or checks stream orientation; the byte-read path does not enforce it.
getwchar()
Synopsis
t_t getwchar( void) FUNCTION The getwchar() function is the wide-character equivalent of getchar(). It reads the next wide character from stdin and returns it as a wint_t value. If the end-of-file is reached or an error occurs, WEOF is returned.
Inputs
None.
Result
Returns the next wide character read from stdin as a wint_t. Returns WEOF if end-of-file is encountered or an error occurs.
Example
wint_t wc;
while ((wc = getwchar()) != WEOF)
putwchar(wc);
Notes
The behavior of getwchar() depends on the current locale, particularly the LC_CTYPE category, which affects the interpretation of multibyte sequences as wide characters. Internally, getwchar() is equivalent to calling fgetwc(stdin).
Bugs
If stdin is not a valid input stream or the locale is misconfigured, results may be undefined or incorrect.
See also
gmtime()
Synopsis
struct tm * gmtime( const time_t * tt)
Function
The gmtime() function converts the calendar time tt to broken-down time representation, expressed in Coordinated Universal Time (UTC). See gmtime_r() for details.
Inputs
tt - The time to convert
Result
A statically allocated buffer with the broken down time in Coordinated Universal Time (UTC). Note that the contents of the buffer might get lost with the call of any of the date and time functions.
Example
time_t tt; struct tm * tm; // Get the time time (&tt); // and convert it tm = gmtime (&tt);
Notes
Resulting tm struct is buffered per stdc.library and shared with localtime().
See also
hypot()
Synopsis
double hypot( double x, double y)
Function
Computes sqrt(x*x + y*y) without intermediate overflow or underflow.
Inputs
x, y - double values.
Result
Hypotenuse sqrt(x² + y²).
Example
double h = hypot(3.0, 4.0); // h = 5.0
Notes
More accurate than direct sqrt(x*x + y*y).
Bugs
None known.
hypotf()
Synopsis
float hypotf( float x, float y)
Function
Returns sqrt(x² + y²) without overflow/underflow.
Inputs
x, y - values.
Result
Euclidean distance.
Example
float v = hypotf(3.0f, 4.0f); // 5.0
Notes
Safer than naive sqrt(x*x + y*y).
Bugs
None known.
See also
hypotl()
Synopsis
long double hypotl( long double x, long double y)
Function
Computes sqrt(x² + y²) without undue overflow or underflow.
Inputs
x - first value. y - second value.
Result
Returns the Euclidean norm.
Example
long double r = hypotl(3.0L, 4.0L); // returns 5.0L
Notes
Accurate even if x or y is large/small.
Bugs
None known.
ilogbf()
Synopsis
int ilogbf( float x)
Function
Return the binary exponent of |x| as an integer.
Inputs
x - Float value to classify.
Result
The integer exponent e such that 2^e <= |x| < 2^(e+1) for finite nonzero x. Zero returns FP_ILOGB0; NaN returns FP_ILOGBNAN; infinity returns INT_MAX. In AROS, FP_ILOGBNAN equals INT_MAX, so these results are ambiguous.
Notes
Include <math.h>. Use isnan() or isinf() on the input to distinguish NaN from infinity. Unlike logbf(), the result is an integer sentinel for exceptional inputs.
Bugs
The subnormal scan shifts a signed 32-bit integer into its sign bit, an operation with undefined behavior in C. Subnormal results may depend on the compiler.
See also
ilogbl()
Synopsis
int ilogbl( long double x)
Function
Return the binary exponent of |x| as an integer.
Inputs
x - Long double value to classify.
Result
The integer exponent e such that 2^e <= |x| < 2^(e+1) for finite nonzero x. Zero returns FP_ILOGB0; NaN returns FP_ILOGBNAN; infinity returns INT_MAX. In AROS, FP_ILOGBNAN equals INT_MAX, so these results are ambiguous.
Notes
Include <math.h>. Use isnan() or isinf() on the input to distinguish NaN from infinity. Unlike logbl(), the result is an integer sentinel for exceptional inputs. Where long double equals double, ilogbl() aliases ilogb().
Bugs
The separate long double subnormal scan assumes unsigned long can hold the significand field. On 32-bit-long targets using binary128, shifts by 63 or 47 bits are undefined. The equal-precision double alias has its own signed-shift defect for subnormal inputs.
See also
imaxabs()
Synopsis
intmax_t imaxabs( intmax_t j)
Function
Compute the absolute value of an integer "j".
Result
Return the absolute value.
imaxdiv()
Synopsis
imaxdiv_t imaxdiv( intmax_t num, intmax_t denom)
Function
Computes the value num/denom and returns the quotient and remainder in a structure named imaxdiv_t.
Result
Return quotient and remainder from division.
ioerr2errno()
Synopsis
int ioerr2errno( int ioerr)
Function
Convert a DOS error number to a stdc error number.
Inputs
ioerr - Zero or a positive DOS error number no greater than
INT_MAX - MAX_ERRNO.
Result
Zero for input zero. The following DOS errors map to errno constants: ERROR_OBJECT_WRONG_TYPE EINVAL ERROR_INVALID_COMPONENT_NAME EINVAL ERROR_NO_FREE_STORE ENOMEM ERROR_DEVICE_NOT_MOUNTED ENOENT ERROR_OBJECT_NOT_FOUND ENOENT ERROR_OBJECT_EXISTS EEXIST ERROR_BUFFER_OVERFLOW ENOBUFS ERROR_BREAK EINTR ERROR_FILE_NOT_OBJECT ENOEXEC ERROR_NOT_EXECUTABLE ENOEXEC ERROR_OBJECT_IN_USE EBUSY ERROR_DIR_NOT_FOUND ENOTDIR ERROR_RENAME_ACROSS_DEVICES EXDEV Other values return MAX_ERRNO + ioerr.
Notes
Include <errno.h>. The function neither reads IoErr() nor changes errno or the DOS error state. Assign the result to errno when required. These mappings describe stdc.library. The selected C link library may override ioerr2errno(); __stdc_ioerr2errno() selects the stdc.library implementation. The stdc strerror() implementation recognizes positive DOS errors encoded with the MAX_ERRNO offset.
See also
isalnum()
Synopsis
int isalnum( int c)
Function
Test if a character is an alphabetic character or a digit. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is alphabetic character or a digit, 0 otherwise.
Example
isalnum ('A') -> true
isalnum ('a') -> true
isalnum ('0') -> true
isalnum ('.') -> false
isalnum ('\n') -> false
isalnum ('\001') -> false
isalnum (EOF) -> false
isalpha()
Synopsis
int isalpha( int c)
Function
Test if a character is an alphabetic character. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is an alphabetic character, 0 otherwise.
Example
isalpha ('A') -> true
isalpha ('a') -> true
isalpha ('0') -> false
isalpha ('.') -> false
isalpha ('\n') -> false
isalpha ('\001') -> false
isalpha (EOF) -> false
isascii()
Synopsis
int isascii( int c)
Function
Test if a character is an ascii character. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is an ascii character, 0 otherwise.
Example
isascii ('A') -> true
isascii ('a') -> true
isascii ('0') -> true
isascii ('.') -> true
isascii ('\n') -> true
isascii ('\001') -> true
isascii (EOF) -> false
isblank()
Synopsis
int isblank( int c)
Function
Test if a character is a space or a tab. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is a space or tab, 0 otherwise.
Example
isblank ('A') -> false
isblank ('a') -> false
isblank ('0') -> false
isblank ('.') -> false
isblank (' ') -> true
isblank ('\n') -> false
isblank ('\001') -> false
isblank (EOF) -> false
iscntrl()
Synopsis
int iscntrl( int c)
Function
Test if a character is a control character. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is a control character, 0 otherwise.
Example
iscntrl ('A') -> false
iscntrl ('a') -> false
iscntrl ('0') -> false
iscntrl ('.') -> false
iscntrl ('\n') -> true
iscntrl ('\001') -> true
iscntrl (EOF) -> false
isdigit()
Synopsis
int isdigit( int c)
Function
Test if a character is a digit. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is a digit, 0 otherwise.
Example
isdigit ('A') -> false
isdigit ('a') -> false
isdigit ('0') -> true
isdigit ('.') -> false
isdigit ('\n') -> false
isdigit ('\001') -> false
isdigit (EOF) -> false
isgraph()
Synopsis
int isgraph( int c)
Function
Test if a character is a printable character but no whitespace. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is a printable character but no whitespace, 0 otherwise.
Example
isgraph ('A') -> true
isgraph ('a') -> true
isgraph ('0') -> true
isgraph ('.') -> true
isgraph ('\n') -> false
isgraph ('\001') -> false
isgraph (EOF) -> false
islower()
Synopsis
int islower( int c)
Function
Test if a character is lowercase. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is lowercase, 0 otherwise.
Example
islower ('A') -> false
islower ('a') -> true
islower ('0') -> false
islower ('.') -> false
islower ('\n') -> false
islower ('\001') -> false
islower (EOF) -> false
isprint()
Synopsis
int isprint( int c)
Function
Test if a character is a printable character. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is a printable character, 0 otherwise.
Example
isprint ('A') -> true
isprint ('a') -> true
isprint ('0') -> true
isprint ('.') -> true
isprint ('\n') -> true
isprint ('\001') -> false
isprint (EOF) -> false
ispunct()
Synopsis
int ispunct( int c)
Function
Test if a character is printable but not alphanumeric. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is printable but not alphanumeric, 0 otherwise.
Example
ispunct ('A') -> false
ispunct ('a') -> false
ispunct ('0') -> false
ispunct ('.') -> true
ispunct ('\n') -> false
ispunct ('\001') -> false
ispunct (EOF) -> false
isspace()
Synopsis
int isspace( int c)
Function
Test if a character is whitespace. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is whitespace, 0 otherwise.
Example
isspace ('A') -> false
isspace ('a') -> false
isspace ('0') -> false
isspace ('.') -> false
isspace ('\n') -> true
isspace ('\001') -> false
isspace (EOF) -> false
isupper()
Synopsis
int isupper( int c)
Function
Test if a character is uppercase. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is uppercase, 0 otherwise.
Example
isupper ('A') -> true
isupper ('a') -> false
isupper ('0') -> false
isupper ('.') -> false
isupper ('\n') -> false
isupper ('\001') -> false
isupper (EOF) -> false
iswctype()
Synopsis
int iswctype( wint_t wc, wctype_t desc)
Function
Tests whether a wide character `wc` has the property indicated by `desc`, which must be a value returned by `wctype()`.
Inputs
wc - the wide character code point to test. desc - classification descriptor returned by `wctype()`.
Result
Non-zero if the character has the property; zero otherwise.
Example
if (iswctype(L'9', wctype("digit"))) {
// Character is a digit
}
Notes
The `desc` value must be obtained from a prior call to `wctype()`. Behavior is undefined if `desc` is invalid or comes from a different implementation.
Bugs
Only standard ASCII and Latin-1 Supplement classifications are supported. No locale-specific behavior or Unicode categories beyond U+00FF are recognized.
See also
isxdigit()
Synopsis
int isxdigit( int c)
Function
Test if a character is a hexadecimal digit. Works for all characters between -128 and 255 inclusive both.
Inputs
c - The character to test.
Result
!= 0 if the character is a hexadecimal digit, 0 otherwise.
Example
isxdigit ('A') -> true
isxdigit ('a') -> true
isxdigit ('x') -> false
isxdigit ('0') -> true
isxdigit ('.') -> false
isxdigit ('\n') -> false
isxdigit ('\001') -> false
isxdigit (EOF) -> false
j0()
Synopsis
double j0( double x)
Function
Computes the Bessel function of the first kind of order zero, J0(x).
Inputs
x - input value.
Result
The value of J0(x).
Example
double val = j0(0.0); // val == 1.0
Notes
Oscillatory function, used in many physics and engineering problems. Domain: all real numbers.
Bugs
May lose precision for very large x.
j0f()
Synopsis
float j0f( float x)
Function
Evaluate the Bessel function of the first kind, J_0(x), of order zero.
Inputs
x - Real argument. Negative arguments are accepted.
Result
An approximation to J_0(x) as a float. Both signs of zero return 1. Both infinities return positive zero. NaN returns NaN.
Notes
Include <math.h>. This is a BSD extension. The function does not assign errno. Floating-point exceptions may occur; enabled traps may prevent return. Use round-to-nearest. The trigonometric argument reduction used for large arguments assumes this rounding mode. J_0 is even: J_0(-x) = J_0(x).
j1()
Synopsis
double j1( double x)
Function
Computes the Bessel function of the first kind of order one, J1(x).
Inputs
x - input value.
Result
The value of J1(x).
Example
double val = j1(0.0); // val == 0.0
Notes
Oscillatory function, important in wave propagation. Domain: all real numbers.
Bugs
May lose precision for very large x.
j1f()
Synopsis
float j1f( float x)
Function
Evaluate the Bessel function of the first kind, J_1(x), of order one.
Inputs
x - Real argument. Negative arguments are accepted.
Result
An approximation to J_1(x) as a float. Zero arguments retain their sign. Infinite arguments return zero with the sign of x. NaN returns NaN.
Notes
Include <math.h>. This is a BSD extension. The function does not assign errno. Floating-point exceptions may occur; enabled traps may prevent return. Use round-to-nearest. The trigonometric argument reduction used for large arguments assumes this rounding mode. J_1 is odd: J_1(-x) = -J_1(x).
jn()
Synopsis
double jn( int n, double x)
Function
Computes the Bessel function of the first kind of order `n` at `x`.
Inputs
n - order of the Bessel function (integer). x - the point at which to evaluate.
Result
Returns the value of the Bessel function \( J_n(x) \). If `x` is infinite or NaN, forwards to __ieee754_jn.
Example
double r = jn(0, 1.0); // J0(1.0)
Notes
Commonly appears in solutions to wave and diffusion equations with cylindrical symmetry.
Bugs
None known.
jnf()
Synopsis
float jnf( int n, float x)
Function
Evaluate the Bessel function of the first kind, J_n(x), for integer order n.
Inputs
n - Integer order; see BUGS for unsupported extreme orders. x - Real argument. Negative arguments are accepted.
Result
An approximation to J_n(x) as a float. NaN returns NaN. For n = 0, either sign of zero returns 1 and either infinity returns positive zero. For other supported orders, zero and infinite arguments return zero, with the sign determined by the parity of n and the signs of n and x.
Notes
Include <math.h>. This is a BSD extension. The function does not assign errno. Floating-point exceptions may occur; enabled traps may prevent return. Use round-to-nearest. The trigonometric argument reduction used for large arguments assumes this rounding mode. Evaluation time can grow with the magnitude of n. For positive integer m, J_-m(x) = (-1)^m J_m(x) and J_m(-x) = (-1)^m J_m(x).
Bugs
INT_MIN is not supported: negating this order overflows signed int for non-NaN arguments. Large orders can also overflow integer recurrence calculations; for example, n = 1073741824 and x = 1 are unsafe with 32-bit int. For |x| < 2^-29 and |n| > 33, the function returns zero without raising underflow for the discarded result.
labs()
Synopsis
long labs( long j)
Function
Compute the absolute value of j.
Inputs
j - A signed long
Result
The absolute value of j.
Example
// returns 1 labs (1L); // returns 1 labs (-1L);
ldexp()
Synopsis
double ldexp( double x, int exp)
Function
Computes x * 2^exp.
Inputs
x - base double exp - exponent integer
Result
x scaled by 2 to the exp.
Example
double r = ldexp(1.5, 3); // 12.0
Notes
Used for binary exponent scaling.
Bugs
None known.
See also
ldexpf()
Synopsis
float ldexpf( float x, int n)
Function
Multiply x by 2 raised to n.
Inputs
x - Value to scale. n - Base-two exponent.
Result
The scaled float value. Inexact results are rounded according to the current floating-point rounding direction. Signed zero and infinity retain their signs; NaN produces NaN.
Notes
Include <math.h>. ldexpf() is a symbol alias of scalbnf(), with identical numerical and exception behavior. This implementation does not set errno. Overflow and underflow may raise floating-point exceptions.
Bugs
The shared implementation adds n to a signed exponent without checking for overflow. For x = 1 and n = INT_MAX, this causes undefined signed integer arithmetic before the range check.
See also
ldexpl()
Synopsis
long double ldexpl( long double x, int n)
Function
Multiply x by 2 raised to n.
Inputs
x - Value to scale. n - Base-two exponent.
Result
The scaled long double value, subject to the limitations described in BUGS. Inexact results depend on the current floating-point rounding direction. Signed zero and infinity retain their signs; NaN produces NaN.
Notes
Include <math.h>. ldexpl() aliases scalbnl() where long double has a separate implementation, or scalbn() where double and long double have equal precision. Neither path sets errno. Overflow and underflow may raise floating-point exceptions.
Bugs
The scaling implementations add n to a signed exponent without checking for overflow. For x = 1 and n = INT_MAX, this causes undefined signed integer arithmetic before the range check. The separate long double implementation narrows its underflow constant through double-precision copysign(). Under downward rounding, a negative input can yield negative zero where a negative subnormal is required. The equal-precision alias does not use this implementation.
See also
ldiv()
Synopsis
ldiv_t ldiv( long int numer, long int denom)
Function
Compute quotient en remainder of two long variables
Inputs
numer = the numerator denom = the denominator
Result
a struct with two long ints quot and rem with
quot = numer / denom and rem = numer % denom.
typedef struct ldiv_t {
long int quot;
long int rem;
} ldiv_t;
See also
lgamma()
Synopsis
double lgamma( double x)
Function
Computes the natural logarithm of the absolute value of the gamma function.
Inputs
x - input value.
Result
Returns ln(|G(x)|). Domain errors set errno to EDOM.
Example
double val = lgamma(5.0);
Notes
Useful for large arguments to avoid overflow.
Bugs
None known.
lgamma_r()
Synopsis
double lgamma_r( double x, int *signgamp)
Function
Return the natural logarithm of the absolute value of Gamma(x), and store its sign separately.
Inputs
x - Double argument.
signgamp - Non-NULL pointer to writable int storage. The
function writes this object for every argument,
including poles and nonfinite values.
Result
An approximation to log(|Gamma(x)|) in double. For finite nonpole arguments, *signgamp is +1 or -1 according to the sign of Gamma(x), subject to BUGS. Returns zero for x equal to 1 or 2. Both signs of zero and negative integers are poles and return positive infinity. Either infinity returns positive infinity; NaN returns NaN. At negative zero, *signgamp is -1. At positive zero, negative integer poles, either infinity and NaN, it is +1. These special-case values do not indicate a valid finite Gamma value or successful evaluation.
Notes
Include <math.h>. Use tgamma() when you need Gamma(x) itself. The result can be negative even when *signgamp is positive. The signgam variable is not used as implicit output. Passing &signgam explicitly still writes that object. Use separate output storage for independent concurrent calls. The function does not assign errno. Pole arithmetic can raise divide-by-zero; other arithmetic can raise overflow or inexact. Enabled traps may prevent return.
Bugs
Large negative noninteger arguments can produce an incorrect Gamma sign. For example, x equal to -1125899906842625.5 can report -1 although Gamma(x) is positive.
lgammaf()
Synopsis
float lgammaf( float x)
Function
Return the natural logarithm of the absolute value of Gamma(x), and store its sign in signgam.
Inputs
x - Float argument.
Result
An approximation to log(|Gamma(x)|) in float. For finite nonpole arguments, signgam is +1 or -1 according to the sign of Gamma(x), subject to BUGS. Returns zero for x equal to 1 or 2. Both signs of zero and negative integers are poles and return positive infinity. Either infinity returns positive infinity; NaN returns NaN. At negative zero, signgam is -1. At positive zero, negative integer poles, either infinity and NaN, it is +1. These values do not indicate successful evaluation.
Notes
Include <math.h> to access signgam. On AROS it is a macro; do not replace the header with an extern int declaration. Read or copy signgam before another call that overwrites it. Use lgammaf_r() with your own output storage when the sign must remain independent of other calls. Use tgammaf() for Gamma(x) itself. The return value here can be negative even when signgam is positive. The function does not assign errno. Pole arithmetic can raise divide-by-zero; other arithmetic can raise overflow or inexact. Enabled traps may prevent return.
Bugs
Large negative noninteger arguments can produce an incorrect Gamma sign. For example, x equal to -2097153.5f can report -1 although Gamma(x) is positive.
See also
lgammaf_r()
Synopsis
float lgammaf_r( float x, int *signgamp)
Function
Return the natural logarithm of the absolute value of Gamma(x), and store its sign separately.
Inputs
x - Float argument.
signgamp - Non-NULL pointer to writable int storage. The
function writes this object for every argument,
including poles and nonfinite values.
Result
An approximation to log(|Gamma(x)|) in float. For finite nonpole arguments, *signgamp is +1 or -1 according to the sign of Gamma(x), subject to BUGS. Returns zero for x equal to 1 or 2. Both signs of zero and negative integers are poles and return positive infinity. Either infinity returns positive infinity; NaN returns NaN. At negative zero, *signgamp is -1. At positive zero, negative integer poles, either infinity and NaN, it is +1. These special-case values do not indicate a valid finite Gamma value or successful evaluation.
Notes
Include <math.h>. Use tgammaf() when you need Gamma(x) itself. The result can be negative even when *signgamp is positive. The signgam variable is not used as implicit output. Passing &signgam explicitly still writes that object. Use separate output storage for independent concurrent calls. The function does not assign errno. Pole arithmetic can raise divide-by-zero; other arithmetic can raise overflow or inexact. Enabled traps may prevent return.
Bugs
Large negative noninteger arguments can produce an incorrect Gamma sign. For example, x equal to -2097153.5f can report -1 although Gamma(x) is positive.
See also
lgammal()
Synopsis
long double lgammal( long double x)
Function
Computes the natural logarithm of the absolute value of the gamma function.
Inputs
x - input value.
Result
Returns ln|G(x)|.
Example
long double r = lgammal(5.0L); // Ë ln(24)
Notes
Useful for large factorials: lgammal(n+1) Ë ln(n!)
Bugs
None known.
lgammal_r()
Synopsis
long double lgammal_r( long double x, int *signgamp)
Function
Compute the natural logarithm of the absolute gamma function and its sign.
Inputs
x - Argument to the gamma function.
signgamp - Non-NULL pointer to writable int storage. Receives the sign
of Gamma(x), normally +1 or -1 for finite non-pole arguments.
Result
An approximation to log(|Gamma(x)|), not Gamma(x). Returns zero for x equal to 1 or 2, positive infinity at either signed zero or a negative integer, positive infinity for either infinite input, and NaN for NaN. Large positive finite inputs can overflow. At -0, *signgamp is -1; at +0, negative integer poles, infinities and NaN, it is +1. These values at poles and non-finite inputs do not establish a valid finite Gamma value.
Notes
Include <math.h>. The sign of the logarithm is independent of the reported Gamma sign. Use tgammal() when Gamma(x) itself is required. The function writes through signgamp on every returning path and does not use signgam as implicit output. Use separate output storage for independent concurrent calls; passing &signgam still writes that object. No explicit errno assignment is made here. Pole evaluation uses division by zero; overflow and inexact exceptions can arise during arithmetic. Enabled traps may prevent return. Precision follows the target long double format; equal-precision targets alias lgamma_r().
Bugs
Argument reduction for large negative nonintegers can select the wrong reflection interval, producing an incorrect Gamma sign and logarithm. This affects the extended-precision variants as well as the double alias; avoid relying on these results for large negative arguments.
See also
llabs()
Synopsis
long long llabs( long long j)
Function
Compute the absolute value of j.
Inputs
j - A signed long long
Result
The absolute value of j.
Example
// returns 1 labs (1L); // returns 1 labs (-1L);
lldiv()
Synopsis
lldiv_t lldiv( long long int numer, long long int denom)
Function
Compute quotient en remainder of two long long variables
Inputs
numer = the numerator denom = the denominator
Result
a struct with two long ints quot and rem with
quot = numer / denom and rem = numer % denom.
typedef struct lldiv_t {
long long int quot;
long long int rem;
} lldiv_t;
llrint()
Synopsis
long long llrint( double x)
Function
Round x in the current floating-point rounding mode and convert the result to long long. Nearest rounding selects the even integer at a tie.
Inputs
x - Finite double value whose rounded result fits in long long.
Result
The integer result. Both signed zeros become zero. No error value is reserved for an invalid conversion.
Notes
Include <math.h>. Use <fenv.h> to control the rounding mode. With functioning environment support, the wrapper restores the caller's environment and clears new FE_INEXACT if FE_INVALID was raised. Preexisting exception flags are preserved.
Bugs
Conversion of NaN, infinity or an out-of-range rounded value is undefined; the wrapper does not validate the integer cast. Floating-point environment failures are ignored, and some AROS targets provide incomplete or stub implementations. On RISC-V hard-float, a failed save can lead to restoration of uninitialized environment state. The rint() delegate has undefined C behavior for some small negative inputs.
See also
llrintf()
Synopsis
long long llrintf( float x)
Function
Round x in the current floating-point rounding mode and convert the result to long long. Nearest rounding selects the even integer at a tie.
Inputs
x - Finite float value whose rounded result fits in long long.
Result
The integer result. Both signed zeros become zero. No error value is reserved for an invalid conversion.
Notes
Include <math.h>. Use <fenv.h> to control the rounding mode. With functioning environment support, the wrapper restores the caller's environment and clears new FE_INEXACT if FE_INVALID was raised. Preexisting exception flags are preserved.
Bugs
Conversion of NaN, infinity or an out-of-range rounded value is undefined; the wrapper does not validate the integer cast. Floating-point environment failures are ignored, and some AROS targets provide incomplete or stub implementations. On RISC-V hard-float, a failed save can lead to restoration of uninitialized environment state. The rintf() delegate has undefined C behavior for some small negative inputs.
See also
llrintl()
Synopsis
long long llrintl( long double x)
Function
Round x in the current floating-point rounding mode and convert the result to long long. Nearest rounding selects the even integer at a tie.
Inputs
x - Finite long double value whose rounded result fits in long long.
Result
The integer result. Both signed zeros become zero. No error value is reserved for an invalid conversion.
Notes
Include <math.h>. Use <fenv.h> to control the rounding mode. With functioning environment support, the wrapper restores the caller's environment and clears new FE_INEXACT if FE_INVALID was raised. Preexisting exception flags are preserved. Where long double has the same precision as double, this symbol is an alias of the double-input variant.
Bugs
Conversion of NaN, infinity or an out-of-range rounded value is undefined; the wrapper does not validate the integer cast. Floating-point environment failures are ignored, and some AROS targets provide incomplete or stub implementations. On RISC-V hard-float, a failed save can lead to restoration of uninitialized environment state. The separate rintl() delegate depends on long double evaluation precision; reduced x87 precision can produce an incorrect result. The double alias inherits the double rint() limitation.
See also
llround()
Synopsis
long long llround( double x)
Function
Round x to the nearest integer, with halfway cases away from zero, and return the result as long long. The current rounding direction does not affect the result.
Inputs
x - Finite double value whose rounded result fits in long long.
Result
The rounded integer. Both signs of zero return 0. No defined result is guaranteed for nonfinite inputs or an out-of-range conversion.
Notes
Include <math.h>. The implementation calls round() before conversion to long long. It does not assign errno. Rounding can affect floating-point exception flags.
Bugs
The range check can accept NaNs, infinities and out-of-range values, allowing undefined floating-to-integer conversions. The explicit rejection path raises FE_INVALID and returns LLONG_MAX if execution continues, but not all invalid inputs reach it. LLONG_MAX is also a valid result, not a unique error sentinel.
See also
llroundf()
Synopsis
long long llroundf( float x)
Function
Round x to the nearest integer, with halfway cases away from zero, and return the result as long long. The current rounding direction does not affect the result.
Inputs
x - Finite float value whose rounded result fits in long long.
Result
The rounded integer. Both signs of zero return 0. No defined result is guaranteed for nonfinite inputs or an out-of-range conversion.
Notes
Include <math.h>. The implementation calls roundf() before conversion to long long. It does not assign errno. Rounding can affect floating-point exception flags.
Bugs
The range check can accept NaNs, infinities and out-of-range values, allowing undefined floating-to-integer conversions. The explicit rejection path raises FE_INVALID and returns LLONG_MAX if execution continues, but not all invalid inputs reach it. LLONG_MAX is also a valid result, not a unique error sentinel.
See also
llroundl()
Synopsis
long long llroundl( long double x)
Function
Round x to the nearest integer, with halfway cases away from zero, and return the result as long long. The current rounding direction does not affect the result.
Inputs
x - Finite long double value whose rounded result fits in long long.
Result
The rounded integer. Both signs of zero return 0. No defined result is guaranteed for nonfinite inputs or an out-of-range conversion.
Notes
Include <math.h>. The implementation calls roundl() before conversion to long long. It does not assign errno. Rounding can affect floating-point exception flags. On targets where long double and double have equal precision, this symbol aliases the corresponding double implementation.
Bugs
The range check can accept NaNs, infinities and out-of-range values, allowing undefined floating-to-integer conversions. The explicit rejection path raises FE_INVALID and returns LLONG_MAX if execution continues, but not all invalid inputs reach it. LLONG_MAX is also a valid result, not a unique error sentinel.
See also
localeconv()
Synopsis
struct lconv *localeconv( void)
Function
The localeconv function sets the components of an object with type struct lconv with values appropriate for the formatting of numeric quantities (monetary and otherwise) according to the rules of the current locale.
Inputs
-
Result
The lconv struct
Notes
stdc.library only support "C" locale so always the same data is returned.
See also
localtime()
Synopsis
struct tm * localtime( const time_t * tt)
Function
Splits the system time in seconds into a structure. See localtime_r() for details.
Inputs
tt - A time in seconds from the 1. Jan 1970
Result
A statically allocated buffer with the broken up time. Note that the contents of the buffer might get lost with the call of any of the date and time functions.
Example
time_t tt; struct tm * tm; // Get time time (&tt); // Break time up tm = localtime (&tt);
Notes
Resulting tm struct is buffered per stdc.library and shared with gmtime().
See also
log()
Synopsis
double log( double x)
Function
Computes the natural logarithm (base e) of x.
Inputs
x - input value (must be positive).
Result
Returns ln(x). Returns NaN and sets errno to EDOM if x = 0.
Example
double val = log(2.718281828); // approximately 1.0
Notes
Uses IEEE 754 semantics for special values.
Bugs
None known.
log10()
Synopsis
double log10( double x)
Function
Computes the base-10 logarithm of x.
Inputs
x - input value (must be positive).
Result
Returns log10(x). Returns NaN and sets errno to EDOM if x = 0.
Example
double val = log10(100.0); // returns 2.0
Notes
Uses IEEE 754 semantics.
Bugs
None known.
log10f()
Synopsis
float log10f( float x)
Function
Return the base-10 logarithm of x.
Inputs
x - Positive float value, including positive subnormal values.
Result
An approximation to the base-10 logarithm in float. Returns positive zero for x = 1. Both signs of zero return negative infinity. Negative values, including negative infinity, return NaN. Positive infinity returns positive infinity; NaN returns NaN.
Notes
Include <math.h>. The function does not assign errno. Zero arguments can raise divide-by-zero; negative arguments can raise invalid. Other arithmetic can raise inexact. Enabled traps may prevent return.
log10l()
Synopsis
long double log10l( long double x)
Function
Computes the base-10 logarithm of x.
Inputs
x - a positive number.
Result
Returns log10(x), or -8 if x == 0.
Example
long double r = log10l(1000.0L); // returns 3.0L
Notes
Domain error if x <= 0.
Bugs
None known.
log1p()
Synopsis
double log1p( double x)
Function
Computes the natural logarithm of (1 + x), i.e. ln(1 + x), with high accuracy even for values of x near zero.
Inputs
x - input value.
Result
Returns ln(1 + x). If x == -1.0, returns -INFINITY and sets errno to ERANGE. If x < -1.0, returns NaN and sets errno to EDOM.
Example
double val = log1p(1e-9); // accurate result close to 1e-9 double val2 = log1p(-1.0); // returns -INFINITY, sets errno = ERANGE
Notes
This function is more accurate than using log(1 + x) directly for small x, due to reduced cancellation error. The result is well-defined for all x > -1. If x < -1, the result is undefined (logarithm of a negative number).
Bugs
None known.
log1pf()
Synopsis
float log1pf( float x)
Function
Return the natural logarithm of 1 + x without losing small x to rounding in the addition.
Inputs
x - Float value greater than -1 for a finite result.
Result
An approximation to log(1 + x) in float. Signed zero retains its sign. At x = -1, returns negative infinity. For x < -1, including negative infinity, returns NaN. Positive infinity returns positive infinity; NaN returns NaN.
Notes
Include <math.h>. Prefer log1pf(x) to logf(1.0f + x) when x is close to zero. The latter can lose x before the logarithm is evaluated. The function does not assign errno. The pole at -1 can raise divide-by-zero; arguments below -1 can raise invalid. Other arithmetic can raise inexact. Enabled traps may prevent return.
log1pl()
Synopsis
long double log1pl( long double x)
Function
Computes log(1 + x) accurately for small x.
Inputs
x - a number greater than -1.
Result
Returns log(1 + x).
Example
long double r = log1pl(1.0e-10L);
Notes
Accurate even if x is near zero.
Bugs
None known.
log2()
Synopsis
double log2( double x)
Function
Computes the base-2 logarithm of x.
Inputs
x - input value (must be positive).
Result
Returns log2(x). Returns NaN and sets errno to EDOM if x = 0.
Example
double val = log2(8.0); // returns 3.0
Notes
Uses IEEE 754 semantics.
Bugs
None known.
log2f()
Synopsis
float log2f( float x)
Function
Return the base-2 logarithm of x.
Inputs
x - Positive float value, including positive subnormal values.
Result
An approximation to the base-2 logarithm in float. Returns positive zero for x = 1. Both signs of zero return negative infinity. Negative values, including negative infinity, return NaN. Positive infinity returns positive infinity; NaN returns NaN.
Notes
Include <math.h>. The function does not assign errno. Zero arguments can raise divide-by-zero; negative arguments can raise invalid. Other arithmetic can raise inexact. Enabled traps may prevent return.
log2l()
Synopsis
long double log2l( long double x)
Function
Computes the base-2 logarithm of x.
Inputs
x - a positive number.
Result
Returns log2(x), or -8 if x == 0.
Example
long double r = log2l(8.0L); // returns 3.0L
Notes
Domain error if x <= 0.
Bugs
None known.
logbf()
Synopsis
float logbf( float x)
Function
Return the base-two exponent of the magnitude of x as a floating-point value.
Inputs
x - Float value to examine.
Result
For finite nonzero x, e such that 2^e <= |x| < 2^(e+1). Zero returns negative infinity, infinity returns positive infinity, and NaN returns NaN.
Notes
Include <math.h>. The zero path divides by zero and can raise FE_DIVBYZERO. A floating-point trap may prevent return. Unlike ilogbf(), special inputs produce floating-point values rather than integer sentinels.
logbl()
Synopsis
long double logbl( long double x)
Function
Return the base-two exponent of the magnitude of x as a floating-point value.
Inputs
x - Long double value to examine.
Result
For finite nonzero x, e such that 2^e <= |x| < 2^(e+1). Zero returns negative infinity, infinity returns positive infinity, and NaN returns NaN.
Notes
Include <math.h>. The zero path divides by zero and can raise FE_DIVBYZERO. A floating-point trap may prevent return. Unlike ilogbl(), special inputs produce floating-point values rather than integer sentinels. Where long double equals double, logbl() aliases logb().
Bugs
The separate long double subnormal scan requires an unsigned long wide enough for the significand field. Binary128 on a 32-bit-long target can shift by 63 or 47 bits, which is undefined behavior in C.
logf()
Synopsis
float logf( float x)
Function
Return the natural logarithm of x.
Inputs
x - Positive float value, including positive subnormal values.
Result
An approximation to the natural logarithm in float. Returns positive zero for x = 1. Both signs of zero return negative infinity. Negative values, including negative infinity, return NaN. Positive infinity returns positive infinity; NaN returns NaN.
Notes
Include <math.h>. The function does not assign errno. Zero arguments can raise divide-by-zero; negative arguments can raise invalid. Other arithmetic can raise inexact. Enabled traps may prevent return.
logl()
Synopsis
long double logl( long double x)
Function
Computes the natural logarithm (base e) of x.
Inputs
x - input value (must be positive).
Result
Returns ln(x). Returns NaN and sets errno to EDOM if x = 0.
Example
double val = log(2.718281828); // approximately 1.0
Notes
Uses IEEE 754 semantics for special values.
Bugs
None known.
longjmp()
Synopsis
void longjmp( jmp_buf env, int val)
Function
Resume execution at the environment most recently saved in env.
Inputs
env - Intact jmp_buf initialized by setjmp() in the current thread.
Its saving function and the relevant variable-length scopes must
still be active.
val - Value returned by the resumed setjmp(). Zero is converted to 1.
Result
Does not return to its caller.
Notes
Restores the saved stack pointer, return address and CPU-specific register state. It does not run cleanup code in skipped functions, release locks, close files or free heap allocations. Arrange cleanup before jumping or in the resumed path. Use only an environment saved by setjmp(), with the same target ABI. Invalid, expired or cross-thread environments are not diagnosed before restoring the stack and transferring control. See setjmp() for the rules governing local variables and permitted save expressions. No signal mask is restored. Do not rely on this operation to restore floating-point control or exception state.
See also
setjmp() posixc/siglongjmp()
lrint()
Synopsis
long lrint( double x)
Function
Round x in the current floating-point rounding mode and convert the result to long. Nearest rounding selects the even integer at a tie.
Inputs
x - Finite double value whose rounded result fits in long.
Result
The integer result. Both signed zeros become zero. No error value is reserved for an invalid conversion.
Notes
Include <math.h>. Use <fenv.h> to control the rounding mode. With functioning environment support, the wrapper restores the caller's environment and clears new FE_INEXACT if FE_INVALID was raised. Preexisting exception flags are preserved.
Bugs
Conversion of NaN, infinity or an out-of-range rounded value is undefined; the wrapper does not validate the integer cast. Floating-point environment failures are ignored, and some AROS targets provide incomplete or stub implementations. On RISC-V hard-float, a failed save can lead to restoration of uninitialized environment state. The rint() delegate has undefined C behavior for some small negative inputs.
See also
lrintf()
Synopsis
long lrintf( float x)
Function
Round x in the current floating-point rounding mode and convert the result to long. Nearest rounding selects the even integer at a tie.
Inputs
x - Finite float value whose rounded result fits in long.
Result
The integer result. Both signed zeros become zero. No error value is reserved for an invalid conversion.
Notes
Include <math.h>. Use <fenv.h> to control the rounding mode. With functioning environment support, the wrapper restores the caller's environment and clears new FE_INEXACT if FE_INVALID was raised. Preexisting exception flags are preserved.
Bugs
Conversion of NaN, infinity or an out-of-range rounded value is undefined; the wrapper does not validate the integer cast. Floating-point environment failures are ignored, and some AROS targets provide incomplete or stub implementations. On RISC-V hard-float, a failed save can lead to restoration of uninitialized environment state. The rintf() delegate has undefined C behavior for some small negative inputs.
See also
lrintl()
Synopsis
long lrintl( long double x)
Function
Round x in the current floating-point rounding mode and convert the result to long. Nearest rounding selects the even integer at a tie.
Inputs
x - Finite long double value whose rounded result fits in long.
Result
The integer result. Both signed zeros become zero. No error value is reserved for an invalid conversion.
Notes
Include <math.h>. Use <fenv.h> to control the rounding mode. With functioning environment support, the wrapper restores the caller's environment and clears new FE_INEXACT if FE_INVALID was raised. Preexisting exception flags are preserved. Where long double has the same precision as double, this symbol is an alias of the double-input variant.
Bugs
Conversion of NaN, infinity or an out-of-range rounded value is undefined; the wrapper does not validate the integer cast. Floating-point environment failures are ignored, and some AROS targets provide incomplete or stub implementations. On RISC-V hard-float, a failed save can lead to restoration of uninitialized environment state. The separate rintl() delegate depends on long double evaluation precision; reduced x87 precision can produce an incorrect result. The double alias inherits the double rint() limitation.
See also
lround()
Synopsis
long lround( double x)
Function
Round x to the nearest integer, with halfway cases away from zero, and return the result as long. The current rounding direction does not affect the result.
Inputs
x - Finite double value whose rounded result fits in long.
Result
The rounded integer. Both signs of zero return 0. No defined result is guaranteed for nonfinite inputs or an out-of-range conversion.
Notes
Include <math.h>. The implementation calls round() before conversion to long. It does not assign errno. Rounding can affect floating-point exception flags.
Bugs
The range check can accept NaNs, infinities and out-of-range values, allowing undefined floating-to-integer conversions. The explicit rejection path raises FE_INVALID and returns LONG_MAX if execution continues, but not all invalid inputs reach it. LONG_MAX is also a valid result, not a unique error sentinel.
See also
lroundf()
Synopsis
long lroundf( float x)
Function
Round x to the nearest integer, with halfway cases away from zero, and return the result as long. The current rounding direction does not affect the result.
Inputs
x - Finite float value whose rounded result fits in long.
Result
The rounded integer. Both signs of zero return 0. No defined result is guaranteed for nonfinite inputs or an out-of-range conversion.
Notes
Include <math.h>. The implementation calls roundf() before conversion to long. It does not assign errno. Rounding can affect floating-point exception flags.
Bugs
The range check can accept NaNs, infinities and out-of-range values, allowing undefined floating-to-integer conversions. The explicit rejection path raises FE_INVALID and returns LONG_MAX if execution continues, but not all invalid inputs reach it. LONG_MAX is also a valid result, not a unique error sentinel.
See also
lroundl()
Synopsis
long lroundl( long double x)
Function
Round x to the nearest integer, with halfway cases away from zero, and return the result as long. The current rounding direction does not affect the result.
Inputs
x - Finite long double value whose rounded result fits in long.
Result
The rounded integer. Both signs of zero return 0. No defined result is guaranteed for nonfinite inputs or an out-of-range conversion.
Notes
Include <math.h>. The implementation calls roundl() before conversion to long. It does not assign errno. Rounding can affect floating-point exception flags. On targets where long double and double have equal precision, this symbol aliases the corresponding double implementation.
Bugs
The range check can accept NaNs, infinities and out-of-range values, allowing undefined floating-to-integer conversions. The explicit rejection path raises FE_INVALID and returns LONG_MAX if execution continues, but not all invalid inputs reach it. LONG_MAX is also a valid result, not a unique error sentinel.
See also
malloc()
Synopsis
void *malloc( size_t size)
Function
Allocate size bytes of memory and return the address of the first byte.
Inputs
size - How much memory to allocate.
Result
A pointer to the allocated memory or NULL. If you don't need the memory anymore, you can pass this pointer to free(). If you don't, the memory will be freed for you when the application exits.
See also
mblen()
Synopsis
int mblen( const char *s, size_t n)
Function
Determines the number of bytes comprising the next multibyte character in the input string 's', examining at most 'n' bytes. This function is typically used to scan or measure multibyte strings when the actual wide character value is not needed.
Inputs
s - Pointer to the multibyte character string to examine.
If NULL, the function is used to test whether the current encoding
has state-dependent encodings.
n - Maximum number of bytes to examine in 's'.
Result
Returns the number of bytes that make up the next multibyte character if the sequence is valid. Returns 0 if the character is the null byte (`'\0'`). Returns -1 if the sequence is invalid or incomplete, and sets errno to EILSEQ. If 's' is NULL, returns 0 in UTF-8 or "C" locale, indicating a stateless encoding.
Example
const char *mb = "ä";
int len = mblen(mb, MB_CUR_MAX);
if (len > 0) {
// len indicates how many bytes 'ä' takes in the current encoding
}
Notes
stdc.library currently only implements "C" or UTF-8-compatible encodings. Therefore, this function always returns 0 when 's' is NULL and does not track shift states. The function relies on UTF-8 byte patterns to determine the multibyte length.
Bugs
Does not support locale-specific or stateful encodings. No shift state is maintained between calls, even in encodings where this might be necessary.
See also
mbrlen()
Synopsis
size_t mbrlen( const char * restrict s, size_t n, mbstate_t * restrict ps)
Function
Determines the number of bytes needed to represent the next multibyte character in the input string 's'.
Inputs
s - Pointer to the input multibyte string. n - Maximum number of bytes to examine from 's'. ps - Conversion state object (unused in this stateless implementation).
Result
Returns the number of bytes that comprise the next multibyte character. Returns 0 if the character is the null character. Returns (size_t)-1 on encoding error and sets errno to EILSEQ. Returns (size_t)-2 if more bytes are needed to complete a valid character.
Example
const char *mbs = "ä"; size_t len = mbrlen(mbs, strlen(mbs), NULL);
Notes
Only UTF-8 multibyte sequences are supported. Implemented in terms of mbrtowc(NULL, s, n, ps) as required by C99 7.24.6.2, so the two functions always agree on what constitutes a valid sequence (including overlong/surrogate/out-of-range rejection).
See also
mbrtoc16()
Synopsis
size_t mbrtoc16( char16_t * restrict pc16, const char * restrict s, size_t n, mbstate_t * restrict ps)
Function
Converts a single multibyte character to a 16-bit (UTF-16) character. Code points outside the Basic Multilingual Plane are returned as a UTF-16 surrogate pair over two successive calls.
Inputs
pc16 - Where to store the converted code unit (may be NULL). s - Multibyte sequence to convert, or NULL. n - Maximum number of bytes from 's' to examine. ps - Conversion state (a static internal state is used if NULL).
Result
The number of bytes consumed, 0 for a null character, (size_t)-1 on an encoding error (errno = EILSEQ), (size_t)-2 for an incomplete sequence, or (size_t)-3 when the stored code unit is the low surrogate produced from a preceding call (no further input is consumed).
Notes
Only UTF-8 multibyte sequences are supported.
See also
mbrtoc32()
Synopsis
size_t mbrtoc32( char32_t * restrict pc32, const char * restrict s, size_t n, mbstate_t * restrict ps)
Function
Converts a single multibyte character to a 32-bit (UTF-32) character.
Inputs
pc32 - Where to store the converted character (may be NULL). s - Multibyte sequence to convert, or NULL. n - Maximum number of bytes from 's' to examine. ps - Conversion state (a static internal state is used if NULL).
Result
As mbrtowc(): the number of bytes consumed, 0 for a null character, (size_t)-1 on an encoding error (errno = EILSEQ) or (size_t)-2 for an incomplete sequence.
Notes
char32_t holds a complete Unicode code point, so on AROS - where wchar_t is 32 bits wide - this is equivalent to mbrtowc().
See also
mbrtowc()
Synopsis
size_t mbrtowc( wchar_t * restrict pwc, const char * restrict s, size_t n, mbstate_t * restrict ps)
Function
Converts the multibyte character at 's' to a wide character stored in *pwc.
Inputs
pwc - Pointer to output wide character (can be NULL). s - Pointer to the input multibyte character. n - Maximum number of bytes to examine from 's'. ps - Conversion state object (unused in this stateless implementation).
Result
Returns the number of bytes consumed to produce the wide character. Returns 0 if the null character was converted and stored. Returns (size_t)-1 on encoding error and sets errno to EILSEQ. Returns (size_t)-2 if 's' is NULL or points to an incomplete character.
Example
const char *mbs = "ä"; wchar_t wc; size_t len = mbrtowc(&wc, mbs, strlen(mbs), NULL);
Notes
Only UTF-8 multibyte sequences are supported. Locale-specific or stateful encodings are not implemented.
See also
mbsrtowcs()
Synopsis
size_t mbsrtowcs( wchar_t * restrict dst, const char ** restrict src, size_t len, mbstate_t * restrict ps)
Function
Converts a null-terminated multibyte character string pointed to by *src into a corresponding wide character string. The conversion uses the current locale (UTF-8 assumed here) and updates the src pointer to point past the last converted multibyte character.
Inputs
dst - Pointer to destination wide character buffer (may be NULL).
src - Address of the multibyte string pointer. The pointer is updated
during conversion. If dst is NULL, the function returns the
number of wide characters that would result from the conversion.
len - Maximum number of wide characters to write.
ps - Conversion state object (ignored in this implementation).
Result
Returns the number of wide characters written or needed. Returns (size_t)-1 on conversion error and sets errno to EILSEQ.
Notes
This implementation assumes stateless UTF-8 encoding and does not currently use mbstate_t. It wraps around mbrtowc().
See also
mbstowcs()
Synopsis
size_t mbstowcs( wchar_t * restrict dest, const char * restrict src, size_t n)
Function
Converts a null-terminated multibyte character string (char*) into its corresponding wide character string (wchar_t*), using the current locale's encoding. At most 'n' wide characters are written into 'dest'. Conversion stops on the first invalid multibyte sequence, or when a null byte is encountered.
Inputs
dest - Pointer to the output wide character buffer. If NULL, the function
returns the number of wide characters that would result from the conversion,
excluding the terminating null wide character.
src - Pointer to the null-terminated multibyte string to convert.
n - Maximum number of wide characters to write into 'dest'.
Result
Returns the number of wide characters converted (excluding the terminating L'\0'). Returns (size_t)-1 if an invalid multibyte sequence is encountered during conversion, and sets errno to EILSEQ. If 'dest' is NULL, the function returns the number of wide characters that would be generated from the conversion, not counting the final null wide character.
Example
const char *utf8 = "Hello ??!";
wchar_t wbuf[64];
size_t count = mbstowcs(wbuf, utf8, 64);
if (count != (size_t)-1) {
// wbuf now contains wide character equivalents
}
Notes
stdc.library currently only implements "C" or UTF-8-compatible locales. The encoding is stateless, and no locale-dependent shift state is used. Conversion uses mbtowc() for each multibyte sequence encountered in 'src'.
Bugs
Does not support locale-specific encodings or stateful encodings like ISO 2022 or Shift-JIS. Buffer overflow may occur if 'n' is smaller than the number of resulting wide characters.
See also
mbtowc()
Synopsis
int mbtowc( wchar_t * restrict pwc, const char * restrict s, size_t n)
Function
Converts the multibyte sequence starting at 's' into a wide character and stores it at the location pointed to by 'pwc'. The function examines up to 'n' bytes to determine the length of the multibyte character. If 's' is NULL, the function is used to reset the conversion state.
Inputs
pwc - Pointer to the location where the resulting wide character will be stored.
If NULL, the function still parses the multibyte sequence to determine length,
but does not store the result.
s - Pointer to the multibyte character sequence to convert.
If NULL, the function returns 0 (for stateless encodings like UTF-8).
n - Maximum number of bytes to examine from 's'.
Result
Returns the number of bytes that were consumed to produce a valid wide character. Returns 0 if the character is the null byte (`'\0'`). Returns -1 if an invalid or incomplete multibyte sequence is encountered, and sets errno to EILSEQ.
Example
const char *mb = "??";
wchar_t wc;
int len = mbtowc(&wc, mb, MB_CUR_MAX);
if (len > 0) {
// wc now holds the wide character value for '??'
}
Notes
stdc.library currently only implements "C" or UTF-8-compatible locales. The encoding is treated as stateless, so no shift state is used or stored. This function is not thread-safe with stateful encodings unless all calls use the same static state, which is not applicable here.
Bugs
Does not support stateful or locale-dependent encodings. Returns -1 on partial or invalid sequences without giving detailed error context.
See also
memccpy()
Synopsis
void * memccpy( void * restrict dest, const void * restrict src, int c, size_t n)
Function
Copy bytes from src to dest, stopping after the first occurrence of the byte c (converted to unsigned char) has been copied, or after n bytes have been copied, whichever comes first.
Inputs
dest - destination buffer. src - source buffer. c - stop copying once this byte (as unsigned char) is copied. n - maximum number of bytes to copy.
Result
A pointer to the byte in dest immediately following the copy of c, or NULL if c was not found in the first n bytes of src.
memchr()
Synopsis
void * memchr( const void * mem, int c, size_t n)
Function
Locate the first occurrence of c which is converted to an unsigned char in the first n bytes of the memory pointed to by mem.
Inputs
mem - pointer to memory that is searched for c c - the character to search for n - how many bytes to search through starting at mem
Result
pointer to the located byte or null if c was not found
memcmp()
Synopsis
int memcmp( const void * s1, const void * s2, size_t n)
Function
Calculate s1 - s2 for the n bytes after s1 and s2 and stop when the difference is not 0.
Inputs
s1, s2 - Begin of the memory areas to compare n - The number of bytes to compare
Result
The difference of the memory areas. The difference is 0, if both are equal, < 0 if s1 < s2 and > 0 if s1 > s2. Note that it may be greater then 1 or less than -1.
Notes
This function is not part of a library and may thus be called any time.
See also
memcpy()
Synopsis
void *memcpy( void * restrict dst0, const void * restrict src0, size_t length)
Function
Copy a block of memory; handling of overlapping regions is not guaranteed.
Inputs
dst0: destination for copy src0: source for copy length: number of bytes to copy
Result
dst0
Notes
stdc.library/memcpy() is an alias to stdc.library/memmove() So overlapping regions are handled OK if this function is used.
memmove()
Synopsis
void *memmove( void *dst0, const void *src0, size_t length)
Function
Copy a block of memory, handling overlap.
Inputs
dst0: destination for copy src0: source for copy length: number of bytes to copy
Result
dst0
memset()
Synopsis
void * memset( void * dest, int c, size_t count)
Function
Fill the memory at dest with count times c.
Inputs
dest - The first byte of the destination area in memory c - The byte to fill memory with count - How many bytes to write
Result
dest.
mktime()
Synopsis
time_t mktime( struct tm * utim)
Function
The mktime() function converts the broken-down time utim to calendar time representation.
Inputs
utim - The broken-down time to convert
Result
The converted calendar time
Example
time_t tt; struct tm * tm; //Computation which results in a tm tm = ... // and convert it tt = mktime (tm);
Bugs
At the moment sanity check is not performed nor a normalization on the structure is done
See also
modf()
Synopsis
double modf( double x, double *iptr)
Function
Splits the input number into fractional and integer parts.
Inputs
x - the input value to split. iptr - pointer to store the integer part of x.
Result
Returns the fractional part of x and stores the integer part at *iptr. If `iptr` is NULL, returns NaN and sets errno to EDOM.
Example
double i; double f = modf(3.14, &i); // f = 0.14, i = 3.0
Notes
The sum of the return value and *iptr equals x (except for rounding).
Bugs
None known.
modff()
Synopsis
float modff( float x, float *iptr)
Function
Splits the float x into integer and fractional parts.
Inputs
x - floating point number to split. iptr - pointer to float that will receive the integer part.
Result
Returns the fractional part of x.
Example
float i; float f = modff(3.14f, &i); // i = 3.0f, f = 0.14f
Notes
The result and *iptr have the same sign as x.
Bugs
None known.
modfl()
Synopsis
long double modfl( long double x, long double *iptr)
Function
Splits x into integer and fractional parts.
Inputs
x - input value. iptr - pointer to store the integer part.
Result
Returns the fractional part (x - *iptr).
Example
long double i; long double f = modfl(2.718L, &i); // i = 2.0L, f 0.718L
Notes
Does not raise domain errors.
Bugs
None known.
nanf()
Synopsis
float nanf( const char *s)
Function
Construct a quiet NaN from a hexadecimal payload string.
Inputs
s - Non-NULL, NUL-terminated string of hexadecimal digits,
optionally prefixed with 0x or 0X.
Result
A quiet float NaN. Digits after the first nonhexadecimal character are ignored; an empty tag supplies zero payload bits. Different tags can produce the same NaN.
Notes
Include <math.h>. Payload encoding is target-dependent and is not suitable as a portable serialized representation.
Bugs
Payload assembly shifts signed digits into the high nibble; digits 8 through F can cause undefined C behavior. The big-endian scanner uses a different nibble order from the little-endian scanner, so equal tags need not give matching payload bits across these targets.
nanl()
Synopsis
long double nanl( const char *s)
Function
Construct a quiet long double NaN from a hexadecimal tag. An optional 0x or 0X prefix is followed by hexadecimal digits. Scanning stops at the first other character.
Inputs
s - Readable, null-terminated ASCII string. May be empty,
but must not be NULL. Leading whitespace and signs
are not skipped. The string is not modified or retained.
The initial digit sequence must fit in an int index.
Result
A quiet NaN, subject to the scanner limitation below. An empty tag, or a tag with no initial digits after the optional prefix, supplies zero payload bits. Trailing nonhexadecimal text does not produce an error. Payload and sign are representation-dependent. Excess high-order digits are discarded before exponent and quiet bits are imposed; distinct tags may produce the same value. The implementation does not set or clear errno.
Notes
Include <math.h>. The implementation allocates no storage. It scans the entire initial digit sequence even when only a fixed number of digits contributes to the result. The 80-bit implementation uses three 32-bit words; the 128-bit implementation uses four. When long double has the same precision as double, nanl is an alias of nan. Do not use NaN tags as a portable serialization format.
Bugs
The shared scanner uses signed left shifts. On targets with 32-bit int, shifting a hexadecimal digit of 8 through F into bit position 28 has undefined behavior. Such tags have no reliable source-level result. The big-endian scanner reverses nibble placement within each word relative to the little-endian scanner. The same tag need not preserve the same payload across targets.
See also
nearbyint()
Synopsis
double nearbyint( double x)
Function
Round x to an integral floating-point value according to the current rounding direction, without retaining newly raised floating-point exception flags when environment save and restore succeed.
Inputs
x - Double value to round.
Result
The value returned by rint(), in double precision. Signed zeros and infinities retain their sign; NaNs remain NaNs. The result is not a C integer conversion.
Notes
Include <math.h> and <fenv.h>. The wrapper saves the entire floating-point environment before rounding and restores it afterward. It does not disable enabled traps.
Bugs
The wrapper ignores errors from fegetenv() and fesetenv(). On targets where these operations are ineffective or unsupported, exception flags may not be preserved. A trap can prevent restoration. The delegated rint implementation has undefined signed-shift behavior for some small negative inputs.
See also
nearbyintf()
Synopsis
float nearbyintf( float x)
Function
Round x to an integral floating-point value according to the current rounding direction, without retaining newly raised floating-point exception flags when environment save and restore succeed.
Inputs
x - Float value to round.
Result
The value returned by rintf(), in float precision. Signed zeros and infinities retain their sign; NaNs remain NaNs. The result is not a C integer conversion.
Notes
Include <math.h> and <fenv.h>. The wrapper saves the entire floating-point environment before rounding and restores it afterward. It does not disable enabled traps.
Bugs
The wrapper ignores errors from fegetenv() and fesetenv(). On targets where these operations are ineffective or unsupported, exception flags may not be preserved. A trap can prevent restoration. The delegated rint implementation has undefined signed-shift behavior for some small negative inputs.
See also
nearbyintl()
Synopsis
long double nearbyintl( long double x)
Function
Round x to an integral floating-point value according to the current rounding direction, without retaining newly raised floating-point exception flags when environment save and restore succeed.
Inputs
x - Long double value to round.
Result
The value returned by rintl(), in long double precision. Signed zeros and infinities retain their sign; NaNs remain NaNs. The result is not a C integer conversion.
Notes
Include <math.h> and <fenv.h>. The wrapper saves the entire floating-point environment before rounding and restores it afterward. It does not disable enabled traps. Where long double equals double, nearbyintl() aliases nearbyint().
Bugs
The wrapper ignores errors from fegetenv() and fesetenv(). On targets where these operations are ineffective or unsupported, exception flags may not be preserved. A trap can prevent restoration. The separate rintl() implementation requires correctly set long double evaluation precision; equal-precision aliases inherit the rint() signed-shift defect.
See also
nextafterf()
Synopsis
float nextafterf( float x, float y)
Function
Return the adjacent float value in the direction of y.
Inputs
x - Starting value. y - Direction value, supplied as float.
Result
The adjacent value toward y, or y converted to float when x and y compare equal. Equal zeros return the sign of y. A zero starting value and nonzero direction select the smallest subnormal with the sign of y. If either argument is NaN, the result is NaN. Stepping from infinity toward a finite value returns the largest finite value with the same sign. See BUGS for outward steps at the finite limit.
Notes
Include <math.h>. Subnormal results and steps to zero can raise FE_UNDERFLOW and FE_INEXACT. Outward steps at the finite limit can raise FE_OVERFLOW and FE_INEXACT. Enabled traps may prevent return. This function does not set errno.
Bugs
An outward step from the largest positive or negative finite value can return that same finite value under directed rounding, instead of the corresponding infinity.
See also
nextafterl()
Synopsis
long double nextafterl( long double x, long double y)
Function
Return the adjacent long double value in the direction of y.
Inputs
x - Starting value. y - Value that determines the direction.
Result
If x and y compare equal, return y, including its zero sign. A zero starting value and nonzero direction select the smallest subnormal with the sign of y. If either argument is NaN, the result is NaN. An inward step from infinity returns the largest finite value with the same sign. See BUGS for outward steps at the finite limit.
Notes
Include <math.h>. This function has the same behavior as nexttowardl(). Subnormal results can raise FE_UNDERFLOW and FE_INEXACT. Outward steps at the finite limit can raise FE_OVERFLOW and FE_INEXACT. Enabled traps may prevent return. This function does not set errno.
Bugs
An outward step from the largest positive or negative finite value can return that same finite value under directed rounding, instead of the corresponding infinity. Where long double has greater precision than double, a step from the smallest subnormal to zero does not raise FE_UNDERFLOW or FE_INEXACT. Existing exception flags are not cleared.
See also
nexttowardf()
Synopsis
float nexttowardf( float x, long double y)
Function
Return the adjacent float value in the direction of y. The direction is determined using the full long double value of y, even when y would round to x if converted to float.
Inputs
x - Starting value. y - Direction value, supplied as long double.
Result
The adjacent value toward y, or y converted to float when x and y compare equal. Equal zeros return the sign of y. A zero starting value and nonzero direction select the smallest subnormal with the sign of y. If either argument is NaN, the result is NaN. Stepping from infinity toward a finite value returns the largest finite value with the same sign. See BUGS for outward steps at the finite limit.
Notes
Include <math.h>. Subnormal results and steps to zero can raise FE_UNDERFLOW and FE_INEXACT. Outward steps at the finite limit can raise FE_OVERFLOW and FE_INEXACT. Enabled traps may prevent return. This function does not set errno.
Bugs
An outward step from the largest positive or negative finite value can return that same finite value under directed rounding, instead of the corresponding infinity. Stepping from zero toward a negative value is affected by undefined C behavior in this implementation.
See also
nexttowardl()
Synopsis
long double nexttowardl( long double x, long double y)
Function
Return the adjacent long double value in the direction of y.
Inputs
x - Starting value. y - Value that determines the direction.
Result
If x and y compare equal, return y, including its zero sign. A zero starting value and nonzero direction select the smallest subnormal with the sign of y. If either argument is NaN, the result is NaN. An inward step from infinity returns the largest finite value with the same sign. See BUGS for outward steps at the finite limit.
Notes
Include <math.h>. This function has the same behavior as nextafterl(). Subnormal results can raise FE_UNDERFLOW and FE_INEXACT. Outward steps at the finite limit can raise FE_OVERFLOW and FE_INEXACT. Enabled traps may prevent return. This function does not set errno.
Bugs
An outward step from the largest positive or negative finite value can return that same finite value under directed rounding, instead of the corresponding infinity. Where long double has greater precision than double, a step from the smallest subnormal to zero does not raise FE_UNDERFLOW or FE_INEXACT. Existing exception flags are not cleared.
See also
on_exit()
Synopsis
int on_exit( void (*func)(int, void *), void *arg)
perror()
Synopsis
void perror( const char *string )
Function
looks up the language-dependent error message string affiliated with an error number and writes it, followed by a newline, to the standard error stream.
Inputs
string - the string to prepend the error message. If NULL only the error
message will be printed, otherwise the error message will be
separated from string by a colon.
pow()
Synopsis
double pow( double x, double y)
Function
Computes x raised to the power of y (x^y).
Inputs
x - the base. y - the exponent.
Result
Returns x raised to y. If the result overflows, sets errno to ERANGE. If x < 0 and y is not an integer, result is NaN and errno is set to EDOM.
Example
double r = pow(2.0, 3.0); // returns 8.0
Notes
Domain and range errors are handled per IEEE 754.
Bugs
Some edge cases may differ slightly from hardware FPU behavior.
powf()
Synopsis
float powf( float x, float y)
Function
Computes x raised to the power y.
Inputs
x - base value. y - exponent.
Result
x raised to the power y as a float.
Example
float r = powf(2.0f, 3.0f); // 8.0f
Notes
If x is negative and y is not an integer, the result is a domain error.
Bugs
May return NaN for invalid domains, like powf(-2.0f, 0.5f)
powl()
Synopsis
long double powl( long double x, long double y)
Function
Computes x raised to the power y.
Inputs
x - base value. y - exponent.
Result
Returns x^y.
Example
long double r = powl(2.0L, 3.0L); // returns 8.0L
Notes
Domain error if x < 0 and y is not an integer.
Bugs
None known.
printf()
Synopsis
int printf( const char * restrict format, ...)
Function
Formats a list of arguments and prints them to standard out.
The format string 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 Each conversion
specification is introduced by the character %. The arguments must
correspond properly (after type promotion) with the conversion
specifier. After the %, the following appear in sequence:
\begin{itemize}
\item Zero or more of the following flags:
\begin{description}
\item[#] specifying that the value should be converted to an
``alternate form''. For c, d, i, n, p, s, and u conversions, this
option has no effect. For o conversions, the precision of the
number is increased to force the first character of the output
string to a zero (except if a zero value is printed with an
explicit precision of zero). For x and X conversions, a non-zero
result has the string `0x' (or `0X' for X conversions) prepended to
it. For e, E, f, g, and G conversions, the result will always
contain a decimal point, even if no digits follow it (normally, a
decimal point appears in the results of those conversions only if a
digit follows). For g and G conversions, trailing zeros are not
removed from the result as they would otherwise be.
\item[0] specifying zero padding. For all conversions except n, the
converted value is padded on the left with zeros rather than
blanks. If a precision is given with a numeric conversion (d, i, o,
u, i, x, and X), the 0 flag is ignored.
\item[-] (a negative field width flag) indicates the converted
value is to be left adjusted on the field boundary. Except for n
conversions, the converted value is padded on the right with
blanks, rather than on the left with blanks or zeros. A -
overrides a 0 if both are given.
\item[ ] (a space) specifying that a blank should be left before a
positive number produced by a signed conversion (d, e, E, f, g, G,
or i). + specifying that a sign always be placed before a number
produced by a signed conversion. A + overrides a space if both are
used.
\item['] specifying that in a numerical argument the output is to
be grouped if the locale information indicates any. Note that many
versions of gcc cannot parse this option and will issue a warning.
\end{description}
\item An optional decimal digit string specifying a minimum field
width. If the converted value has fewer characters than the field
width, it will be padded with spaces on the left (or right, if the
left-adjustment flag has been given) to fill out the field width.
\item An optional precision, in the form of a period (`.') followed
by an optional digit string. If the digit string is omitted, the
precision is taken as zero. This gives the minimum number of digits
to appear for d, i, o, u, x, and X conversions, the number of
digits to appear after the decimal-point for e, E, and f
conversions, the maximum number of significant digits for g and G
conversions, or the maximum number of characters to be printed from
a string for s conversions.
\item The optional character h, specifying that a following d, i,
o, u, x, or X conversion corresponds to a short int or unsigned
short int argument, or that a following n conversion corresponds to
a pointer to a short int argument.
\item The optional character l (ell) specifying that a following d,
i, o, u, x, or X conversion applies to a pointer to a long int or
unsigned long int argument, or that a following n conversion
corresponds to a pointer to a long int argument. Linux provides a
non ANSI compliant use of two l flags as a synonym to q or L. Thus
ll can be used in combination with float conversions. This usage
is, however, strongly discouraged.
\item The character L specifying that a following e, E,
f, g, or G conversion corresponds to a long double
argument, or a following d, i, o, u, x, or X conversion corresponds to a long long argument. Note
that long long is not specified in ANSI C and
therefore not portable to all architectures.
\item The optional character q. This is equivalent to L. See the
STANDARDS and BUGS sections for comments on the use of ll, L, and
q.
\item A Z character specifying that the following integer (d, i, o,
u, i, x, and X), conversion corresponds to a size_t argument.
\item A character that specifies the type of conversion to be
applied.
A field width or precision, or both, may be indicated by an
asterisk `*' instead of a digit string. In this case, an int
argument supplies the field width or precision. A negative field
width is treated as a left adjustment flag followed by a positive
field width; a negative precision is treated as though it were
missing.
The conversion specifiers and their meanings are:
\begin{description}
\item[diouxX] The int (or appropriate variant) argument is
converted to signed decimal (d and i), unsigned octal (o, unsigned
decimal (u, or unsigned hexadecimal (x and X) notation. The letters
abcdef are used for x conversions; the letters ABCDEF are used for
X conversions. The precision, if any, gives the minimum number of
digits that must appear; if the converted value requires fewer
digits, it is padded on the left with zeros.
\item[eE] The double argument is rounded and converted in the style
[<->]d.dddedd where there is one digit 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, no decimal-point character appears. An E
conversion uses the letter E (rather than e) to introduce the
exponent. The exponent always contains at least two digits; if the
value is zero, the exponent is 00.
\item[f] The double argument is rounded and 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 explicitly zero, no decimal-point character
appears. If a decimal point appears, at least one digit appears
before it.
\item[g] The double argument is converted in style f or e (or E for
G conversions). The precision specifies the number of significant
digits. If the precision is missing, 6 digits are given; if the
precision is zero, it is treated as 1. Style e is used if the
exponent from its conversion is less than -4 or greater than or
equal to the precision. Trailing zeros are removed from the
fractional part of the result; a decimal point appears only if it
is followed by at least one digit.
\item[c] The int argument is converted to an unsigned char, and the
resulting character is written.
\item[s] The ``char *'' argument is expected to be a pointer to an
array of character type (pointer to a string). Characters from the
array are written up to (but not including) a terminating NUL
character; if a precision is specified, no more than the number
specified are written. If a precision is given, no null character
need be present; if the precision is not specified, or is greater
than the size of the array, the array must contain a terminating
NUL character.
\item[p] The ``void *'' pointer argument is printed in hexadecimal
(as if by %#x or %#lx).
\item[n] The number of characters written so far is stored into the
integer indicated by the ``int *'' (or variant) pointer argument.
No argument is converted.
\item[%] A `%' is written. No argument is converted. The complete
conversion specification is `%%'.
\end{description}
\end{itemize}
In no case does a non-existent or small field width cause
truncation of a field; if the result of a conversion is wider than
the field width, the field is expanded to contain the conversion
result.
Inputs
format - Format string as described above ... - Arguments for the format string
Result
The number of characters written to stdout or EOF on error.
Example
To print a date and time in the form `Sunday, July 3,
10:02', where weekday and month are pointers to strings:
#include <stdio.h>
fprintf (stdout, "%s, %s %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
To print to five decimal places:
#include <math.h>
#include <stdio.h>
fprintf (stdout, "pi = %.5f\n", 4 * atan(1.0));
To allocate a 128 byte string and print into it:
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *newfmt(const char *fmt, ...)
{
char *p;
va_list ap;
if ((p = malloc(128)) == NULL)
return (NULL);
va_start(ap, fmt);
(void) vsnprintf(p, 128, fmt, ap);
va_end(ap);
return (p);
}
Bugs
All functions are fully ANSI C3.159-1989 conformant, but provide the additional flags q, Z and ' as well as an additional behavior of the L and l flags. The latter may be considered to be a bug, as it changes the behavior of flags defined in ANSI C3.159-1989. The effect of padding the %p format with zeros (either by the 0 flag or by specifying a precision), and the benign effect (i.e., none) of the # flag on %n and %p conversions, as well as nonsensical combinations such as are not standard; such combinations should be avoided. Some combinations of flags defined by ANSI C are not making sense in ANSI C (e.g. %Ld). While they may have a well-defined behavior on Linux, this need not to be so on other architectures. Therefore it usually is better to use flags that are not defined by ANSI C at all, i.e. use q instead of L in combination with diouxX conversions or ll. The usage of q is not the same as on BSD 4.4, as it may be used in float conversions equivalently to L. Because sprintf and vsprintf assume an infinitely long string, callers must be careful not to overflow the actual space; this is often impossible to assure.
putc()
Synopsis
int putc( int c, FILE * stream)
Function
Write one character to the specified stream.
Inputs
c - The character to output stream - The character is written to this stream
Result
The character written or EOF on error.
See also
puts()
Synopsis
int puts( const char * str)
Function
Print a string to stdout. A newline ('\n') is emmitted after the
string.
Inputs
str - Print this string
Result
> 0 on success and EOF on error. On error, the reason is put in errno.
Example
#include <errno.h>
if (puts ("Hello World.") != EOF)
fprintf (stderr, "Success");
else
fprintf (stderr, "Failure: errno=%d", errno);
putwc()
Synopsis
wint_t putwc( wchar_t wc, FILE *stream)
Function
Write a wide character by calling fputwc(). The current conversion routine encodes the value as UTF-8 and writes the bytes in order.
Inputs
wc - Unicode scalar value to write. The supported domain excludes
surrogate values and values above U+10FFFF. See BUGS before writing
non-ASCII values with the current implementation.
stream - Non-NULL open output stream. Remains owned by the caller.
Result
The character value on success, or WEOF on a reported error. A stream not open for writing sets errno to EACCES and its error indicator. A rejected conversion sets EILSEQ and the error indicator. A failed byte write sets the error indicator and maps the DOS error to errno. Allocation failure is not safely reported; see BUGS.
Notes
Include <wchar.h>. This wrapper evaluates each argument once and does not close the stream. L'\0' writes one zero byte. The converter is stateless and ignores the stream's conversion-state object. A write error may occur after earlier bytes have been written. There is no rollback, so the stream can contain a partial UTF-8 sequence. A successful call does not establish that buffered output has reached persistent storage. Append mode attempts to seek to the end before writing, but the seek result is not checked. Call from DOS process context with the C runtime active. Allocation and file-handler writes can block; no timeout or cancellation is supplied. Coordinate access to both the stream and locale state. The wrapper adds no lock spanning conversion and all byte writes.
Bugs
fputwc() allocates the current locale's maximum multibyte size, but wcrtomb() always emits UTF-8. The default C locale supplies one byte; non-ASCII conversion can therefore exceed the requested buffer size. This is an implementation defect, not a supported encoding mode. The allocation result is unchecked. If allocation fails, wcrtomb() treats NULL as a length query; the subsequent write loop dereferences that NULL pointer for an otherwise valid character. There is no safe ENOMEM return path in this implementation. Stream orientation is neither established nor checked. Conversion of signed negative wchar_t values is not consistently rejected by the underlying converter; pass only values in the stated scalar domain.
putwchar()
Synopsis
t_t putwchar( wchar_t wc) FUNCTION The putwchar() function is the wide-character equivalent of putchar(). It writes the wide character wc to the standard output stream using the current locale to convert it to its multibyte representation.
Inputs
wc - The wide character to be written to stdout.
Result
Returns the wide character written as a wint_t value on success. Returns WEOF if an error occurs.
Example
putwchar(L'?');
Notes
The output is affected by the current locale, particularly LC_CTYPE, which governs the multibyte encoding used during output. Internally, putwchar() is equivalent to fputwc(wc, stdout).
Bugs
If stdout is not a valid output stream or the locale does not support the character, the function may fail or produce unexpected results.
See also
qsort()
Synopsis
void qsort( void * a, size_t n, size_t es, int (* cmp)(const void *, const void *))
Function
Sort the array a. It contains n elements of the size es. Elements are compares using the function cmp().
Inputs
a - The array to sort
n - The number of elements in the array
es - The size of a single element in the array
cmp - The function which is called when two elements must be
compared. The function gets the addresses of two elements
of the array and must return 0 is both are equal, < 0 if
the first element is less than the second and > 0 otherwise.
Result
None.
Example
// Use this function to compare to stringpointers
int cmp_strptr (const char ** sptr1, const char ** sptr2)
{
return strcmp (*sptr1, *sptr2);
}
// Sort an array of strings
char ** strings;
// fill the array
strings = malloc (sizeof (char *)*4);
strings[0] = strdup ("h");
strings[1] = strdup ("a");
strings[2] = strdup ("f");
strings[3] = strdup ("d");
// Sort it
qsort (strings, sizeof (char *), 4, (void *)cmp_strptr);
qsort_r()
Synopsis
void qsort_r( void * a, size_t n, size_t es, int (* cmp)(const void *, const void *, void *), void * arg)
Function
Sort the array a, which contains n elements of size es, exactly like qsort(), except that the comparison function cmp() takes a third argument. The pointer arg is passed unchanged as that third argument on every call, letting the comparison capture context without using global variables (so it is reentrant and thread safe).
Inputs
a - The array to sort
n - The number of elements in the array
es - The size of a single element in the array
cmp - The comparison function. It is called with the addresses of two
elements and the arg pointer, and must return 0 if both are
equal, < 0 if the first element is less than the second and
> 0 otherwise.
arg - An arbitrary pointer passed through to every cmp() call.
Result
None.
Example
// Sort integers relative to a pivot supplied via arg.
int cmp_rel (const void *a, const void *b, void *arg)
{
int pivot = *(int *)arg;
int da = abs(*(const int *)a - pivot);
int db = abs(*(const int *)b - pivot);
return da - db;
}
int pivot = 5;
qsort_r (array, count, sizeof(int), cmp_rel, &pivot);
Notes
This implementation uses the GNU/glibc argument order: the context pointer is the last parameter of qsort_r() and the last parameter of the comparison function (compar(a, b, arg)).
quick_exit()
Synopsis
void quick_exit( int status)
Function
Cause normal-ish program termination: the functions registered with at_quick_exit() are called (in reverse order of registration), then control is handed to _Exit(status).
Inputs
status - the exit status reported to the host.
Result
This function does not return.
Notes
Unlike exit(), quick_exit() does not call atexit() handlers and does not flush or close C streams (it terminates via _Exit()).
See also
raise()
Synopsis
int raise( int signum)
Function
Calls the handler of a signal
Inputs
Signal handler to be called.
Result
0: OK -1: error calling handler, errno will be set.
Notes
The behavior of raise() follows the BSD semantics. For each signal the system keeps track of a signal handler is already being called. If not, the signal handler is called; when yes this will logged and the handler will be recalled when the first handler returns. If the a new handler is registered that one will be used then. When sigaction() has been used to register a handler the following flags are honored: SA_SIGINFO - call sa_sigaction(signum, NULL, NULL) instead of sa_handler SA_RESETHAND - reset to SIG_DFL after one delivery SA_NODEFER - don't block the signal during its own handler
See also
rand()
Synopsis
int rand( void)
Function
A random number generator.
Inputs
None.
Result
A pseudo-random integer between 0 and RAND_MAX.
See also
realloc()
Synopsis
void * realloc( void * oldmem, size_t size)
Function
Change the size of an allocated part of memory. The memory must have been allocated by malloc() or calloc(). If you reduce the size, the old contents will be lost. If you enlarge the size, the new contents will be undefined.
Inputs
oldmem - What you got from malloc() or calloc(). size - The new size.
Result
A pointer to the allocated memory or NULL. If you don't need the memory anymore, you can pass this pointer to free(). If you don't, the memory will be freed for you when the application exits.
Notes
If you get NULL, the memory at oldmem will not have been freed and can still be used.
realloc_nocopy()
Synopsis
void * realloc_nocopy( void * oldmem, size_t size)
Function
Change the size of an allocated part of memory. The memory must have been allocated by malloc(), calloc(), realloc() or realloc_nocopy(). The reallocated buffer, unlike with realloc(), is not guaranteed to hold a copy of the old one.
Inputs
oldmem - What you got from malloc(), calloc(), realloc() or realloc_nocopy().
If NULL, the function will behave exactly like malloc().
size - The new size. If 0, the buffer will be freed.
Result
A pointer to the allocated memory or NULL. If you don't need the memory anymore, you can pass this pointer to free(). If you don't, the memory will be freed for you when the application exits.
Notes
If you get NULL, the memory at oldmem will not have been freed and can still be used. This function is AROS specific.
remainder()
Synopsis
double remainder( double x, double y)
Function
Returns the IEEE 754-style remainder of x with respect to y.
Inputs
x - dividend. y - divisor.
Result
Remainder r such that r = x - n*y, where n is the integer nearest to x/y.
Example
double r = remainder(5.3, 2.0); // r = 1.3
Notes
If the result is exactly halfway between two integers, the even integer is used.
Bugs
Returns NaN if y is zero or x or y is NaN.
remainderf()
Synopsis
float remainderf( float x, float y)
Function
Computes IEEE remainder of x/y.
Inputs
x - dividend y - divisor
Result
Remainder with magnitude less than y/2.
Example
float r = remainderf(5.3f, 2.0f); // 1.3f
Notes
Different from fmodf(); may be negative.
Bugs
Returns NaN if y == 0.
See also
remainderl()
Synopsis
long double remainderl( long double x, long double y)
Function
Compute x - n * y, where n is the integer nearest to the exact quotient x / y. Ties select the even integer, independently of the current rounding direction.
Inputs
x - Dividend. y - Divisor.
Result
For finite operands and nonzero y, return a remainder with magnitude at most half of |y|. A zero result has the sign of x. With finite x and infinite y, return x. If x is infinite, y is zero, or either argument is NaN, return NaN.
Notes
Include <math.h>. A zero divisor or infinite dividend raises FE_INVALID unless a quiet NaN operand suppresses the exception. Enabled traps may prevent return. This function does not set errno.
Bugs
Where long double has greater precision than double, results are not reliable when the nearest integer quotient has magnitude 2^31 or greater.
See also
remove()
Synopsis
int remove( const char * pathname)
Function
Deletes a file or directory.
Inputs
pathname - Complete path to the file or directory.
Result
0 on success and -1 on error. In case of an error, errno is set.
remquo()
Synopsis
double remquo( double x, double y, int *quo)
Function
Computes the remainder of dividing x by y and returns part of the quotient via `quo`.
Inputs
x - the dividend. y - the divisor. quo - pointer to an int to store part of the quotient.
Result
Returns the remainder and stores low bits of quotient in *quo. If `quo` is NULL or y is zero, returns NaN and sets errno to EDOM.
Example
int q; double r = remquo(7.0, 2.0, &q); // r = 1.0, q = 3
Notes
The remainder has the same sign as x and magnitude less than y.
Bugs
Some platforms may not produce identical quotients for equal inputs.
See also
remquof()
Synopsis
float remquof( float x, float y, int *quo)
Function
Compute the floating-point remainder and low quotient bits. For finite x and nonzero finite y, the remainder is x - n * y, where n is the integer nearest to x / y; ties select the even integer. The current rounding direction does not select n.
Inputs
x - Dividend.
y - Divisor.
quo - Pointer to a writable int that receives the low 31 bits
of the magnitude of n, with the sign of x / y. If those
bits are all zero, the stored value is zero.
Result
Return the remainder, whose magnitude is at most half of |y|. A zero result has the sign of x. With finite x and infinite y, return x and store zero in *quo. If x is infinite, y is zero, or either argument is NaN, return NaN and leave *quo unchanged.
Notes
Include <math.h>. A zero divisor or infinite dividend raises FE_INVALID unless a quiet NaN operand suppresses the exception. Enabled traps may prevent return. This function does not set errno.
Bugs
Results are not reliable when finite operands satisfy |x| > |y| and y is subnormal.
See also
remquol()
Synopsis
g double remquol( long double x, long double y, int *quo)
Function
Computes the remainder of dividing x by y and returns part of the quotient via `quo`.
Inputs
x - the dividend. y - the divisor. quo - pointer to an int to store part of the quotient.
Result
Returns the remainder and stores low bits of quotient in *quo. If `quo` is NULL or y is zero, returns NaN and sets errno to EDOM.
Example
int q; double r = remquo(7.0, 2.0, &q); // r = 1.0, q = 3
Notes
The remainder has the same sign as x and magnitude less than y.
Bugs
Some platforms may not produce identical quotients for equal inputs.
See also
rename()
Synopsis
int rename( const char * oldpath, const char * newpath)
Function
Renames a file or directory.
Inputs
oldpath - Complete path to existing file or directory. newpath - Complete path to the new file or directory.
Result
0 on success and -1 on error. In case of an error, errno is set.
rewind()
Synopsis
void rewind( FILE * stream)
Function
Change the current position in a stream to the beginning. It also clears the error indication of the stream.
Inputs
stream - Modify this stream
rintf()
Synopsis
float rintf( float x)
Function
Round x to an integral floating-point value using the current rounding direction.
Inputs
x - Float value to round.
Result
The rounded float value. Nearest ties select the even integer; other modes follow the current rounding direction. Signed zeros and infinities keep their sign; NaNs remain NaNs.
Notes
Include <math.h> and <fenv.h>. Unlike nearbyintf(), rounding may raise FE_INEXACT. Unlike roundf(), ties are not always rounded away from zero.
Bugs
The small negative-input path shifts a signed integer into its sign bit, which is undefined behavior in C. Results for that path may depend on the compiler.
See also
rintl()
Synopsis
long double rintl( long double x)
Function
Round x to an integral floating-point value using the current rounding direction.
Inputs
x - Long double value to round.
Result
The rounded long double value. Nearest ties select the even integer; other modes follow the current rounding direction. Signed zeros and infinities keep their sign; NaNs remain NaNs.
Notes
Include <math.h> and <fenv.h>. Unlike nearbyintl(), rounding may raise FE_INEXACT. Unlike roundl(), ties are not always rounded away from zero.
Bugs
The separate implementation requires intermediate arithmetic evaluated in long double precision. A narrower x87 precision setting can give incorrect results; wider evaluation can double-round. Equal-precision aliases inherit the rint() signed-shift defect for small negative inputs.
See also
round()
Synopsis
double round( double x)
Function
Round x to the nearest integral floating-point value, with halfway cases rounded away from zero.
Inputs
x - Double value to round.
Result
For finite x, an integral-valued double result. For example, 0.5 rounds to 1 and -0.5 rounds to -1. The sign of zero is preserved; infinities remain infinite and NaNs remain NaNs.
Notes
Include <math.h>. Rounding is independent of the current rounding direction; unlike rint(), halfway values round away from zero. Exception flags may change.
roundf()
Synopsis
float roundf( float x)
Function
Round x to the nearest integral floating-point value, with halfway cases rounded away from zero.
Inputs
x - Float value to round.
Result
For finite x, an integral-valued float result. For example, 0.5 rounds to 1 and -0.5 rounds to -1. The sign of zero is preserved; infinities remain infinite and NaNs remain NaNs.
Notes
Include <math.h>. Rounding is independent of the current rounding direction; unlike rintf(), halfway values round away from zero. Exception flags may change.
See also
roundl()
Synopsis
long double roundl( long double x)
Function
Round x to the nearest integral floating-point value, with halfway cases rounded away from zero.
Inputs
x - Long double value to round.
Result
For finite x, an integral-valued long double result. For example, 0.5 rounds to 1 and -0.5 rounds to -1. The sign of zero is preserved; infinities remain infinite and NaNs remain NaNs.
Notes
Include <math.h>. Rounding is independent of the current rounding direction; unlike rintl(), halfway values round away from zero. Exception flags may change. On equal-precision long double targets, roundl() aliases round().
See also
scalb()
Synopsis
double scalb( double x, double fn)
Function
Scale x by 2 raised to the integral value fn.
Inputs
x - Double value to scale.
fn - Exponent, supplied as a double. Finite values must be
integral. See BUGS for negative fractional exponents.
Result
The scaled value in double. Exact representable results require no rounding; inexact subnormal results and range limits depend on the current rounding direction. For finite integral fn, signed zero and infinity retain the sign of x. A NaN argument produces a NaN. A finite nonintegral fn produces a NaN, subject to BUGS. For fn equal to positive infinity, returns x * infinity. For fn equal to negative infinity, returns x / infinity. Thus zero with positive infinity, or infinite x with negative infinity, produces a NaN.
Notes
Include <math.h>. Prefer scalbn() for an int exponent or scalbln() for a long exponent. The function does not assign errno. Invalid arguments and range errors can raise floating-point exceptions; the integrality check can also raise inexact. Enabled traps may prevent return.
Bugs
For -1 < fn < 0, the integrality check invokes undefined C behavior. Do not rely on a NaN result for these inputs.
See also
scalbf()
Synopsis
float scalbf( float x, float fn)
Function
Scale x by 2 raised to the integral value fn.
Inputs
x - Float value to scale.
fn - Exponent, supplied as a float. Finite values must be
integral. See BUGS for negative fractional exponents.
Result
The scaled value in float. Exact representable results require no rounding; inexact subnormal results and range limits depend on the current rounding direction. For finite integral fn, signed zero and infinity retain the sign of x. A NaN argument produces a NaN. A finite nonintegral fn produces a NaN, subject to BUGS. For fn equal to positive infinity, returns x * infinity. For fn equal to negative infinity, returns x / infinity. Thus zero with positive infinity, or infinite x with negative infinity, produces a NaN.
Notes
Include <math.h>. Prefer scalbnf() for an int exponent or scalblnf() for a long exponent. The function does not assign errno. Invalid arguments and range errors can raise floating-point exceptions; the integrality check can also raise inexact. Enabled traps may prevent return.
Bugs
For -1 < fn < 0, the integrality check invokes undefined C behavior. Do not rely on a NaN result for these inputs.
See also
scalbln()
Synopsis
double scalbln( double x, long n)
Function
Scale x by an integral power of two. The exponent is clamped to [-65536, 65536] before calling scalbn().
Inputs
x - Double value to scale.
n - Base-two exponent. Values outside the clamp interval are
treated as the nearest endpoint.
Result
The scaled double value. An exact result is returned without rounding; otherwise the current rounding mode applies. Signed zero retains its sign. Infinities and NaNs propagate.
Notes
Include <math.h>. Overflow and underflow may raise floating-point exceptions. Enabled traps may prevent the function from returning.
scalblnf()
Synopsis
float scalblnf( float x, long n)
Function
Scale x by an integral power of two. The exponent is clamped to [-65536, 65536] before calling scalbnf().
Inputs
x - Float value to scale.
n - Base-two exponent. Values outside the clamp interval are
treated as the nearest endpoint.
Result
The scaled float value. An exact result is returned without rounding; otherwise the current rounding mode applies. Signed zero retains its sign. Infinities and NaNs propagate.
Notes
Include <math.h>. Overflow and underflow may raise floating-point exceptions. Enabled traps may prevent the function from returning.
See also
scalblnl()
Synopsis
long double scalblnl( long double x, long n)
Function
Scale x by an integral power of two. The exponent is clamped to [-65536, 65536] before calling scalbnl().
Inputs
x - Long double value to scale.
n - Base-two exponent. Values outside the clamp interval are
treated as the nearest endpoint.
Result
The scaled long double value, subject to the current rounding mode and the limitation described in BUGS. Signed zero retains its sign. Infinities and NaNs propagate.
Notes
Include <math.h>. Overflow and underflow may raise floating-point exceptions. Enabled traps may prevent the function from returning.
Bugs
When long double has a separate extended-precision implementation, scalbnl() narrows a long double underflow constant through the double-precision copysign() function. Under downward rounding, a negative input can produce negative zero when a negative subnormal result is required. The equal-precision double alias does not use this implementation path.
See also
scalbnf()
Synopsis
float scalbnf( float x, int n)
Function
Scale x by an integral power of two.
Inputs
x - Value to scale. n - Base-two exponent.
Result
The scaled float value. Inexact results are rounded according to the current floating-point rounding direction. Signed zero and infinity retain their signs; NaN produces NaN.
Notes
Include <math.h>. Overflow and underflow may raise floating-point exceptions. This implementation does not set errno. ldexpf() is an alias of scalbnf().
Bugs
The implementation adds n to a signed exponent without checking for overflow. For x = 1 and n = INT_MAX, this causes undefined signed integer arithmetic before the range check.
See also
scanf()
Synopsis
int scanf( const char * restrict format, ...)
Result
The number of converted parameters
setbuf()
Synopsis
void setbuf( FILE * restrict stream, char * restrict buf)
Function
Sets a buffer associated with a stream.
Inputs
stream: stream to set a buffer for.
buf: if it points to an array of at least size BUFSIZ it will be used
as a buffer with mode _IOFBF. If it is NULL mode will be set to
_IONBF
Result
-
See also
setjmp()
Synopsis
int setjmp( jmp_buf env)
Function
Save the calling environment for a later nonlocal return with longjmp().
Inputs
env - Writable jmp_buf object. Keep it intact and alive until no further
jump will use it. A new save replaces the previous environment.
Result
Zero on the initial return. After longjmp(), its nonzero val argument, or 1 when val was zero.
Notes
Include <setjmp.h> and use jmp_buf with its declared alignment. The saved register and stack layout depends on the target CPU. Use setjmp() as a complete statement, a complete if/while condition, or in such a condition with unary ! or comparison against an integer constant expression. Do not assign its result to a variable or embed it in another expression. Only jump back while the saving function is still active in the same thread. Do not leave and then re-enter the scope of a variably modified object this way. Changed non-volatile automatic locals in the saving function have indeterminate values after the jump. This is not a snapshot of memory, files or acquired resources. Floating- point state saved by the CPU implementation varies; do not use this interface to save or restore a floating-point environment. No signal mask is saved.
See also
longjmp() posixc/sigsetjmp()
setlocale()
Synopsis
char *setlocale( int category, const char *locale)
Inputs
category - category as defined in locale.h locale - string representing the desired locale (see notes)
Result
The lconv struct
Notes
stdc.library supports "C" (and if the compiler has been compiled with __WCHAR_MAX__ > 255, "UTF8") locale(s). Currently accepted values for locale are "C", and "C.UTF-8".
See also
setvbuf()
Synopsis
int setvbuf( FILE *stream, char *buf, int mode, size_t size)
Function
Sets the buffer and the mode associated with a stream.
Inputs
stream: stream to set buffer on
buf: the buffer to be associated, when NULL a buffer will be allocated
and freed on close or new setvbuf. Should be longword aligned.
mode: mode for buffering
- _IOFBF: fully buffered
- _IOLBF: line buffered
- _IONBF: Not buffered
size: size of the buffer (needs to be at least 208).
Result
0 on success, EOF on error. errno indicated error. Function fails when size < 208 and buf != NULL.
signal()
Synopsis
__sighandler_t *signal( int signum, __sighandler_t *handler)
Function
Set signal handler for a signal.
Inputs
signum - the signal number to register a handler for
handler - the signal handler; can be SIG_IGN, SIG_DFL or a function
pointer that will handle the signal
Result
The old handler that was replaced by the new handler.
See also
significandf()
Synopsis
float significandf( float x)
Function
Return the signed binary significand of x.
Inputs
x - Float value to normalize. See BUGS for subnormal inputs.
Result
For finite nonzero x, the intended result is x scaled by 2 raised to -ilogbf(x), with magnitude at least 1 and less than 2. Normal inputs produce this result exactly. Signed zero and infinity retain their sign. NaN produces a NaN.
Notes
Include <math.h>. Unlike frexpf(), this function returns a significand with magnitude in [1, 2) and does not return an exponent. For example, 12.0f yields 1.5f and -0.5f yields -1.0f. The function does not assign errno. Signaling-NaN handling and exception delivery depend on the target.
Bugs
Subnormal inputs invoke undefined C behavior during exponent extraction. Their normalized result is not guaranteed.
sin()
Synopsis
double sin( double x)
Function
Computes the sine of x (x in radians).
Inputs
x - input angle in radians.
Result
Returns sin(x).
Example
double val = sin(3.14159 / 2); // approximately 1.0
Notes
Uses range reduction and polynomial approximation internally.
Bugs
None known.
sincos()
Synopsis
void sincos( double x, double *sn, double *cs)
Function
Compute the sine and cosine of x.
Inputs
x - Angle in radians. sn - Pointer to a writable double for the sine. cs - Pointer to a separate writable double for the cosine.
Result
Store sin(x) in *sn and cos(x) in *cs. No value is returned. For positive or negative zero, store x in *sn and 1 in *cs. For infinity or NaN, both outputs are NaN.
Notes
Include <math.h>. An infinite argument raises FE_INVALID. Enabled floating-point traps may prevent completion.
Bugs
Argument reduction assumes round-to-nearest. Other rounding modes can produce inaccurate results.
sincosf()
Synopsis
void sincosf( float x, float *sn, float *cs)
Function
Compute the sine and cosine of x.
Inputs
x - Angle in radians. sn - Pointer to a writable float for the sine. cs - Pointer to a separate writable float for the cosine.
Result
Store sin(x) in *sn and cos(x) in *cs. No value is returned. For positive or negative zero, store x in *sn and 1 in *cs. For infinity or NaN, both outputs are NaN.
Notes
Include <math.h>. An infinite argument raises FE_INVALID. Enabled floating-point traps may prevent completion.
Bugs
Argument reduction assumes round-to-nearest. Other rounding modes can produce inaccurate results.
sincosl()
Synopsis
void sincosl( long double x, long double *sn, long double *cs)
Function
Compute the sine and cosine of x.
Inputs
x - Angle in radians. sn - Pointer to a writable long double for the sine. cs - Pointer to a separate writable long double for the cosine.
Result
Store sin(x) in *sn and cos(x) in *cs. No value is returned. For positive or negative zero, store x in *sn and 1 in *cs. For infinity or NaN, both outputs are NaN.
Notes
Include <math.h>. An infinite argument raises FE_INVALID. Enabled floating-point traps may prevent completion.
Bugs
Argument reduction assumes round-to-nearest. Other rounding modes can produce inaccurate results. With a 113-bit long-double significand, calls that require argument reduction may leave one output unwritten or negate its previous value instead of producing the requested result.
sinf()
Synopsis
float sinf( float x)
Function
Computes the sine of x (x in radians).
Inputs
x - input angle in radians.
Result
The sine of x.
Example
float val = sinf(3.14159f / 2); // val approx 1.0f
Notes
Domain: all real numbers.
Bugs
None known.
sinh()
Synopsis
double sinh( double x)
Function
Computes the hyperbolic sine of x.
Inputs
x - input value.
Result
Returns sinh(x) = (e^x - e^{-x}) / 2.
Example
double val = sinh(1.0);
Notes
Uses exponentials internally for calculation.
Bugs
None known.
sinhf()
Synopsis
float sinhf( float x)
Function
Computes the hyperbolic sine of x.
Inputs
x - input float
Result
Returns sinh(x).
Example
float r = sinhf(1.0f); // 1.175201
Notes
Uses exponential functions internally.
Bugs
None known.
sinhl()
Synopsis
long double sinhl( long double x)
Function
Computes the hyperbolic sine of x.
Inputs
x - input value.
Result
Returns sinh(x) = (e^x - e^{-x}) / 2.
Example
double val = sinh(1.0);
Notes
Uses exponentials internally for calculation.
Bugs
None known.
sinl()
Synopsis
long double sinl( long double x)
Function
Computes the sine of x (x in radians).
Inputs
x - input angle in radians.
Result
Returns sin(x).
Example
double val = sin(3.14159 / 2); // approximately 1.0
Notes
Uses range reduction and polynomial approximation internally.
Bugs
None known.
snprintf()
Synopsis
int snprintf( char * str, size_t n, const char * format, ...)
Function
C99 says:The snprintf function is equivalent to fprintf, except that the output is written into an array (specified by argument s) rather than to a stream. If n is zero, nothing is written, and s may be a null pointer. Otherwise, output characters beyond the n-1st 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. If copying takes place between objects that overlap, the behavior is undefined.
Inputs
str - The formatted string is written into this variable. You
must make sure that it is large enough to contain the
result.
n - At most n characters are written into the string. This
includes the final 0.
format - Format string as described above
... - Arguments for the format string
Result
The snprintf function 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.
sprintf()
Synopsis
int sprintf( char * str, const char * format, ...)
Function
Formats a list of arguments and writes them into the string str.
Inputs
str - The formatted string is written into this variable. You
must make sure that it is large enough to contain the
result.
format - Format string as described above
... - Arguments for the format string
Result
The number of characters written into the string.
Notes
No checks are made that str is large enough for the result.
sqrt()
Synopsis
double sqrt( double x)
Function
Computes the square root of x.
Inputs
x - input value (must be non-negative).
Result
Returns vx. Returns NaN and sets errno to EDOM if x < 0.
Example
double val = sqrt(4.0); // returns 2.0
Notes
Uses IEEE 754 semantics.
Bugs
None known.
sqrtf()
Synopsis
float sqrtf( float x)
Function
Computes square root of x.
Inputs
x - input float (= 0)
Result
Square root of x.
Example
float r = sqrtf(4.0f); // 2.0f
Notes
Returns NaN if x < 0.
Bugs
None known.
sqrtl()
Synopsis
long double sqrtl( long double x)
Function
Computes the square root of x with extended precision.
Inputs
x - input value (must be non-negative).
Result
Returns vx as a long double. Returns NaN and sets errno to EDOM if x < 0.
Example
long double val = sqrtl(4.0L); // returns 2.0L
Notes
Provides higher precision than sqrt().
Bugs
None known.
srand()
Synopsis
void srand( unsigned int seed)
Function
Set the starting value for the random number generator rand() If a seed value is set to a value the same stream of pseudo-random numbers will be generated by rand() for the same seed value.
Inputs
seed - New start value
Result
None.
Notes
One seed value per stdc.library is kept which normally corresponds with per task.
See also
sscanf()
Synopsis
int sscanf( const char *str, const char *format, ...)
Function
Scan the specified string and convert it into the arguments as specified by format.
Inputs
str - The routine examines this string. format - Format string. See scanf() for a description ... - Arguments for the result
Result
The number of converted parameters.
stccpy()
Synopsis
size_t stccpy( char * dest, const char * src, size_t n)
Function
Copy a string. Works like an assignment "dest=src;". At most n characters are copied.
Inputs
dest - The string is copied into this variable. Make sure it is
large enough.
src - This is the new contents of dest.
n - How many characters to copy at most. If the string src is
smaller than that, only strlen(str)+1 bytes are copied.
Result
The number of copied characters.
Notes
No check is made that dest is large enough for src. SAS/C specific.
See also
stcd_l()
Synopsis
int stcd_l( const char * in, long * lvalue)
Function
Convert decimal string to a long integer
Inputs
in - The decimal string to be converted lvalue - Pointer to long where the result is saved
Result
length of characters converted. >= 1 means success. 0 means failure.
Notes
SAS/C specific
stch_l()
Synopsis
int stch_l( const char * in, long * lvalue)
Function
Convert hexadecimal string to a long integer
Inputs
in - The hexadecimal string to be converted lvalue - Pointer to long where the result is saved
Result
Number of characters converted
Notes
SAS/C specific
stcl_d()
Synopsis
int stcl_d( char * out, long lvalue)
Function
Convert an long integer to a decimal string
Inputs
out - Result will be put into this string uivalue - the value to convert
Result
The number of characters written into the string
Notes
SAS/C specific
stcl_h()
Synopsis
int stcl_h( char * out, long lvalue)
Function
Convert an long integer to a hex string
Inputs
out - Result will be put into this string uivalue - the value to convert
Result
The number of characters written into the string
Notes
SAS/C specific
stcl_o()
Synopsis
int stcl_o( char * out, long lvalue)
Function
Convert an long integer to an octal string
Inputs
out - Result will be put into this string uivalue - the value to convert
Result
The number of characters written into the string
Notes
SAS/C specific
stco_l()
Synopsis
int stco_l( const char * in, long * lvalue)
Function
Convert octal string to a long integer
Inputs
in - The octal string to be converted lvalue - Pointer to long where the result is saved
Result
1 means success. 0 means failure.
Notes
SAS/C specific
stcu_d()
Synopsis
int stcu_d( char * out, unsigned uivalue)
Function
Convert an unsigned integer to a decimal string
Inputs
out - Result will be put into this string uivalue - the value to convert
Result
The number of characters written into the string
Notes
SAS C specific
stpblk()
Synopsis
char * stpblk( const char * str )
Function
Searches for the first non-blank character in a string. A blank character is defined as one that isspace() treats like one (ie. spaces, tabs and newlines).
Inputs
str - String to search.
Result
A pointer to the first occurrence of a non-blank character in str.
Example
char *hello = " Hello"; char *empty = " "; printf( stpblk( hello ) ); --> Hello printf( stpblk( empty ) ); --> printf( "%d", strlen( stpblk( hello ) ) ); --> 5 printf( "%d", strlen( stpblk( empty ) ) ); --> 0
Notes
This function always returns a valid pointer as provided str isn't NULL. If there are no non-blank characters in the string, a pointer to the trailing '\0' is returned (ie. an empty string).
See also
stpcpy()
Synopsis
char * stpcpy( char * dest, const char * src)
Function
Copy a string returning pointer to its end.
Inputs
dest - The string is copied into this variable. Make sure it is
large enough.
src - This is the new contents of dest.
Result
pointer to the end of the string dest (address of it's null character)
Notes
No check is made that dest is large enough for src.
See also
stpsym()
Synopsis
char * stpsym( char * str_ptr, char * dest_ptr, int dest_size)
Function
Searches for a symbol in a string.
Inputs
str_ptr - points to the string to scan dest_ptr - points to the string where stpsym stores the symbol dest_size - specifies the size in bytes of *dest_ptr
Result
Pointer to the next character in the string after the symbol. If stpsym could not find a symbol, it returns str_ptr.
Example
#include <string.h>
#include <stdio.h>
int main(void)
{
char *text;
char symbol[10];
char *r;
text = "alpha1 2";
r = stpsym(text,symbol,10);
printf("%s",symbol); // prints "alpha1"
}
Notes
A symbol consists of an alphabetic character followed by zero or more alphanumeric characters. stpsym() does not skip leading space characters. Note that if you want to retrieve a symbol of length n, you need to ensure that *dest_ptr can accommodate at least n+1 elements, and that dest_size == n+1. This extra element is needed for the terminating null character.
strcasecmp()
Synopsis
int strcasecmp( const char * str1, const char * str2)
Function
Calculate str1 - str2 ignoring case.
Inputs
str1, str2 - Strings to compare
Result
The difference of the strings. The difference is 0, if both are equal, < 0 if str1 < str2 and > 0 if str1 > str2. Note that it may be greater then 1 or less than -1.
Notes
This function is not part of a library and may thus be called any time.
strcasestr()
Synopsis
char * strcasestr( const char * str, const char * search)
Function
Searches for a string in a string.
Inputs
str - Search this string search - Look for this string
Result
A pointer to the first occurrence of search in str or NULL if search is not found in str.
Example
char buffer[64]; strcpy (buffer, "Hello "); // This returns a pointer to the first l in buffer. strcasestr (buffer, "llo "); // This returns NULL strcasestr (buffer, "llox");
strcat()
Synopsis
char * strcat( char * dest, const char * src)
Function
Concatenates two strings.
Inputs
dest - src is appended to this string. Make sure that there
is enough room for src.
src - This string is appended to dest
Result
dest.
Example
char buffer[64]; strcpy (buffer, "Hello "); strcat (buffer, "World."); // Buffer now contains "Hello World."
Notes
The routine makes no checks if dest is large enough.
strchr()
Synopsis
char * strchr( const char * str, int c)
Function
Searches for a character in a string.
Inputs
str - Search this string c - Look for this character
Result
A pointer to the first occurrence of c in str or NULL if c is not found in str.
Example
char buffer[64]; strcpy (buffer, "Hello "); // This returns a pointer to the first l in buffer. strchr (buffer, 'l'); // This returns NULL strchr (buffer, 'x');
See also
strcmp()
Synopsis
int strcmp( const char * str1, const char * str2)
Function
Calculate str1 - str2.
Inputs
str1, str2 - Strings to compare
Result
The difference of the strings. The difference is 0, if both are equal, < 0 if str1 < str2 and > 0 if str1 > str2. Note that it may be greater then 1 or less than -1.
Notes
This function is not part of a library and may thus be called any time.
strcoll()
Synopsis
int strcoll( const char * str1, const char * str2)
Function
Calculate str1 - str2. The operation is based on strings interpreted as appropriate for the program's current locale for category LC_COLLATE.
Inputs
str1, str2 - Strings to compare
Result
The difference of the strings. The difference is 0, if both are equal, < 0 if str1 < str2 and > 0 if str1 > str2. Note that it may be greater then 1 or less than -1.
Notes
stdc.library only implements "C" locale so strcoll() is equivalent to strcmp()
strcpy()
Synopsis
char * strcpy( char * dest, const char * src)
Function
Copy a string. Works like an assignment "dest=src;".
Inputs
dest - The string is copied into this variable. Make sure it is
large enough.
src - This is the new contents of dest.
Result
dest.
Notes
No check is made that dest is large enough for src.
strcspn()
Synopsis
size_t strcspn( const char * str, const char * reject)
Function
Calculates the length of the initial segment of str which consists entirely of characters not in reject.
Inputs
str - The string to check. reject - Characters which must not be in str.
Result
Length of the initial segment of str which doesn't contain any characters from reject.
Example
char buffer[64]; strcpy (buffer, "Hello "); // Returns 5 strcspn (buffer, " "); // Returns 0 strcspn (buffer, "H");
strdup()
Synopsis
char * strdup( const char * orig)
Function
Create a copy of a string. The copy can be freed with free() or will be freed when the program ends.
Inputs
str1 - Strings to duplicate
Result
A copy of the string which can be freed with free().
strerror()
Synopsis
char * strerror( int n)
Function
Returns a readable string for an error number in errno.
Inputs
n - The contents of errno or a #define from errno.h
Result
A string describing the error.
Notes
This functions only handles the error codes needed by C99 and the ones used in stdc.library. This function is aliased as strerror() in libstdc.a Other libraries may override this function by providing this function also in their libxxx.a file. They can internally call __stdc_strerror to get the strings for the errors handled by this function.
strftime()
Synopsis
size_t strftime(
char *s,
size_t maxsize,
const char *format,
const struct tm *timeptr)
Function
Converts the time information in the struct tm pointed to by 'timeptr' into a formatted string according to the 'format' specification. The resulting string is placed in the buffer pointed to by 's', which can contain up to 'maxsize' characters, including the terminating null.
Inputs
s - Pointer to the destination character buffer.
maxsize - Maximum number of characters to store in the destination,
including the null terminator.
format - Format control string containing ordinary characters and
conversion specifiers, similar to ANSI strftime().
timeptr - Pointer to a struct tm containing the time values to format.
Result
The number of characters written to the destination buffer, excluding the terminating null character. Returns 0 if an error occurs (e.g., invalid arguments or formatting failure).
Example
struct tm now = { .tm_year = 124, .tm_mon = 6, .tm_mday = 7, .tm_wday = 0,
.tm_hour = 15, .tm_min = 30, .tm_sec = 45 };
char buf[64];
strftime(buf, sizeof(buf), "%A, %B %d, %Y %H:%M:%S %p", &now);
// Example output: "Sunday, July 07, 2024 15:30:45 PM"
Notes
Supports a subset of ANSI C strftime() specifiers: %a %A - abbreviated and full weekday names %b %B - abbreviated and full month names %p - AM/PM indicator %d %m %y %Y %H %I %M %S - numeric date/time fields %n %t %% - special characters Composite formats (%c, %x, %X, etc.) and locale-specific date/time formats are not yet implemented.
Bugs
- Does not support all strftime() specifiers. - Does not use the user�s actual locale settings.
strlcat()
Synopsis
size_t strlcat( char *dst, const char *src, size_t siz)
strlcpy()
Synopsis
size_t strlcpy( char *dst, const char *src, size_t siz)
strlen()
Synopsis
size_t strlen( const char * ptr)
Function
Calculate the length of a string (without the terminating 0 byte).
Inputs
ptr - The string to get its length for
Result
The length of the string.
strlwr()
Synopsis
char * strlwr( char * str)
Function
Converts a string to all lower case characters. Modifies the given string.
Inputs
str - The string to convert.
Result
The same string buffer is passed back with all characters converted.
strncasecmp()
Synopsis
int strncasecmp( const char * str1, const char * str2, size_t n)
Function
Calculate str1 - str2 ignoring case. Up to n characters are taken into account.
Inputs
str1, str2 - Strings to compare
Result
The difference of the strings. The difference is 0, if both are equal, < 0 if str1 < str2 and > 0 if str1 > str2. Note that it may be greater then 1 or less than -1.
Notes
This function is not part of a library and may thus be called any time.
strncat()
Synopsis
char * strncat( char * dest, const char * src, size_t n)
Function
Concatenates two strings. If src is longer than n characters, then only the first n characters are copied.
Inputs
dest - src is appended to this string. Make sure that there
is enough room for src.
src - This string is appended to dest
n - No more than this number of characters of src are copied.
Result
dest.
Example
char buffer[64]; strcpy (buffer, "Hello "); strncat (buffer, "World.!!", 6); // Buffer now contains "Hello World."
Notes
The routine makes no checks if dest is large enough. The size of dest must be at least strlen(dest)+n+1.
strncmp()
Synopsis
int strncmp( const char * str1, const char * str2, size_t n)
Function
Calculate str1 - str2 for up to n chars or up to the first 0 byte.
Inputs
str1, str2 - Strings to compare
Result
The difference of the strings. The difference is 0, if both are equal, < 0 if str1 < str2 and > 0 if str1 > str2. Note that it may be greater then 1 or less than -1.
Notes
This function is not part of a library and may thus be called any time.
strncpy()
Synopsis
char * strncpy( char * dest, const char * src, size_t n)
Function
Copy a string. Works like an assignment "dest=src;". At most n characters are copied.
Inputs
dest - The string is copied into this variable. Make sure it is
large enough.
src - This is the new contents of dest.
n - How many characters to copy at most. If the string src is
smaller than that, only strlen(str)+1 bytes are copied.
Result
dest.
Notes
No check is made that dest is large enough for src.
strndup()
Synopsis
char * strndup( const char *s, size_t n)
Function
Create a copy of a string. The copy can be freed with free() or will be freed when then program ends. The copy will be at most n character long, excluding the trailing \000
Inputs
s - String to duplicate n - Maximum length
Result
A copy of the string which can be freed with free().
strnlen()
Synopsis
size_t strnlen( const char * ptr, size_t n)
Function
Calculate the length of a string (without the terminating 0 byte).
Inputs
ptr - The string to get its length for n - The max length
Result
The length of the string.
strpbrk()
Synopsis
char * strpbrk( const char * str, const char * accept)
Function
Locate the first occurrence of any character in accept in str.
Inputs
str - Search this string accept - Look for these characters
Result
A pointer to the first occurrence of any character in accept in str or NULL if no character of accept is not found in str.
Example
char buffer[64]; strcpy (buffer, "Hello "); // This returns a pointer to the first l in buffer. strpbrk (buffer, "lo"); // This returns NULL strpbrk (buffer, "xyz");
strrchr()
Synopsis
char * strrchr( const char * str, int c)
Function
Searches for the last character c in a string.
Inputs
str - Search this string c - Look for this character
Result
A pointer to the first occurrence of c in str or NULL if c is not found in str.
Example
char buffer[64]; strcpy (buffer, "Hello "); // This returns a pointer to the second l in buffer. strrchr (buffer, 'l'); // This returns NULL strrchr (buffer, 'x');
See also
strrev()
Synopsis
char * strrev( char * s)
Function
Reverse a string (rotate it about its midpoint)
Inputs
s - The string to be reversed
Result
The original string pointer
Example
char buffer[64]; strcpy (buffer, "Hello); strrev(buffer); // buffer now contains "olleH"
Notes
SAS C specific
strsep()
Synopsis
char * strsep( char ** strptr, const char * sep)
Function
Separates a string by the characters in sep. Unlike strtok(), strsep() does not merge adjacent delimiters: an empty field (two delimiters in a row, or a leading delimiter) yields an empty string. This makes it suitable for parsing records whose fields may be empty.
Inputs
strptr - Address of the string to scan. Updated to point just after
the delimiter that terminated the returned token, or set to
NULL once the end of the string has been reached.
sep - Characters which separate "words" in the string.
Result
A pointer to the (possibly empty) token, or NULL when *strptr is already NULL (no more tokens).
Example
char buffer[64]; char *bufptr, *word; strcpy (buffer, "a,bb,,ccc"); bufptr = buffer; word = strsep (&bufptr, ","); // Returns "a" word = strsep (&bufptr, ","); // Returns "bb" word = strsep (&bufptr, ","); // Returns "" (empty field!) word = strsep (&bufptr, ","); // Returns "ccc" word = strsep (&bufptr, ","); // Returns NULL
Notes
The function changes the scanned string (it writes a NUL over the delimiter that terminates each token).
See also
strspn()
Synopsis
size_t strspn( const char * str, const char * accept)
Function
Calculates the length of the initial segment of str which consists entirely of characters in accept.
Inputs
str - The string to check. accept - Characters which have to be in str.
Result
Length of the initial segment of str which contains only characters from accept.
Example
char buffer[64]; strcpy (buffer, "Hello "); // Returns 5 strspn (buffer, "Helo"); // Returns 0 strspn (buffer, "xyz");
strstr()
Synopsis
char * strstr( const char * str, const char * search)
Function
Searches for a string in a string.
Inputs
str - Search this string search - Look for this string
Result
A pointer to the first occurrence of search in str or NULL if search is not found in str.
Example
char buffer[64]; strcpy (buffer, "Hello "); // This returns a pointer to the first l in buffer. strstr (buffer, "llo "); // This returns NULL strstr (buffer, "llox");
strtod()
Synopsis
double strtod( const char * str, char ** endptr)
Function
Convert a string of digits into a double.
Inputs
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'. An 'e' or 'E' introduces the exponent.
Komma is only allowed before exponent.
endptr - If this is non-NULL, then the address of the first
character after the number in the string is stored
here.
Result
The value of the string. The first character after the number is returned in *endptr, if endptr is non-NULL. If no digits can be converted, *endptr contains str (if non-NULL) and 0 is returned.
strtof()
Synopsis
float strtof( const char * str, char ** endptr)
Function
Convert a floating-point number from an ASCII decimal representation into a double-precision format.
Inputs
str - The string which should be converted. Leading
whitespace are ignored.
endptr - If this is non-NULL, then the address of the first
character after the number in the string is stored
here.
Result
The float value of the string. The first character after the number is returned in *endptr, if endptr is non-NULL. If no digits can be converted, *endptr contains str (if non-NULL) and 0 is returned.
strtoimax()
Synopsis
intmax_t strtoimax( const char * nptr, char ** endptr, int base)
Function
Convert a string of digits into an integer according to the given base. This function is like strtol() except the fact, that it returns a value of type intmax_t.
Inputs
str - The string which should be converted.
endptr - If this is non-NULL, then the address of the first
character after the number in the string is stored
here.
base - The base for the number.
Result
The value of the string. The first character after the number is returned in *endptr, if endptr is non-NULL. If no digits can be converted, *endptr contains str (if non-NULL) and 0 is returned.
Bugs
errno is not set as required by C99 standard
strtok()
Synopsis
char * strtok( char * str, const char * sep)
Function
Separates a string by the characters in sep.
Inputs
str - The string to check or NULL if the next word in
the last string is to be searched.
sep - Characters which separate "words" in str.
Result
The first word in str or the next one if str is NULL.
Example
char buffer[64]; strcpy (buffer, "Hello, this is a test."); // Init. Returns "Hello" strtok (str, " \t,."); // Next word. Returns "this" strtok (NULL, " \t,."); // Next word. Returns "is" strtok (NULL, " \t"); // Next word. Returns "a" strtok (NULL, " \t"); // Next word. Returns "test." strtok (NULL, " \t"); // Next word. Returns NULL. strtok (NULL, " \t");
Notes
The function changes str !
strtol()
Synopsis
long strtol( const char * str, char ** endptr, int base)
Function
Convert a string of digits into an integer according to the given base.
Inputs
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'. If base is above 10, then the
alphabetic characters from 'A' are used to specify
digits above 9 (ie. 'A' or 'a' is 10, 'B' or 'b' is
11 and so on until 'Z' or 'z' is 35).
endptr - If this is non-NULL, then the address of the first
character after the number in the string is stored
here.
base - The base for the number. May be 0 or between 2 and 36,
including both. 0 means to autodetect the base. strtoul()
selects the base by inspecting the first characters
of the string. If they are "0x", then base 16 is
assumed. If they are "0", then base 8 is assumed. Any
other digit will assume base 10. This is like in C.
If you give base 16, then an optional "0x" may
precede the number in the string.
Result
The value of the string. The first character after the number is returned in *endptr, if endptr is non-NULL. If no digits can be converted, *endptr contains str (if non-NULL) and 0 is returned.
Example
// returns 1, ptr points to the 0-Byte
strol (" \t +0x1", &ptr, 0);
// Returns 15. ptr points to the a
strol ("017a", &ptr, 0);
// Returns 215 (5*36 + 35)
strol ("5z", &ptr, 36);
strtold()
Synopsis
long double strtold( const char * str, char ** endptr)
Function
Convert a string of digits into a long double.
Inputs
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'. An 'e' or 'E' introduces the exponent.
Comma is only allowed before exponent.
endptr - If this is non-NULL, then the address of the first
character after the number in the string is stored
here.
Result
The value of the string. The first character after the number is returned in *endptr, if endptr is non-NULL. If no digits can be converted, *endptr contains str (if non-NULL) and 0 is returned.
Notes
We make the compiler do an internal conversion from a double to a long double. Because of this we lose a some precision, but for now it works.
Bugs
NAN is not handled at the moment
See also
strtoll()
Synopsis
long long strtoll( const char * restrict str, char ** restrict endptr, int base)
Function
Convert a string of digits into an integer according to the given base.
Inputs
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'. If base is above 10, then the
alphabetic characters from 'A' are used to specify
digits above 9 (ie. 'A' or 'a' is 10, 'B' or 'b' is
11 and so on until 'Z' or 'z' is 35).
endptr - If this is non-NULL, then the address of the first
character after the number in the string is stored
here.
base - The base for the number. May be 0 or between 2 and 36,
including both. 0 means to autodetect the base. strtoul()
selects the base by inspecting the first characters
of the string. If they are "0x", then base 16 is
assumed. If they are "0", then base 8 is assumed. Any
other digit will assume base 10. This is like in C.
If you give base 16, then an optional "0x" may
precede the number in the string.
Result
The value of the string. The first character after the number is returned in *endptr, if endptr is non-NULL. If no digits can be converted, *endptr contains str (if non-NULL) and 0 is returned.
Example
// returns 1, ptr points to the 0-Byte
strtoll (" \t +0x1", &ptr, 0);
// Returns 15. ptr points to the a
strtoll ("017a", &ptr, 0);
// Returns 215 (5*36 + 35)
strtoll ("5z", &ptr, 36);
See also
strtoul()
Synopsis
unsigned long strtoul( const char * str, char ** endptr, int base)
Function
Convert a string of digits into an integer according to the given base.
Inputs
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'. If base is above 10, then the
alphabetic characters from 'A' are used to specify
digits above 9 (ie. 'A' or 'a' is 10, 'B' or 'b' is
11 and so on until 'Z' or 'z' is 35).
endptr - If this is non-NULL, then the address of the first
character after the number in the string is stored
here.
base - The base for the number. May be 0 or between 2 and 36,
including both. 0 means to autodetect the base. strtoul()
selects the base by inspecting the first characters
of the string. If they are "0x", then base 16 is
assumed. If they are "0", then base 8 is assumed. Any
other digit will assume base 10. This is like in C.
If you give base 16, then an optional "0x" may
precede the number in the string.
Result
The value of the string. The first character after the number is returned in *endptr, if endptr is non-NULL. If no digits can be converted, *endptr contains str (if non-NULL) and 0 is returned.
Example
// Returns 1, ptr points to the 0-Byte
strtoul (" \t +0x1", &ptr, 0);
// Returns 15. ptr points to the a
strtoul ("017a", &ptr, 0);
// Returns 215 (5*36 + 35)
strtoul ("5z", &ptr, 36);
strtoull()
Synopsis
unsigned long long strtoull( const char * restrict str, char ** restrict endptr, int base)
Function
Convert a string of digits into an integer according to the given base.
Inputs
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'. If base is above 10, then the
alphabetic characters from 'A' are used to specify
digits above 9 (ie. 'A' or 'a' is 10, 'B' or 'b' is
11 and so on until 'Z' or 'z' is 35).
endptr - If this is non-NULL, then the address of the first
character after the number in the string is stored
here.
base - The base for the number. May be 0 or between 2 and 36,
including both. 0 means to autodetect the base. strtoull()
selects the base by inspecting the first characters
of the string. If they are "0x", then base 16 is
assumed. If they are "0", then base 8 is assumed. Any
other digit will assume base 10. This is like in C.
If you give base 16, then an optional "0x" may
precede the number in the string.
Result
The value of the string. The first character after the number is returned in *endptr, if endptr is non-NULL. If no digits can be converted, *endptr contains str (if non-NULL) and 0 is returned.
Example
// Returns 1, ptr points to the 0-Byte
strtoull (" \t +0x1", &ptr, 0);
// Returns 15. ptr points to the a
strtoull ("017a", &ptr, 0);
// Returns 215 (5*36 + 35)
strtoull ("5z", &ptr, 36);
See also
strtoumax()
Synopsis
uintmax_t strtoumax( const char * nptr, char ** endptr, int base)
Function
Convert a string of digits into an integer according to the given base. This function is like strtoul() except the fact, that it returns a value of type uintmax_t.
Inputs
str - The string which should be converted.
endptr - If this is non-NULL, then the address of the first
character after the number in the string is stored
here.
base - The base for the number.
Result
The value of the string. The first character after the number is returned in *endptr, if endptr is non-NULL. If no digits can be converted, *endptr contains str (if non-NULL) and 0 is returned.
Bugs
errno is not set as required by C99 standard
See also
strupr()
Synopsis
char * strupr( char * str)
Function
Converts a string to all upper case characters. Modifies the given string.
Inputs
str - The string to convert.
Result
The same string buffer is passed back with all characters converted.
strxfrm()
Synopsis
size_t strxfrm( char * restrict dst, const char * restrict src, size_t n)
Function
The strxfrm() function transforms a null-terminated string pointed to by src according to the current locale collation if any, then copies the transformed string into dst. Not more than n characters are copied into dst, including the terminating null character added. If n is set to 0 (it helps to determine an actual size needed for transformation), dst is permitted to be a NULL pointer. Comparing two strings using strcmp() after strxfrm() is equal to compar- ing two original strings with strcoll().
Inputs
dst - the destination string's buffer src - the source string n - the size of the dst buffer.
Result
Upon successful completion, strxfrm() returns the length of the trans- formed string not including the terminating null character. If this value is n or more, the contents of dst are indeterminate.
Notes
stdc.library only support "C" locale so strxfrm is equivalent to strncpy.
swprintf()
Synopsis
int swprintf( wchar_t * restrict str, size_t maxsize, const wchar_t * restrict format, ...)
Function
Format a variable list of arguments according to a wide-character format string and store the result in the specified buffer.
Inputs
s - Destination buffer for the formatted wide-character string.
maxsize - Maximum number of wide characters to store in the buffer,
including the null terminator.
format - A wide-character printf() format string.
... - Additional arguments matching the format specifiers.
Result
The number of wide characters written to the buffer, excluding the terminating null character. A negative value is returned if an error occurs.
Notes
The result is always null-terminated unless maxsize is zero.
See also
swscanf()
Synopsis
int swscanf( const wchar_t * restrict ws, const wchar_t * restrict format, ...)
Function
Reads formatted wide-character input from the given wide-character string and stores the results into the provided argument locations.
Inputs
ws - Read from this wide-character string format - How to convert the input into the arguments ... - Write the result in these arguments
Result
The number of converted arguments.
system()
Synopsis
int system( const char *string)
Function
Execute a command string. If string is NULL then 1 will be returned.
Inputs
string - command to execute or NULL
Result
Return value of command executed. If value < 0 errno indicates error. 1 is return if string is NULL.
Notes
The system() version of stdcio.library just passes the command to SystemTags() dos.library call.
tan()
Synopsis
double tan( double x)
Function
Computes the tangent of x (x in radians).
Inputs
x - input angle in radians.
Result
Returns tan(x).
Example
double val = tan(3.14159 / 4); // approximately 1.0
Notes
Uses range reduction and polynomial approximation internally. Returns NaN and sets errno to EDOM if x is an odd multiple of p/2.
Bugs
None known.
tanf()
Synopsis
float tanf( float x)
Function
Computes the tangent of x (in radians).
Inputs
x - angle in radians.
Result
Tangent of x.
Example
float r = tanf(0.785398f); // 1.0 (p/4 radians)
Notes
tan(x) = sin(x) / cos(x), undefined at (p/2 + kp)
Bugs
Near p/2 and odd multiples, large errors or infinities may result.
tanh()
Synopsis
double tanh( double x)
Function
Computes the hyperbolic tangent of x.
Inputs
x - input value.
Result
Returns tanh(x) = sinh(x) / cosh(x).
Example
double val = tanh(1.0);
Notes
Uses exponentials internally for calculation.
Bugs
None known.
tanhf()
Synopsis
float tanhf( float x)
Function
Computes hyperbolic tangent of x.
Inputs
x - input float
Result
Returns tanh(x).
Example
float r = tanhf(1.0f); // 0.761594
Notes
Approaches ±1 for large |x|.
Bugs
None known.
tanhl()
Synopsis
long double tanhl( long double x)
Function
Computes the hyperbolic tangent of x.
Inputs
x - input value.
Result
Returns tanh(x) = sinh(x) / cosh(x).
Example
double val = tanh(1.0);
Notes
Uses exponentials internally for calculation.
Bugs
None known.
tanl()
Synopsis
long double tanl( long double x)
Function
Computes the tangent of x.
Inputs
x - angle in radians.
Result
Returns tan(x), or may overflow near odd multiples of p/2.
Example
long double r = tanl(0.0L); // returns 0.0L
Notes
Long double variant of tan().
Bugs
None known.
tgamma()
Synopsis
double tgamma( double x)
Function
Computes the gamma function G(x).
Inputs
x - input value.
Result
Returns the gamma function value. Domain errors set errno to EDOM.
Example
double val = tgamma(5.0); // returns 24.0 (4!)
Notes
Extends the factorial function to real numbers.
Bugs
None known.
tgammal()
Synopsis
long double tgammal( long double x)
Function
Computes the gamma function G(x).
Inputs
x - input value.
Result
Returns G(x), or 8 for poles.
Example
long double r = tgammal(5.0L); // returns 24.0L
Notes
Undefined for negative integers.
Bugs
None known.
time()
Synopsis
time_t time( time_t * tloc)
Function
time() returns the time since 00:00:00 GMT, January 1, 1970, measured in seconds.
Inputs
tloc - If this pointer is non-NULL, then the time is written into
this variable as well.
Result
The number of seconds.
Example
time_t tt1, tt2; // tt1 and tt2 are the same tt1 = time (&tt2); // This is valid, too tt1 = time (NULL);
Notes
This function must not be used in a shared library or in a threaded application.
See also
timespec_get()
Synopsis
int timespec_get( struct timespec *ts, int base)
Function
Store the current calendar time, based on the given time base, into *ts. The only base required by C11 is TIME_UTC, for which the time is the number of seconds and nanoseconds since the epoch (UTC).
Inputs
ts - the timespec to fill in. base - the time base; TIME_UTC is supported.
Result
base on success, or 0 if base is not supported or the time could not be obtained.
See also
tmpfile()
Synopsis
FILE * tmpfile( void)
Function
The tmpfile() function creates a temporary file that is different from any other existing file and that will automatically be removed when it is closed or at program termination. The file is opened for update with "wb+" mode.
Result
Pointer to the stream that was created. On error NULL is returned.
Example
#include <errno.h>
#include <stdio.h>
#include <string.h>
main()
{
FILE * fp;
fp = tmpfile();
if ( fp == NULL)
{
perror(strerror(errno));
return;
}
fprintf(fp, "do a bit of writing to the temp file");
}
Notes
This function uses tmpnam(NULL) to get the file name.
tmpnam()
Synopsis
char *tmpnam( char *s)
Function
The tmpnam function generates a string that is a valid file name and that is not the same as the name of an existing file. The function is potentially capable of generating TMP_MAX different strings, but any or all of them may already be in use by existing files and thus not be suitable return values.
Inputs
Pointer to a string of at least L_tmpnam characters.
Result
The resulting file name is returned in the input string pointer or a pointer to an internal buffer if NULL was passed to the function. If file name generation failed a NULL is returned.
See also
towctrans()
Synopsis
wint_t towctrans( wint_t wc, wctrans_t desc)
Function
Transforms a wide character according to the mapping identified by the wctrans_t descriptor.
Inputs
wc - the wide character to transform. desc - transformation descriptor from `wctrans()`.
Result
The transformed wide character, or the original character if the descriptor is invalid.
Example
wctrans_t t = wctrans("tolower");
wint_t lc = towctrans(L'Z', t); // 'z'
Bugs
Behavior is undefined if `desc` was not obtained from `wctrans()`.
See also
towlower()
Synopsis
wint_t towlower( wint_t wc)
Function
Converts an uppercase wide character to its lowercase equivalent.
Inputs
wc - a wide character code point.
Result
The lowercase equivalent of the input character if applicable; otherwise returns the character unchanged.
Example
wint_t c = towlower(L'Ä'); // returns L'ä'
Notes
Supports all characters in the ASCII and Latin-1 Supplement ranges. For example, `L'É'` ? `L'é`.
See also
towupper()
Synopsis
wint_t towupper( wint_t wc)
Function
Converts a lowercase wide character to its uppercase equivalent.
Inputs
wc - a wide character code point.
Result
The uppercase equivalent of the input character if applicable; otherwise returns the character unchanged.
Example
wint_t c = towupper(L'è'); // returns L'È'
Notes
Supports all characters in the ASCII and Latin-1 Supplement ranges. For example, `L'ö'` ? `L'Ö'`.
Bugs
Characters outside U+00FF are returned unchanged.
See also
trunc()
Synopsis
double trunc( double x)
Function
Truncates fractional part of x toward zero.
Inputs
x - input double
Result
Integral part of x without fraction.
Example
double r = trunc(3.9); // 3.0 double r2 = trunc(-3.9); // -3.0
Notes
Differs from floor() by rounding toward zero.
Bugs
None known.
truncf()
Synopsis
float truncf( float x)
Function
Truncates fractional part of x toward zero.
Inputs
x - input float
Result
Integral part with fraction discarded.
Example
float r = truncf(2.9f); // 2.0f float r2 = truncf(-2.9f); // -2.0f
Notes
Differs from floorf() by rounding toward zero.
Bugs
None known.
truncl()
Synopsis
long double truncl( long double x)
Function
Truncates fractional part of x (long double) toward zero.
Inputs
x - input long double
Result
Integral part without fraction.
Example
long double r = truncl(3.9L); // 3.0L long double r2 = truncl(-3.9L); // -3.0L
Notes
Same behavior as trunc() for long double.
Bugs
None known.
ungetc()
Synopsis
int ungetc( int c, FILE * stream)
Function
Puch the character c character back into the stream.
Inputs
c - Put this character back into the stream. The next read will
return this character. If you push back more than one
character, then they will be returned in reverse order.
The function guarantees that one character can be
pushed back but no more. It is possible to push the EOF
character back into the stream.
stream - Read from this stream
Result
c or EOF on error.
ungetwc()
Synopsis
wint_t ungetwc( wint_t wc, FILE * stream)
Function
Push a wide character back onto the input stream. The next read operation will return this character.
Inputs
wc - Wide character to push back (can be WEOF). stream - Pointer to the stream.
Result
Returns the wide character pushed back, or WEOF on error.
Notes
Only one wide character can be pushed back at a time. Subsequent calls without reading will overwrite the previous pushed-back character.
vasprintf()
Synopsis
int vasprintf( char **restrict str, const char *restrict format, va_list args)
Function
Analog of vsprintf, except that sotrage is allocated for a string large enough to hold the output including the terminating null byte
Inputs
str - Where to store the pointer for the allocated string. format - A printf() format string. args - A list of arguments for the format string.
Result
The number of characters written, or EOF on error.
See also
vfprintf()
Synopsis
int vfprintf( FILE * restrict stream, const char * restrict format, va_list args)
Function
Format a list of arguments and print them on the specified stream.
Inputs
stream - A stream on which one can write format - A printf() format string. args - A list of arguments for the format string.
Result
The number of characters written.
vfscanf()
Synopsis
int vfscanf( FILE * stream, const char * format, va_list args)
Function
Read the scream, scan it as the format specified and write the result of the conversion into the specified arguments.
Inputs
stream - A stream to read from format - A scanf() format string. args - A list of arguments for the results.
Result
The number of converted arguments.
vfwprintf()
Synopsis
int vfwprintf( struct __sFILE * restrict stream, const wchar_t * restrict format, va_list arg)
Function
Format a va_list of arguments according to a wide-character format string and write the output to the given stream.
Inputs
stream - Output stream. format - A wide-character printf() format string. arg - A va_list containing the arguments for the format string.
Result
The number of wide characters written to the stream, or a negative value if an error occurs.
Notes
This is the va_list version of fwprintf(), similar to vprintf().
See also
vfwscanf()
Synopsis
int vfwscanf( FILE * restrict stream, const wchar_t * restrict format, va_list arg)
Function
Reads formatted wide-character input from the given file stream, parsing according to the given format string, and stores the results into the locations described by the argument list.
Inputs
stream - Read from this wide-character file stream format - How to convert the input into the arguments arg - List of argument pointers to receive results
Result
The number of converted arguments.
See also
vprintf()
Synopsis
int vprintf( const char * format, va_list args)
Function
Format a list of arguments and print them on the standard output.
Inputs
format - A printf() format string. args - A list of arguments for the format string.
Result
The number of characters written.
vscanf()
Synopsis
int vscanf( const char * format, va_list args)
Function
Scan the standard input and convert it into the arguments as specified by format.
Inputs
format - A scanf() format string. args - A list of arguments for the results
Result
The number of converted parameters.
vsnprintf()
Synopsis
int vsnprintf( char * str, size_t n, const char * format, va_list args)
Function
Format a list of arguments and put them into the string str. The function makes sure that no more than n characters (including the terminal 0 byte) are written into str. If n is zero, nothing is written, and s may be a null pointer. Otherwise, output characters beyond the n-1st 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. If copying takes place between objects that overlap, the behavior is undefined.
Inputs
str - The formatted result is stored here n - The size of str format - A printf() format string. args - A list of arguments for the format string.
Result
Function 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.
vsprintf()
Synopsis
int vsprintf( char * str, const char * format, va_list args)
Function
Format a list of arguments and put them into the string str.
Inputs
str - The formatted result is stored here format - A printf() format string. args - A list of arguments for the format string.
Result
The number of characters written.
Notes
No check is made that str is large enough to contain the result.
vsscanf()
Synopsis
int vsscanf( const char *str, const char *format, va_list args)
Function
Scan a string and convert it into the arguments as specified by format.
Inputs
str - Scan this string format - A scanf() format string. args - A list of arguments for the results
Result
The number of arguments converted.
vswprintf()
Synopsis
int vswprintf( wchar_t * restrict str, size_t maxsize, const wchar_t * restrict format, va_list args)
Function
Format a va_list of arguments according to a wide-character format string and store the result in the specified buffer.
Inputs
s - Destination buffer for the formatted wide-character string.
maxsize - Maximum number of wide characters to store in the buffer,
including the null terminator.
format - A wide-character printf() format string.
arg - A va_list containing the arguments for the format string.
Result
The number of wide characters written to the buffer, excluding the terminating null character. A negative value is returned if an error occurs.
Notes
The result is always null-terminated unless maxsize is zero.
See also
vswscanf()
Synopsis
int vswscanf( const wchar_t * restrict ws, const wchar_t * restrict format, va_list arg)
Function
Reads formatted wide-character input from the given wide-character string, parsing according to the given format string, and stores the results into the locations described by the argument list.
Inputs
ws - Read from this wide-character string format - How to convert the input into the arguments arg - List of argument pointers to receive results
Result
The number of converted arguments.
See also
vwprintf()
Synopsis
int vwprintf( const wchar_t * restrict format, va_list args)
Function
Format a va_list of arguments according to a wide-character format string and print the output to the standard output stream.
Inputs
format - A wide-character printf() format string. arg - A va_list containing the arguments for the format string.
Result
The number of wide characters written to the standard output, or a negative value if an error occurs.
Notes
Equivalent to vfwprintf() with stdout as the output stream.
See also
vwscanf()
Synopsis
int vwscanf( const wchar_t * restrict format, va_list arg)
Function
Reads formatted wide-character input from the standard input stream and stores the results into the locations described by the argument list.
Inputs
format - How to convert the input into the arguments arg - List of argument pointers to receive results
Result
The number of converted arguments.
See also
wcrtomb()
Synopsis
e_t wcrtomb( char * restrict s, wchar_t wc, mbstate_t * restrict ps)
Function
Converts a single wide character (wchar_t) to its multibyte representation and stores it in the output buffer 's'.
Inputs
s - Pointer to the destination buffer to receive the multibyte sequence.
If NULL, the function returns the length of the encoding sequence used
to reset the shift state (which is 1 for UTF-8 or 0 for state-independent encodings).
wc - The wide character to convert.
ps - Pointer to an mbstate_t object that keeps conversion state between calls.
May be NULL for stateless encodings like UTF-8.
Result
Returns the number of bytes written to 's' if successful. If 'wc' is the null wide character, a single null byte is written and 1 is returned. If the conversion fails (invalid code point or sequence), (size_t)-1 is returned and errno is set to EILSEQ.
Example
wchar_t wc = L'ü'; char buf[MB_CUR_MAX]; size_t len = wcrtomb(buf, wc, NULL);
Notes
This implementation assumes a stateless encoding (UTF-8). If 'ps' is NULL, an internal static conversion state is not maintained behavior is stateless. Surrogate pairs and values above U+10FFFF are treated as invalid.
Bugs
Does not support stateful encodings. No locale-specific behavior is implemented assumes UTF-8 or ASCII compatible only.
See also
wcscat()
Synopsis
wchar_t *wcscat( wchar_t *wcdst, const wchar_t *wcsrc)
Function
Appends a wide string, onto another wide string.
Inputs
wcdst - the wide string that will have the text appended to it. wcsrc - the wide string to append.
Result
A pointer to the resulting wide string.
wcschr()
Synopsis
ar_t *wcschr( const wchar_t* s, wchar_t c)
Function
Find the first occurrence of c in the wide string s.
Inputs
s - source wide string. c - wide character to locate.
Result
Returns a pointer to the located wide character c. If c does not occur in the wide string s a null pointer is returned.
wcscmp()
Synopsis
int wcscmp( const wchar_t *wcstra, const wchar_t *wcstrb)
Function
Lexicographically compares two null-terminated wide strings.
Inputs
wcstra - wide string to compare. wcstrb - wide string to compare.
Result
If wcstra appears before wcstrb lexographically, then -1 is returned. If wcstrb appears before wcstra lexographically, then 1 is returned. If the strings are equal, 0 is returned.
wcscoll()
Synopsis
nt wcscoll( const wchar_t *ws1, const wchar_t *ws2)
Function
Compares the two wide-character strings 'ws1' and 'ws2' according to the current locale's collation order.
Inputs
ws1 -- first wide-character string ws2 -- second wide-character string
Result
Returns < 0 if ws1 < ws2, 0 if ws1 == ws2, > 0 if ws1 > ws2.
Notes
This implementation ignores locale collation and performs a binary comparison using wcscmp().
wcscpy()
Synopsis
wchar_t *wcscpy( wchar_t *wcdst, const wchar_t *wcsrc)
Function
Copies a wide string, to another wide string.
Inputs
wcdst - the wide string that will be copied to. wcsrc - the wide string to copy.
Result
A pointer to the resulting wide string.
wcscspn()
Synopsis
e_t wcscspn( const wchar_t *s1, const wchar_t *s2)
Function
Scans s1 for the first occurrence of any of the wide characters that are part of s2, returning the number of wide characters of s1 read before this first occurrence..
Inputs
s1 - wide string to be scanned. s2 - wide string containing the characters to match.
Result
Returns the length of the segment.
wcsftime()
Synopsis
size_t wcsftime( wchar_t *s, size_t maxsize, const wchar_t *format, const struct tm *timeptr)
Function
Format time/date according to locale-dependent format. This is the wide character version of strftime().
Inputs
s - buffer to store the formatted string maxsize - maximum number of wide characters to store format - format string with conversion specifiers timeptr - pointer to tm structure containing time/date
Result
Number of wide characters stored in s (excluding null terminator), or 0 if the result would not fit in maxsize characters.
Example
wchar_t buffer[100]; struct tm *timeinfo; time_t rawtime; time(&rawtime); timeinfo = localtime(&rawtime); wcsftime(buffer, 100, L"Today is %A, %B %d, %Y", timeinfo);
Notes
Function does not take localization into account at the moment. Conversion specifiers are the same as strftime().
See also
wcslen()
Synopsis
size_t wcslen( const wchar_t *wcstr)
Function
Returns the length of a wide string.
Inputs
wcstr - wide string to tally.
Result
The number of non-null wide characters, in the wide string.
wcsncat()
Synopsis
ar_t *wcsncat( wchar_t *dest, const wchar_t *src, size_t n)
Function
Appends at most n wide characters from the wide string src to the end of the wide string dest, and null-terminates the result.
Inputs
dest - Destination wide string buffer. Must be large enough to hold the
resulting concatenated string including the terminating null.
src - Source wide string to append.
n - Maximum number of wide characters to append from src.
Result
Returns a pointer to the destination string dest.
Example
wchar_t buf[20] = L"Hello, "; wcsncat(buf, L"World!", 3); // buf now contains L"Hello, Wor"
Notes
Appends characters up to n or until a null wide character in src is encountered, whichever comes first. The resulting string in dest is always null-terminated. Behavior is undefined if dest and src overlap.
wcsncmp()
Synopsis
int wcsncmp( const wchar_t *wcstra, const wchar_t *wcstrb, size_t cnt)
Function
Lexicographically compares two null-terminated wide strings, upto the specified length
Inputs
wcstra - wide string to compare. wcstrb - wide string to compare. cnt - maximum number of wide characters to compare.
wcsncpy()
Synopsis
wchar_t *wcsncpy( wchar_t *wcdst, const wchar_t *wcsrc, size_t cnt)
Function
Copies upto the specified length of wide characters from a wide string, to another wide string.
Inputs
wcdst - the wide string that will be copied to. wcsrc - the wide string to copy. cnt - maximum number of wide characters to copy.
Result
A pointer to the resulting wide string.
wcspbrk()
Synopsis
ar_t *wcspbrk( const wchar_t *s, const wchar_t *accept)
Function
Scans the wide string s for the first occurrence of any character in the wide string accept.
Inputs
s - Wide string to scan. accept - Wide string containing characters to match.
Result
Returns a pointer to the first occurrence in s of any character from accept, or NULL if no such character is found.
wcsrchr()
Synopsis
ar_t *wcsrchr( const wchar_t *s, wchar_t c)
Function
Locates the last occurrence of the wide character c in the wide string s.
Inputs
s - Wide string to search. c - Wide character to locate.
Result
Returns a pointer to the last occurrence of c in s, or NULL if c is not found. If c is the null character, returns a pointer to the null terminator.
wcsrtombs()
Synopsis
size_t wcsrtombs( char * restrict dst, const wchar_t ** restrict src, size_t len, mbstate_t * restrict ps)
Function
Converts a null-terminated wide character string pointed to by *src into a corresponding multibyte character string. The conversion uses the current locale (UTF-8 assumed here) and updates the src pointer to point past the last converted wide character.
Inputs
dst - Pointer to destination multibyte buffer (may be NULL).
src - Address of the wide character string pointer. The pointer is updated
during conversion. If dst is NULL, the function returns the number
of bytes that would result from the conversion.
len - Maximum number of bytes to write.
ps - Conversion state object (ignored in this implementation).
Result
Returns the number of bytes written or needed. Returns (size_t)-1 on conversion error and sets errno to EILSEQ.
Notes
This implementation assumes stateless UTF-8 encoding and does not currently use mbstate_t. It wraps around wcrtomb().
See also
wcsspn()
Synopsis
e_t wcsspn( const wchar_t *s1, const wchar_t *s2)
Function
Calculates the length of the initial segment of s1 which consists entirely of wide characters in s2.
Inputs
s1 - wide string to be scanned. s2 - wide string containing the characters to match.
Result
Length of the initial segment of s1 which contains only wide characters from s2.
wcsstr()
Synopsis
ar_t *wcsstr( const wchar_t *s1, const wchar_t *s2)
Function
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.
Inputs
s1 - wide string to be scanned. s2 - wide string containing the sequence of characters to match.
Result
Returns a pointer to the first occurrence in s1 of the entire sequence of characters specified in s2, or a null pointer if the sequence is not present in s1.
wcstod()
Synopsis
ble wcstod( const wchar_t *nptr, wchar_t **endptr)
Function
Converts the initial portion of the wide string nptr to a double-precision floating-point number. Conversion stops at the first invalid character.
Inputs
nptr - Wide string to convert.
endptr - If not NULL, set to point to the character after the last used
in conversion.
Result
Returns the converted double value. Returns 0.0 if no conversion could be performed. On overflow, returns HUGE_VAL and sets errno to ERANGE.
Example
wchar_t *end; double val = wcstod(L"3.14159xyz", &end); // val == 3.14159, *end == L'x'
Notes
Recognizes optional whitespace, optional sign, decimal and exponential notation, and special values such as "inf" and "nan".
wcstof()
Synopsis
at wcstof( const wchar_t *nptr, wchar_t **endptr)
Function
Converts the initial portion of the wide string nptr to a single-precision floating-point number. Stops at the first invalid character.
Inputs
nptr - Wide string to convert. endptr - If not NULL, updated to point after the last consumed character.
Result
Returns the converted float value, or 0.0 if no conversion was possible. On overflow, returns HUGE_VALF and sets errno to ERANGE.
Example
wchar_t *end; float val = wcstof(L"2.71828abc", &end); // val == 2.71828f, *end == L'a'
Notes
Supports whitespace, optional sign, decimal/exponential notation, and special values like "inf" and "nan".
wcstoimax()
Synopsis
intmax_t wcstoimax( const wchar_t * restrict nptr, wchar_t ** restrict endptr, int base)
Function
Converts a wide-character string of digits into an integer of type intmax_t, according to the specified base. This function behaves like wcstol() but returns an intmax_t result.
Inputs
nptr - Pointer to the wide-character string to convert.
endptr - If non-NULL, stores the address of the first character
after the number.
base - The base for conversion (e.g., 10 for decimal, 16 for hex).
Result
Returns the converted value as an intmax_t. If no valid conversion could be performed, returns 0 and stores nptr in *endptr (if endptr is non-NULL).
Example
wchar_t *str = L"12345"; wchar_t *end; intmax_t value = wcstoimax(str, &end, 10);
Notes
Does not set errno on overflow or underflow, contrary to the C99 standard. Behavior is otherwise compatible with the standard library definition.
Bugs
errno is not set on conversion errors or range overflows.
See also
wcstok()
Synopsis
ar_t *wcstok( wchar_t * restrict s1, const wchar_t * restrict s2, wchar_t ** restrict ptr)
Function
Split wide string into tokens.
Inputs
s1 - wide string to truncate. s2 - wide string containing the delimiter wide characters. ptr - Pointer to a wchar_t pointer.
Result
Returns a pointer to the first wide character of a token, or a null pointer if there is no token.
wcstol()
Synopsis
g wcstol( const wchar_t *nptr, wchar_t **endptr, int base)
Function
Converts the initial part of wide string nptr to a long integer value, using the specified base (2 to 36) or auto-detect if base is 0.
Inputs
nptr - Wide string to convert. endptr - If not NULL, set to character after last used in conversion. base - Numeric base for conversion (0, or 2 to 36).
Result
Returns the converted long integer. On overflow, returns LONG_MAX or LONG_MIN and sets errno to ERANGE. Returns 0 if no conversion was done.
Example
wchar_t *end; long val = wcstol(L"0x10abc", &end, 0); // val == 16, *end == L'a'
Notes
Skips optional whitespace and supports optional '+' or '-' sign. Base 0 auto-detects hexadecimal (0x), octal (0), or decimal.
See also
wcstold()
Synopsis
g double wcstold( const wchar_t *nptr, wchar_t **endptr)
Function
Converts the initial portion of the wide string nptr to a long double floating-point number. Stops at first invalid character.
Inputs
nptr - Wide string input. endptr - If not NULL, set to the character after last converted character.
Result
Returns converted long double value. Returns 0.0L if no conversion. On overflow, returns HUGE_VALL and sets errno to ERANGE.
Example
wchar_t *end; long double val = wcstold(L"1.2345e10xyz", &end); // val == 1.2345e10L, *end == L'x'
Notes
Handles optional whitespace, sign, decimal and exponential notation, and special values "inf" and "nan".
wcstoll()
Synopsis
g long wcstoll( const wchar_t *nptr, wchar_t **endptr, int base)
Function
Converts the initial part of wide string nptr to a long long integer, respecting the base (2 to 36) or auto-detect if base is 0.
Inputs
nptr - Wide string input. endptr - If not NULL, updated to point after last converted character. base - Numeric base for conversion.
Result
Returns converted long long integer. On overflow, returns LLONG_MAX or LLONG_MIN and sets errno to ERANGE. Returns 0 if no conversion.
Example
wchar_t *end; long long val = wcstoll(L"123456789LLxyz", &end, 10); // val == 123456789LL, *end == L'x'
Notes
Handles optional whitespace and sign. Base 0 auto-detects hex/octal/decimal.
See also
wcstombs()
Synopsis
size_t wcstombs( char * restrict dest, const wchar_t * restrict src, size_t n)
Function
Converts a null-terminated wide character string (wchar_t*) into its corresponding multibyte string (char*), using the current locale's encoding. At most 'n' bytes are written into 'dest', not including the terminating null byte.
Inputs
dest - Pointer to the destination buffer that receives the converted multibyte string.
If NULL, the function returns the number of bytes that would be written, not
including the null terminator.
src - Pointer to the null-terminated wide character string to convert.
n - Maximum number of bytes to write into 'dest'.
Result
Returns the number of bytes stored in 'dest', excluding the terminating null byte. If a wide character cannot be converted to a valid multibyte sequence, the function returns (size_t)-1 and sets errno to EILSEQ. If 'dest' is NULL, the function returns the number of bytes that would be needed to encode the wide string, excluding the terminating null byte.
Example
wchar_t wstr[] = L"Hello ??!";
char buffer[64];
size_t len = wcstombs(buffer, wstr, sizeof(buffer));
if (len != (size_t)-1) {
// buffer now contains UTF-8-encoded string
}
Notes
stdc.library currently only implements "C" or UTF-8 compatible locale behavior. The encoding is treated as stateless and locale-independent. The terminating null character (L'\0') is converted, but the function does not include it in the returned count.
Bugs
Does not handle stateful encodings or locale-specific behavior. Buffer overflow is possible if 'n' is too small to hold even one multibyte character.
See also
wcstoul()
Synopsis
igned long wcstoul( const wchar_t *nptr, wchar_t **endptr, int base)
Function
Converts the initial part of the wide string nptr to an unsigned long integer according to the specified base or auto-detect if base is 0.
Inputs
nptr - Wide string input. endptr - If not NULL, set to character after last used in conversion. base - Numeric base (0 or 2 to 36).
Result
Returns the converted unsigned long integer. On overflow, returns ULONG_MAX and sets errno to ERANGE. Returns 0 if no conversion.
Example
wchar_t *end; unsigned long val = wcstoul(L"0755abc", &end, 0); // val == 493, *end == L'a'
Notes
Supports optional whitespace and optional plus sign. Base 0 auto-detects.
See also
wcstoull()
Synopsis
igned long long wcstoull( const wchar_t *nptr, wchar_t **endptr, int base)
Function
Converts the initial part of wide string nptr to an unsigned long long integer according to the specified base or auto-detect if base is 0.
Inputs
nptr - Wide string input. endptr - If not NULL, set to the character after last consumed character. base - Numeric base for conversion (0 or 2 to 36).
Result
Returns converted unsigned long long integer. On overflow, returns ULLONG_MAX and sets errno to ERANGE. Returns 0 if no conversion.
Example
wchar_t *end; unsigned long long val = wcstoull(L"18446744073709551615xyz", &end, 10); // val == 18446744073709551615ULL, *end == L'x'
Notes
Supports optional whitespace and plus sign. Base 0 auto-detects.
wcstoumax()
Synopsis
uintmax_t wcstoumax( const wchar_t *nptr, wchar_t **endptr, int base)
Function
Converts a wide-character string of digits into an unsigned integer according to the given base. This function is similar to wcstoul(), but returns a value of type uintmax_t.
Inputs
nptr - Pointer to the wide-character string to be converted.
endptr - If non-NULL, the address of the first character after the
number is stored here.
base - The numeric base for the conversion (e.g., 10 for decimal,
16 for hexadecimal).
Result
The converted numeric value as a uintmax_t. If no valid digits are found, 0 is returned, and if endptr is non-NULL, it is set to nptr.
Example
wchar_t *str = L"FF"; wchar_t *end; uintmax_t value = wcstoumax(str, &end, 16);
Notes
The function does not set errno on overflow or underflow, contrary to the requirements of the C99 standard.
Bugs
errno is not set on range errors as required by the C99 standard.
See also
wcsxfrm()
Synopsis
size_t wcsxfrm( wchar_t *dest, const wchar_t *src, size_t n)
Function
Transforms the wide-character string 'src' into a form suitable for comparison using wcscmp(), and stores it in 'dest'.
Inputs
dest -- destination buffer to store the transformed string src -- source wide-character string n -- maximum number of characters to store in dest
Result
Returns the length of the transformed string (as if no limit was applied), not counting the null terminator.
Notes
This naive implementation simply copies 'src' to 'dest' up to 'n' characters (including the null terminator if space permits). This implementation does not perform locale-specific transformations; it is equivalent to wcsncpy() + wcslen()
wctob()
Synopsis
wctob( wint_t wc) FUNCTION The wctob() function attempts to convert a wide character to a single-byte character, according to the current locale's encoding. The conversion is only successful if the wide character maps to a single byte.
Inputs
wc - A wide character (wint_t) to convert.
Result
Returns the corresponding single-byte character (as an unsigned char) cast to int, or EOF if the character cannot be represented as a single-byte sequence.
Example
int c = wctob(L'A'); // Might return 'A' if in ASCII-compatible locale.
Notes
This function only succeeds for wide characters that map directly to a single byte in the current locale encoding.
Bugs
Fails for wide characters that require multibyte sequences (e.g., most non-ASCII characters in UTF-8).
See also
wctomb()
Synopsis
int wctomb( char *s, wchar_t wc)
Function
Converts a single wide character to its multibyte equivalent and stores it in the buffer pointed to by 's'.
Inputs
s - Pointer to the output buffer to store the resulting multibyte character.
If NULL, the function is called to reset the conversion state.
wc - The wide character to convert.
Result
Returns the number of bytes written into 's' if successful. If 'wc' is the null character (L'\0'), a single null byte is written and 1 is returned. If the wide character cannot be represented as a valid multibyte sequence, -1 is returned and errno is set to EILSEQ. If 's' is NULL, the function does not perform a conversion. Instead, it returns 0 if the encoding is stateless (as with UTF-8), or a non-zero value if the encoding is state-dependent. For UTF-8, 0 is always returned in this case.
Example
wchar_t wc = L'O';
char buf[MB_CUR_MAX];
int len = wctomb(buf, wc);
if (len > 0) {
// buf now contains the multibyte representation of 'wc'
}
Notes
This function is a wrapper around wcrtomb(), using a static internal mbstate_t object to preserve compatibility with C standard behavior. However, since UTF-8 is a stateless encoding, the static state is effectively unused. The function does not support stateful encodings and behaves according to the "C" or UTF-8 locale model only. Behavior is undefined if multibyte encodings require internal state.
Bugs
No locale-specific behavior is supported. No stateful encoding support (e.g., Shift-JIS or ISO 2022).
See also
wctrans()
Synopsis
wctrans_t wctrans( const char *prop)
Function
Returns a value representing a wide character mapping function, such as "tolower" or "toupper", to be used with `towctrans()`.
Inputs
prop - a string specifying the mapping ("tolower", "toupper").
Result
A wctrans_t descriptor for the transformation, or 0 if not recognized.
Example
wctrans_t map = wctrans("toupper");
wchar_t upper = towctrans(L'a', map); // 'A'
See also
wctype()
Synopsis
wctype_t wctype( const char *prop)
Function
Returns a value identifying a wide character classification property, such as "alpha", "digit", or "upper", which can later be used with `iswctype()` to test characters.
Inputs
prop - a null-terminated string naming a wide character class.
Common names include: "alnum", "alpha", "blank", "cntrl",
"digit", "graph", "lower", "print", "punct", "space",
"upper", "xdigit".
Result
Returns a value of type wctype_t if the property name is recognized, or 0 if not.
Example
wctype_t type = wctype("alpha");
if (iswctype(L'Z', type))
{
// is an alpha character
}
Notes
The returned wctype_t value is opaque and must only be used with `iswctype()`.
Bugs
Only a fixed set of property names are recognized. No locale-specific names are currently supported.
See also
wmemchr()
Synopsis
ar_t *wmemchr( const wchar_t *s, wchar_t c, size_t n)
Function
Scans the initial n wide characters of the memory area pointed to by s for the first occurrence of the wide character c.
Inputs
s - Memory area to scan. c - Wide character to locate. n - Number of wide characters to scan.
Result
Returns a pointer to the first occurrence of c within the first n wide characters of s, or NULL if c is not found.
See also
wmemcmp()
Synopsis
wmemcmp( const wchar_t * s1, const wchar_t * s2, size_t n)
Function
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.
Inputs
s1 - Pointer to block of elements of type wchar_t. s2 - Pointer to block of elements of type wchar_t. n - Number of elements of type wchar_t to compare.
Result
Returns an integral value indicating the relationship between the content of the blocks: A zero value indicates that the contents of both memory blocks are equal. A value greater than zero indicates that the first wide character that does not match in both memory blocks has a greater value in ptr1 than in ptr2; And a value less than zero indicates the opposite.
wmemcpy()
Synopsis
ar_t *wmemcpy( wchar_t * restrict s1, const wchar_t * restrict s2, size_t n)
Function
Copies n wide characters from s2 to s1. The memory areas must not overlap.
Inputs
s1 - Destination buffer. s2 - Source buffer. n - Number of wide characters to copy.
Result
Returns s1.
See also
wmemmove()
Synopsis
ar_t *wmemmove( wchar_t *s1, const wchar_t *s2, size_t n)
Function
Copies n wide characters from s2 to s1. The memory areas may overlap.
Inputs
s1 - Destination buffer. s2 - Source buffer. n - Number of wide characters to copy.
Result
Returns s1.
See also
wmemset()
Synopsis
ar_t *wmemset( wchar_t *s, wchar_t c, size_t n)
Function
Copies the value of c into each of the first n wide characters of the object pointed to by s.
Inputs
s - Pointer to the array to fill. c - Value to be set. n - Number of bytes to be set to the value.
Result
Returns the value of s.
wprintf()
Synopsis
int wprintf( const wchar_t * restrict format, ...)
Function
Format a variable list of arguments according to a wide-character format string and print the output to the standard output stream.
Inputs
format - A wide-character printf() format string. ... - Additional arguments matching the format specifiers.
Result
The number of wide characters written to the standard output, or a negative value if an error occurs.
Notes
Equivalent to fwprintf() with stdout as the output stream.
See also
wscanf()
Synopsis
int wscanf( const wchar_t * restrict format, ...)
Function
Reads formatted wide-character input from the standard input stream and stores the results into the provided argument locations.
Inputs
format - How to convert the input into the arguments ... - Write the result in these arguments
Result
The number of converted arguments.
y0()
Synopsis
double y0( double x)
Function
Computes the Bessel function of the second kind of order zero, Y0(x).
Inputs
x - input value, must be positive.
Result
The value of Y0(x).
Example
double val = y0(1.0);
Notes
Domain: x > 0. Returns -inf or NaN for invalid domain inputs.
Bugs
Undefined for x <= 0.
y0f()
Synopsis
float y0f( float x)
Function
Evaluate the Bessel function of the second kind, Y_0(x), of order zero.
Inputs
x - Positive real argument.
Result
An approximation to Y_0(x) as a float. Both signs of zero return negative infinity. Negative values, including negative infinity, return NaN. Positive infinity returns positive zero. NaN returns NaN.
Notes
Include <math.h>. This is a BSD extension. The function does not assign errno. Floating-point exceptions may occur; enabled traps may prevent return. Use round-to-nearest. The trigonometric argument reduction used for large arguments assumes this rounding mode. Zero arguments can raise divide-by-zero; negative arguments can raise invalid.
y1()
Synopsis
double y1( double x)
Function
Computes the Bessel function of the second kind of order one, Y1(x).
Inputs
x - input value, must be positive.
Result
The value of Y1(x).
Example
double val = y1(1.0);
Notes
Domain: x > 0. Returns -inf or NaN for invalid domain inputs.
Bugs
Undefined for x <= 0.
y1f()
Synopsis
float y1f( float x)
Function
Evaluate the Bessel function of the second kind, Y_1(x), of order one.
Inputs
x - Positive real argument.
Result
An approximation to Y_1(x) as a float. Both signs of zero return negative infinity. Negative values, including negative infinity, return NaN. Positive infinity returns positive zero. NaN returns NaN.
Notes
Include <math.h>. This is a BSD extension. The function does not assign errno. Floating-point exceptions may occur; enabled traps may prevent return. Use round-to-nearest. The trigonometric argument reduction used for large arguments assumes this rounding mode. Zero arguments can raise divide-by-zero; negative arguments can raise invalid.
yn()
Synopsis
double yn( int n, double x)
Function
Computes the Bessel function of the second kind (Neumann function) of order `n` at `x`.
Inputs
n - order of the Bessel function (integer). x - the point at which to evaluate. Must be positive.
Result
Returns the value of the Bessel function \( Y_n(x) \). Returns NaN and sets errno to EDOM if `x` < 0. Returns -infinity and sets errno to ERANGE if `x` == 0.
Example
double r = yn(1, 2.0); // Y1(2.0)
Notes
Commonly used in physics for problems with cylindrical symmetry involving singularities.
Bugs
None known.
ynf()
Synopsis
float ynf( int n, float x)
Function
Evaluate the Bessel function of the second kind, Y_n(x), for integer order n.
Inputs
n - Integer order; see BUGS for unsupported extreme orders. x - Positive real argument.
Result
An approximation to Y_n(x) as a float. Negative arguments, including negative infinity, return NaN. NaN returns NaN. Both signs of zero return negative infinity for every n, subject to the negative-order defect below. Positive infinity returns negative zero for n = -1 and positive zero for other supported orders.
Notes
Include <math.h>. This is a BSD extension. The function does not assign errno. Floating-point exceptions may occur; enabled traps may prevent return. Use round-to-nearest. The trigonometric argument reduction used for large arguments assumes this rounding mode. Evaluation time can grow with the magnitude of n. For positive integer m and finite positive x, Y_-m(x) = (-1)^m Y_m(x). Zero arguments can raise divide-by-zero; negative arguments can raise invalid.
Bugs
INT_MIN is not supported for positive arguments: negating this order overflows signed int. Recurrence arithmetic is not protected against overflow for very large orders. For negative odd orders at zero, the returned negative infinity disagrees with the positive-side limit, which is positive infinity. The zero check bypasses the negative-order sign correction.