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
__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.
_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.
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
asctime_r()
Synopsis
char * asctime_r( const struct tm * tm, char * buf)
Function
The asctime_r() function converts the broken-down time value tm
into a string with this format:
"Wed Jun 30 21:49:08 1993\n"
Inputs
tm - The broken down time buf - Buffer of at least 26 characters to store the string in
Result
The pointer passed in buf, containing the converted time. Note that there is a newline at the end of the buffer.
Example
time_t tt; struct tm tm; char str[26]; // Get time time (&tt); // Break time up localtime (&tt, &tm); // Convert to string asctime (&tm, str);
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.
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.
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.
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.
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.
See also
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.
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
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.
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
ctime_r()
Synopsis
char * ctime_r( const time_t * tt, char * buf)
Function
The ctime_r() function converts the time value tt into a string with
this format:
"Wed Jun 30 21:49:08 1993\n"
Inputs
tt - Convert this time. buf - Buffer of at least 26 characters to store the string in
Result
The pointer passed in buf, containing the converted time. Note that there is a newline at the end of the buffer.
Example
time_t tt; char str[26]; // Get time time (&tt); // Convert to string ctime (&tt, str);
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
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
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
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
}
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.
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.
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.
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.
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.
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.
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
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
gmtime_r()
Synopsis
struct tm * gmtime_r( const time_t * tt, struct tm * tm)
Function
The gmtime_r() function converts the calendar time tt (assumed to be UTC) to broken-down time representation, expressed in Coordinated Universal Time (UTC).
Inputs
tt - The time to convert tm - A struct tm to store the result in
Result
The pointer passed in tm, containing the broken down time in Coordinated Universal Time (UTC).
Example
time_t tt; struct tm tm; // Get the time time (&tt); // and convert it gmtime (&tt, &tm);
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.
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.
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.
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.
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.
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
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.
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.
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;
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().
localtime_r()
Synopsis
struct tm * localtime_r( const time_t * tt, struct tm * tm)
Function
The localtime_r() function converts the calendar time tt (assumed to
be UTC) to broken-down time representation, expressed users local
timezone.
The members of the tm structure are:
tm_sec - The number of seconds after the minute, normally in
the range 0 to 59, but can be up to 61 to allow for leap
seconds.
tm_min - The number of minutes after the hour, in the range 0 to 59.
tm_hour - The number of hours past midnight, in the range 0 to 23.
tm_mday - The day of the month, in the range 1 to 31.
tm_mon - The number of months since January, in the range 0 to 11.
tm_year - The number of years since 1900.
tm_wday - The number of days since Sunday, in the range 0 to 6.
tm_yday - The number of days since January 1, in the range 0 to 365.
tm_isdst - A flag that indicates whether daylight saving time
is in effect at the time described. The value is positive
if daylight saving time is in effect, zero if it is not,
and negative if the information is not available.
Inputs
tt - A time in seconds from the 1. Jan 1970 tm - A struct tm to store the result in
Result
The pointer passed in tm.
Example
time_t tt; struct tm tm; // Get time time (&tt); // Break time up localtime_r (&tt, &tm);
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.
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.
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.
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.
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.
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
malloc_align()
Synopsis
void *malloc_align( size_t size, size_t alignment)
Function
Allocate aligned memory.
Inputs
size - How much memory to allocate.
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 *).
Result
A pointer to the allocated memory or NULL.
Notes
errno is set to EINVAL if the alignment parameter was not a power of two, or was not a multiple of sizeof(void *). errno is set to ENOMEM if there was insufficient memory to fulfill the request. Memory allocated by malloc_align() should be freed with free(). If not, it will be freed when the program terminates. This function is AROS specific.
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. The encoding is stateless; mbstate_t is unused.
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
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.
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);
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);
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.
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
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
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
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
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.
Notes
Implemented but no interrupts will be generated like when pressing Ctrl-C; signal handlers can for now only be called by raise() in the program itself.
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.
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)
Notes
Function does not take localization into account at the moment
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.
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]; char **bufptr strcpy (buffer, "Hello, this is a test."); *bufptr = buffer // First word. Returns "Hello" strtok (bufptr, " \t,."); // Next word. Returns "this" strtok (bufptr, " \t,."); // Next word. Returns "is" strtok (bufptr, " \t"); // Next word. Returns "a" strtok (bufptr, " \t"); // Next word. Returns "test." strtok (bufptr, " \t"); // Next word. Returns NULL. strtok (bufptr, " \t");
Notes
The function changes str !
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.
Bugs
NAN is not handled at the moment
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 !
strtok_r()
Synopsis
char * strtok_r( char * str, const char * sep, char **saveptr)
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.
saveptr - internal context for next scan
Result
The first word in str or the next one if str is NULL.
Example
char buffer[64]; char *ptr; strcpy (buffer, "Hello, this is a test."); // Init. Returns "Hello" strtok_r (str, " \t,.", &ptr); // Next word. Returns "this" strtok_r (NULL, " \t,.", &ptr); // Next word. Returns "is" strtok_r (NULL, " \t", &ptr); // Next word. Returns "a" strtok_r (NULL, " \t", &ptr); // Next word. Returns "test." strtok_r (NULL, " \t", &ptr); // Next word. Returns NULL. strtok_r (NULL, " \t", &ptr);
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.
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
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.
See also
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.
See also
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.
See also
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.
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.
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.
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.
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.
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 * restrict s1, const wchar_t * restrict s2, size_t n)
Function
Appends not more than n wide characters from the array pointed to by s2 to the end of the wide string pointed to by s1.
Inputs
s1 - specifies the pointer to the destination array. s2 - specifies the string to be added to the destination. n - specifies the maximum number of wide characters to be added.
Result
Returns the value of s1.
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 *s1, const wchar_t *s2)
Function
Locate characters s2 in wide string s1.
Inputs
s1 - wide string to be scanned. s2 - wide string containing the characters to match.
Result
Returns a pointer to the wide character in s1, or a null pointer if no wide character from s2 occurs in s1.
wcsrchr()
Synopsis
ar_t *wcsrchr( const wchar_t *s, wchar_t c)
Function
Locates the last occurrence of c in the wide string pointed to by s.
Inputs
s - wide string. c - wide character to be located.
Result
Returns a pointer to the last occurrence of c in s.
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.
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.
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
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
Locates the first occurrence of c in the initial n wide characters of the object pointed to by s. .
Inputs
s - Pointer to the array of wchar_t elements to be searched. c - Wide character to be located. n - Number of elements of type wchar_t to compare.
Result
Returns a pointer to the located wide character, or a null pointer if the wide character does not occur in the object.
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 the object pointed to by s2 to the object pointed to by s1.
Inputs
s1 - Pointer to the destination array where the content is to be copied. s2 - Pointer to the source of data to be copied. n - Number of bytes to copy.
Result
Returns the value of s1.
wmemmove()
Synopsis
ar_t *wmemmove( wchar_t *s1, const wchar_t *s2, size_t n)
Function
Copies n wide characters from the object pointed to by s2 to the object pointed to by s1. Copying takes place as if an intermediate buffer were used, allowing the destination and source to overlap
Inputs
s1 - Pointer to the destination array where the content is to be copied. s2 - Pointer to the source of data to be copied. n - Number of elements of type wchar_t to copy.
Result
Returns the value of s1.
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.
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.
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.
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.