====
stdc
====

.. This document is automatically generated. Don't edit it!

`Index <index>`_

----------

======================================= ======================================= ======================================= ======================================= 
`--background_C99--`_                   `--background_locale--`_                `--background_string--`_                `--background_wchar--`_                 
`__assert()`_                           `__assert()`_                           `__cxa_atexit()`_                       `__cxa_finalize()`_                     
`__progonly__Exit()`_                   `__progonly_abort()`_                   `__progonly_atexit()`_                  `__progonly_exit()`_                    
`__progonly_on_exit()`_                 `__stdc_get_errorptr()`_                `__stdc_gmtoffset()`_                   `__stdc_jmp2exit()`_                    
`__stdc_program_end()`_                 `__stdc_program_startup()`_             `__stdc_set_errorptr()`_                `__stdc_set_exitjmp()`_                 
`__stdc_strerror()`_                    `__stdcio_get_environptr()`_            `__stdcio_get_envlistptr()`_            `__stdcio_set_environptr()`_            
`__stdcio_set_envlistptr()`_            `__vcformat()`_                         `__vwformat()`_                         `__vwscanf()`_                          
`__wvcformat()`_                        `abs()`_                                `acos()`_                               `acosf()`_                              
`acosh()`_                              `acoshf()`_                             `acoshl()`_                             `acosl()`_                              
`aligned_alloc()`_                      `asctime()`_                            `asctime_r()`_                          `asin()`_                               
`asinf()`_                              `asinh()`_                              `asinhf()`_                             `asinl()`_                              
`asprintf()`_                           `assert()`_                             `atan()`_                               `atan2()`_                              
`atan2f()`_                             `atan2l()`_                             `atanf()`_                              `atanh()`_                              
`atanhf()`_                             `atanhl()`_                             `atanl()`_                              `atof()`_                               
`atoi()`_                               `atol()`_                               `atoll()`_                              `bsearch()`_                            
`btowc()`_                              `cabs()`_                               `cabsf()`_                              `cabsl()`_                              
`calloc()`_                             `cbrt()`_                               `cbrtf()`_                              `cbrtl()`_                              
`ceil()`_                               `ceilf()`_                              `ceill()`_                              `clearerr()`_                           
`clock()`_                              `cos()`_                                `cosf()`_                               `cosh()`_                               
`coshf()`_                              `coshl()`_                              `cosl()`_                               `ctime()`_                              
`ctime_r()`_                            `difftime()`_                           `div()`_                                `erf()`_                                
`erfc()`_                               `erfcf()`_                              `erfcl()`_                              `erfclf()`_                             
`erff()`_                               `erfl()`_                               `exp()`_                                `exp10()`_                              
`exp10f()`_                             `expf()`_                               `expl()`_                               `expm1()`_                              
`expm1f()`_                             `fabs()`_                               `fabsf()`_                              `fabsl()`_                              
`fclose()`_                             `feof()`_                               `ferror()`_                             `fflush()`_                             
`fgetc()`_                              `fgetpos()`_                            `fgets()`_                              `fgetwc()`_                             
`fgetws()`_                             `floor()`_                              `floorf()`_                             `floorl()`_                             
`fmod()`_                               `fmodf()`_                              `fmodl()`_                              `fopen()`_                              
`fprintf()`_                            `fputc()`_                              `fputs()`_                              `fputwc()`_                             
`fputws()`_                             `fread()`_                              `free()`_                               `freopen()`_                            
`frexp()`_                              `fscanf()`_                             `fseek()`_                              `fsetpos()`_                            
`ftell()`_                              `fwide()`_                              `fwprintf()`_                           `fwrite()`_                             
`fwscanf()`_                            `gamma()`_                              `getc()`_                               `getchar()`_                            
`getenv()`_                             `gets()`_                               `getwchar()`_                           `gmtime()`_                             
`gmtime_r()`_                           `hypot()`_                              `hypotf()`_                             `hypotl()`_                             
`imaxabs()`_                            `imaxdiv()`_                            `isalnum()`_                            `isalpha()`_                            
`isascii()`_                            `isblank()`_                            `iscntrl()`_                            `isdigit()`_                            
`isgraph()`_                            `islower()`_                            `isprint()`_                            `ispunct()`_                            
`isspace()`_                            `isupper()`_                            `iswctype()`_                           `isxdigit()`_                           
`j0()`_                                 `j1()`_                                 `jn()`_                                 `labs()`_                               
`ldexp()`_                              `ldiv()`_                               `lgamma()`_                             `lgammal()`_                            
`llabs()`_                              `lldiv()`_                              `localeconv()`_                         `localtime()`_                          
`localtime_r()`_                        `log()`_                                `log10()`_                              `log10l()`_                             
`log1p()`_                              `log1pl()`_                             `log2()`_                               `log2l()`_                              
`logl()`_                               `malloc()`_                             `malloc_align()`_                       `mblen()`_                              
`mbrlen()`_                             `mbrlen()`_                             `mbrtowc()`_                            `mbrtowc()`_                            
`mbsrtowcs()`_                          `mbsrtowcs()`_                          `mbstowcs()`_                           `mbtowc()`_                             
`memchr()`_                             `memcmp()`_                             `memcpy()`_                             `memmove()`_                            
`memset()`_                             `mktime()`_                             `modf()`_                               `modff()`_                              
`modfl()`_                              `perror()`_                             `pow()`_                                `powf()`_                               
`powl()`_                               `printf()`_                             `putc()`_                               `putchar()`_                            
`puts()`_                               `putwchar()`_                           `qsort()`_                              `raise()`_                              
`rand()`_                               `realloc()`_                            `realloc_nocopy()`_                     `remainder()`_                          
`remainderf()`_                         `remove()`_                             `remquo()`_                             `remquol()`_                            
`rename()`_                             `rewind()`_                             `scanf()`_                              `setbuf()`_                             
`setlocale()`_                          `setvbuf()`_                            `signal()`_                             `sin()`_                                
`sinf()`_                               `sinh()`_                               `sinhf()`_                              `sinhl()`_                              
`sinl()`_                               `snprintf()`_                           `sprintf()`_                            `sqrt()`_                               
`sqrtf()`_                              `sqrtl()`_                              `srand()`_                              `sscanf()`_                             
`stccpy()`_                             `stcd_l()`_                             `stch_l()`_                             `stcl_d()`_                             
`stcl_h()`_                             `stcl_o()`_                             `stco_l()`_                             `stcu_d()`_                             
`stpblk()`_                             `stpcpy()`_                             `stpsym()`_                             `strcasecmp()`_                         
`strcasestr()`_                         `strcat()`_                             `strchr()`_                             `strcmp()`_                             
`strcoll()`_                            `strcpy()`_                             `strcspn()`_                            `strdup()`_                             
`strftime()`_                           `strlcat()`_                            `strlcpy()`_                            `strlen()`_                             
`strlwr()`_                             `strncasecmp()`_                        `strncat()`_                            `strncmp()`_                            
`strncpy()`_                            `strndup()`_                            `strnlen()`_                            `strpbrk()`_                            
`strrchr()`_                            `strrev()`_                             `strsep()`_                             `strspn()`_                             
`strstr()`_                             `strtod()`_                             `strtof()`_                             `strtoimax()`_                          
`strtok()`_                             `strtok_r()`_                           `strtol()`_                             `strtold()`_                            
`strtoll()`_                            `strtoul()`_                            `strtoull()`_                           `strtoumax()`_                          
`strupr()`_                             `strxfrm()`_                            `swprintf()`_                           `swscanf()`_                            
`system()`_                             `tan()`_                                `tanf()`_                               `tanh()`_                               
`tanhf()`_                              `tanhl()`_                              `tanl()`_                               `tgamma()`_                             
`tgammal()`_                            `time()`_                               `tmpfile()`_                            `tmpnam()`_                             
`towctrans()`_                          `towlower()`_                           `towupper()`_                           `trunc()`_                              
`truncf()`_                             `truncl()`_                             `ungetc()`_                             `ungetwc()`_                            
`vasprintf()`_                          `vfprintf()`_                           `vfscanf()`_                            `vfwprintf()`_                          
`vfwscanf()`_                           `vprintf()`_                            `vscanf()`_                             `vsnprintf()`_                          
`vsprintf()`_                           `vsscanf()`_                            `vswprintf()`_                          `vswscanf()`_                           
`vwprintf()`_                           `vwscanf()`_                            `wcrtomb()`_                            `wcrtomb()`_                            
`wcscat()`_                             `wcschr()`_                             `wcschr()`_                             `wcscmp()`_                             
`wcscpy()`_                             `wcscspn()`_                            `wcsftime()`_                           `wcslen()`_                             
`wcsncat()`_                            `wcsncat()`_                            `wcsncmp()`_                            `wcsncpy()`_                            
`wcsnrtombs()`_                         `wcspbrk()`_                            `wcspbrk()`_                            `wcsrchr()`_                            
`wcsrchr()`_                            `wcsrtombs()`_                          `wcsrtombs()`_                          `wcsspn()`_                             
`wcsstr()`_                             `wcstod()`_                             `wcstof()`_                             `wcstok()`_                             
`wcstol()`_                             `wcstold()`_                            `wcstombs()`_                           `wcstoul()`_                            
`wcsxfrm()`_                            `wctob()`_                              `wctomb()`_                             `wctrans()`_                            
`wctype()`_                             `wmemchr()`_                            `wmemcmp()`_                            `wmemcpy()`_                            
`wmemmove()`_                           `wmemset()`_                            `wprintf()`_                            `wscanf()`_                             
`y0()`_                                 `y1()`_                                 `yn()`_                                 
======================================= ======================================= ======================================= ======================================= 

-----------

--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 </documentation/headerfiles/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()`_ 

----------

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

`assert()`_ 

----------

__cxa_atexit()
==============

Synopsis
~~~~~~~~
::

  int __cxa_atexit(
     void (*func)(void *, int),
     void *arg,
     void *d)


Function
~~~~~~~~
::

     Registers a cleanup function to be called when the program terminates
     via exit() or when a shared object (DSO) is unloaded.

     This function is primarily used by C++ compilers to handle destruction
     of static and global objects associated with shared libraries.


Inputs
~~~~~~
::

     func - Pointer to the function to be called on exit or unload.
            The function must accept a void pointer and an int as arguments.
     arg  - Argument to be passed to the function when it is called.
     d    - The DSO handle with which the function is associated.


Result
~~~~~~
::

     Returns 0 on success, or -1 if there is insufficient memory to
     register the function.


Example
~~~~~~~
::


     void my_cleanup(void *arg, int status) {
         // Perform cleanup
     }

     __cxa_atexit(my_cleanup, my_data, my_dso_handle);


Notes
~~~~~
::

     The function is called with (arg, status) arguments, where status
     is usually zero. The `d` parameter is used to manage which functions
     to call when a specific shared object is unloaded.


Bugs
~~~~
::

     This function is not intended for use in user code; it is called
     automatically by the C++ runtime.



See also
~~~~~~~~

`atexit()`_ `exit()`_ `__cxa_finalize()`_ 

----------

__cxa_finalize()
================

Synopsis
~~~~~~~~
::

  void __cxa_finalize(
     void *d)


Function
~~~~~~~~
::

     Call all functions registered via __cxa_atexit() that match the
     specified DSO handle. If the handle is NULL, all registered functions
     are called in reverse order of registration.

     This is typically called automatically when a shared object is
     unloaded or during normal process termination to run global destructors.


Inputs
~~~~~~
::

     d - Dynamic shared object (DSO) handle, or NULL to finalize all.


Result
~~~~~~
::

     None.


Notes
~~~~~
::

     This function is part of the C++ runtime support and is not meant to be
     called by user code. It is invoked by the runtime to clean up static or
     global objects.


Bugs
~~~~
::

     AROS doesnt support Dynamic shared objects, so the DSO handle will
     always be NULL.



See also
~~~~~~~~

`__cxa_atexit()`_ `exit()`_ `atexit()`_ 

----------

__progonly__Exit()
==================

Synopsis
~~~~~~~~
::

  void __progonly__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
~~~~~~~~

`exit()`_ 

----------

__progonly_abort()
==================

Synopsis
~~~~~~~~
::

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



See also
~~~~~~~~

`signal()`_ `exit()`_ 

----------

__progonly_atexit()
===================

Synopsis
~~~~~~~~
::

  int __progonly_atexit(
     void (*func)(void))


Function
~~~~~~~~
::

     Registers the given function to be called at normal
     process termination.
     

Inputs
~~~~~~
::

     func - function to be called.



See also
~~~~~~~~

`exit()`_ 

----------

__progonly_exit()
=================

Synopsis
~~~~~~~~
::

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



See also
~~~~~~~~

`atexit()`_ `on_exit()`_ 

----------

__progonly_on_exit()
====================

Synopsis
~~~~~~~~
::

  int __progonly_on_exit(
     void (*func)(int, void *),
     void *arg)



----------

__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



----------

__stdc_strerror()
=================

Synopsis
~~~~~~~~
::

  char * __stdc_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.



----------

__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_set_environptr()`_ 

----------

__stdcio_get_envlistptr()
=========================

Synopsis
~~~~~~~~
::

  char ***__stdcio_get_envlistptr(
     void)


Inputs
~~~~~~
::

     -


Notes
~~~~~
::

     Private - do not use!



See also
~~~~~~~~

`__stdcio_set_envlistptr()`_ 

----------

__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_get_environptr()`_ `getenv()`_ `setenv()`_ 

----------

__stdcio_set_envlistptr()
=========================

Synopsis
~~~~~~~~
::

  int __stdcio_set_envlistptr(
     char ***envlistptr)


Notes
~~~~~
::

     Private - do not use!



See also
~~~~~~~~

`__stdcio_get_envlistptr()`_ 

----------

__vcformat()
============

Synopsis
~~~~~~~~
::

  int __vcformat(
     void       * data,
     int       (* outc)(int, void *),
     const char * format,
     va_list      args)


Function
~~~~~~~~
::

     Format a list of arguments and call a function for each char
     to print.


Inputs
~~~~~~
::

     data - This is passed to the user callback outc as its second argument.
     outc - Call this function for every character that should be
             emitted. The function should return EOF on error and
             > 0 otherwise.
     format - A printf() format string.
     args - A list of arguments for the format string.


Result
~~~~~~
::

     The number of characters written.



----------

__vwformat()
============

Synopsis
~~~~~~~~
::

  int __vwformat(
     void          * data,
     wint_t       (* outwc)(wchar_t, void *),
     const wchar_t * format,
     va_list         args)


Function
~~~~~~~~
::

     Formats a list of arguments according to the provided wide-character
     format string and emits each resulting wide character through a
     callback function.


Inputs
~~~~~~
::

     data   - A user-supplied pointer passed as the second argument to
              the outwc() callback function.
     outwc  - A callback function invoked for each wide character to output.
              The callback receives the character and the data pointer.
              It should return EOF on error or a positive value on success.
     format - A wide-character printf() format string containing
              formatting directives.
     args   - A va_list containing the arguments for the format string.


Result
~~~~~~
::

     The number of wide characters successfully written, or a negative
     value on error.


Notes
~~~~~
::

     This is a generic backend used to implement wide-character printf
     functions. It handles parsing of printf-style format specifiers
     and passes formatted output one character at a time to the caller's
     output function.


Bugs
~~~~
::

     Some format specifiers may not yet be implemented or fully support
     wide-character variations.



See also
~~~~~~~~

`swprintf()`_ `vswprintf()`_ `fwprintf()`_ `vfwprintf()`_ `wprintf()`_ `vwprintf()`_ 

----------

__vwscanf()
===========

Synopsis
~~~~~~~~
::

  int __vwscanf(
     void       * data,
     wint_t    (* get_wchar)(void *),
     int       (* unget_wchar)(wint_t, void *),
     const wchar_t * format,
     va_list      args)


Function
~~~~~~~~
::

     Core wide-character scanf parser. Reads formatted wide-character input
     from the data source using the provided get/unget character functions,
     parsing according to the given format string, and stores the results
     into the locations described by the argument list.


Inputs
~~~~~~
::

     data       - Opaque pointer passed to get_wchar and unget_wchar
     get_wchar   - Function to read the next character from the input
     unget_wchar - Function to push back a character into the input
     format     - How to convert the input into the arguments
     args       - List of argument pointers to receive results


Result
~~~~~~
::

     The number of converted arguments.



See also
~~~~~~~~

`vwscanf()`_ 

----------

__wvcformat()
=============

Synopsis
~~~~~~~~
::

  int __wvcformat(
     void       * data,
     int       (* outc)(int, void *),
     const wchar_t * 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 wprintf() format string.
     args - A list of arguments for the format string.


Result
~~~~~~
::

     The number of characters written.



----------

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



See also
~~~~~~~~

`labs()`_ `llabs()`_ 

----------

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.



See also
~~~~~~~~

`acosf()`_ `asin()`_ `atan()`_ 

----------

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.



See also
~~~~~~~~

`acos()`_ `asinf()`_ `atanf()`_ 

----------

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.



See also
~~~~~~~~

`acoshf()`_ `asinh()`_ `cosh()`_ 

----------

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.



See also
~~~~~~~~

`acosh()`_ `asinhf()`_ `coshf()`_ 

----------

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.



See also
~~~~~~~~

`cosh()`_ `asinh()`_ `atanh()`_ `acoshf()`_ `acosh()`_ 

----------

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.



See also
~~~~~~~~

`cos()`_ `asin()`_ `atan()`_ `acosf()`_ `acosl()`_ 

----------

aligned_alloc()
===============

Synopsis
~~~~~~~~
::

  void *aligned_alloc(
     size_t alignment,
     size_t size)


Function
~~~~~~~~
::

     Allocate aligned memory.


Inputs
~~~~~~
::

     alignment - Alignment of allocated memory. The address of the
                 allocated memory will be a multiple of this value, which
                 must be a power of two and a multiple of sizeof(void *).
     size - How much memory to allocate.


Result
~~~~~~
::

     Returns zero on success.
     Returns EINVAL if the alignment parameter was not a power of two, or
     was not a multiple of sizeof(void *).
     Returns ENOMEM if there was insufficient memory to fulfill the request.


Notes
~~~~~
::

     Memory allocated by aligned_alloc() should be freed with free(). If
     not, it will be freed when the program terminates.

     If an error occurs, errno will not be set.



See also
~~~~~~~~

`calloc()`_ `free()`_ `malloc()`_ 

----------

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

`time()`_ `ctime()`_ `gmtime()`_ `localtime()`_ 

----------

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

`time()`_ `ctime_r()`_ `gmtime_r()`_ `localtime_r()`_ 

----------

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.



See also
~~~~~~~~

`asinf()`_ `acos()`_ `atan()`_ 

----------

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.



See also
~~~~~~~~

`asin()`_ `acosf()`_ `atanf()`_ 

----------

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.



See also
~~~~~~~~

`asinhf()`_ `sinh()`_ `log()`_ 

----------

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.



See also
~~~~~~~~

`asinh()`_ `sinhf()`_ 

----------

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.



See also
~~~~~~~~

`sin()`_ `acos()`_ `atan()`_ `asinf()`_ `asinl()`_ 

----------

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

`vasprintf()`_ `sprintf()`_ `vsprintf()`_ 

----------

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.



See also
~~~~~~~~

`atanf()`_ `atan2()`_ `tan()`_ 

----------

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.



See also
~~~~~~~~

`atan()`_ `atan2f()`_ `tan()`_ 

----------

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.



See also
~~~~~~~~

`atan()`_ `atan2()`_ `tanf()`_ 

----------

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.



See also
~~~~~~~~

`atan2()`_ `atan()`_ `atan2f()`_ 

----------

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.



See also
~~~~~~~~

`atan()`_ `atan2f()`_ `tanf()`_ 

----------

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.



See also
~~~~~~~~

`atanhf()`_ `tanh()`_ 

----------

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.



See also
~~~~~~~~

`tanhf()`_ `asinhf()`_ `acoshf()`_ 

----------

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.



See also
~~~~~~~~

`tanh()`_ `asinh()`_ `acosh()`_ `atanhf()`_ `atanhl()`_ 

----------

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.



See also
~~~~~~~~

`atan()`_ `atan2l()`_ 

----------

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.



See also
~~~~~~~~

`atoi()`_ `atol()`_ `strtod()`_ `strtol()`_ `strtoul()`_ 

----------

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



See also
~~~~~~~~

`atof()`_ `atol()`_ `strtod()`_ `strtol()`_ `strtoul()`_ 

----------

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



See also
~~~~~~~~

`atof()`_ `atoi()`_ `strtod()`_ `strtol()`_ `strtoul()`_ 

----------

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



See also
~~~~~~~~

`atof()`_ `atoi()`_ `atol()`_ `strtod()`_ `strtol()`_ `strtoul()`_ 

----------

bsearch()
=========

Synopsis
~~~~~~~~
::

  void * bsearch(
     const void * key,
     const void * base,
     size_t       count,
     size_t       size,
     int       (* comparefunction)(const void *, const void *))


Function
~~~~~~~~
::

     Search in a sorted array for an entry key.


Inputs
~~~~~~
::

     key - Look for this key.
     base - This is the address of the first element in the array
             to be searched. Note that the array *must* be sorted.
     count - The number of elements in the array
     size - The size of one element
     comparefunction - The function which is called when two elements
             must be compared. The function gets the addresses of two
             elements of the array and must return 0 is both are equal,
             < 0 if the first element is less than the second and > 0
             otherwise.


Result
~~~~~~
::

     A pointer to the element which equals key in the array or NULL if
     no such element could be found.



----------

btowc()
=======

Synopsis
~~~~~~~~
::

  t_t btowc(
     int c)

   FUNCTION
     The btowc() function converts a single byte character (in the range
     of unsigned char) to its corresponding wide character representation,
     according to the current multibyte encoding in the current locale.

     If the input is EOF or does not correspond to a valid single-byte
     multibyte character, WEOF is returned.


Inputs
~~~~~~
::

     c - A single byte character as an int (must be representable as
         unsigned char or EOF).


Result
~~~~~~
::

     Returns the corresponding wide character (wint_t) if the conversion
     succeeds. Returns WEOF if the input is EOF or an invalid multibyte
     sequence.


Example
~~~~~~~
::

     wint_t wc = btowc((int)'A');


Notes
~~~~~
::

     This function only works for single-byte multibyte characters. It is
     intended to be used with byte input where the encoding may vary
     depending on the locale.

     It uses mbrtowc() internally with a zero-initialized conversion state.


Bugs
~~~~
::

     If called with a multibyte encoding that requires more than one byte
     per character (e.g., UTF-8 for non-ASCII), this function will fail
     for non-ASCII characters.



See also
~~~~~~~~

`wctob()`_ `mbrtowc()`_ `setlocale()`_ 

----------

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.



See also
~~~~~~~~

`cabsf()`_ `cabsl()`_ 

----------

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

`hypotf()`_ 

----------

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.



See also
~~~~~~~~

`cabs()`_ `cabsf()`_ 

----------

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.



See also
~~~~~~~~

`free()`_ `malloc()`_ 

----------

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.



See also
~~~~~~~~

`cbrtf()`_ `pow()`_ 

----------

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.



See also
~~~~~~~~

`cbrt()`_ `powf()`_ 

----------

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.



See also
~~~~~~~~

`sqrtl()`_ `powl()`_ 

----------

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.



See also
~~~~~~~~

`floor()`_ `trunc()`_ 

----------

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

`floorf()`_ `roundf()`_ `truncf()`_ 

----------

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.



See also
~~~~~~~~

`floorl()`_ `truncl()`_ 

----------

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

`ferror()`_ `clearerr()`_ 

----------

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

`time()`_ 

----------

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.



See also
~~~~~~~~

`cosf()`_ `sin()`_ `tan()`_ 

----------

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.



See also
~~~~~~~~

`cos()`_ `sinf()`_ `tanf()`_ 

----------

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.



See also
~~~~~~~~

`coshf()`_ `sinh()`_ `tanh()`_ 

----------

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.



See also
~~~~~~~~

`cosh()`_ `sinhf()`_ `tanhf()`_ 

----------

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.



See also
~~~~~~~~

`sinhl()`_ `tanhl()`_ `cosl()`_ 

----------

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.



See also
~~~~~~~~

`sin()`_ `tan()`_ `cosf()`_ `cosl()`_ 

----------

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

`time()`_ `asctime()`_ `gmtime()`_ `localtime()`_ 

----------

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

`time()`_ `asctime_r()`_ `gmtime_r()`_ `localtime_r()`_ 

----------

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

`time()`_ `ctime()`_ `asctime()`_ `localtime()`_ 

----------

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

`ldiv()`_ 

----------

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.



See also
~~~~~~~~

`erfc()`_ `erfcf()`_ `erfl()`_ 

----------

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.



See also
~~~~~~~~

`erf()`_ `erfcf()`_ `erfcl()`_ 

----------

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.



See also
~~~~~~~~

`erfc()`_ `erff()`_ `erfclf()`_ 

----------

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.



See also
~~~~~~~~

`erfl()`_ `erf()`_ `erfclf()`_ 

----------

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.



See also
~~~~~~~~

`erfcf()`_ `erf()`_ 

----------

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.



See also
~~~~~~~~

`erfcf()`_ `erf()`_ 

----------

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.



See also
~~~~~~~~

`erf()`_ `erfcl()`_ 

----------

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.



See also
~~~~~~~~

`expf()`_ `expm1()`_ 

----------

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.



See also
~~~~~~~~

`exp()`_ `pow()`_ 

----------

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.



See also
~~~~~~~~

`expf()`_ `powf()`_ 

----------

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.



See also
~~~~~~~~

`exp()`_ `expm1f()`_ 

----------

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.



See also
~~~~~~~~

`expm1()`_ `log()`_ `expf()`_ `expl()`_ 

----------

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.



See also
~~~~~~~~

`exp()`_ `expm1f()`_ 

----------

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.



See also
~~~~~~~~

`expf()`_ `expm1()`_ 

----------

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.



See also
~~~~~~~~

`fabsf()`_ `fabsl()`_ 

----------

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

`fabs()`_ 

----------

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.



See also
~~~~~~~~

`fabs()`_ `fabsf()`_ 

----------

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

`fopen()`_ 

----------

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()`_ `clearerr()`_ 

----------

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

`ferror()`_ `clearerr()`_ 

----------

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.



See also
~~~~~~~~

`getc()`_ `feof()`_ `ferror()`_ `fputc()`_ `putc()`_ 

----------

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

`fsetpos()`_ 

----------

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
     }



See also
~~~~~~~~

`fopen()`_ `gets()`_ `fputs()`_ `putc()`_ 

----------

fgetwc()
========

Synopsis
~~~~~~~~
::

  wint_t fgetwc(
     FILE * stream)


Function
~~~~~~~~
::

     Read the next wide character from the specified stream.
     Supports UTF-8 decoding if the stream is byte-oriented.
     Returns a pushed-back wide character if present via ungetwc.


Inputs
~~~~~~
::

     stream - Pointer to the input stream.


Result
~~~~~~
::

     Returns the next wide character as a wint_t.
     Returns WEOF on end-of-file or error.


Notes
~~~~~
::

     The function handles UTF-8 sequences up to 4 bytes.
     If a wide character has been pushed back with ungetwc, it is returned first.



See also
~~~~~~~~

`ungetwc()`_ `fputwc()`_ `fwide()`_ 

----------

fgetws()
========

Synopsis
~~~~~~~~
::

  wchar_t *fgetws(
     wchar_t *ws,
     int n,
     FILE *stream)


Function
~~~~~~~~
::

     Reads a wide-character string from the specified stream.
     Converts UTF-8 input bytes to wide characters and stores up to n-1 wide characters.
     Null-terminates the string.


Inputs
~~~~~~
::

     ws - Buffer to store the wide string.
     n - Maximum number of wide characters to read (including null terminator).
     stream - Input stream to read from.


Result
~~~~~~
::

     Returns ws on success, or NULL on error or end of file.


Notes
~~~~~
::

     Handles UTF-8 decoding and stream buffering.



See also
~~~~~~~~

`fgets()`_ `fgetwc()`_ 

----------

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.



See also
~~~~~~~~

`ceil()`_ `trunc()`_ 

----------

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.



See also
~~~~~~~~

`ceilf()`_ `truncf()`_ 

----------

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.



See also
~~~~~~~~

`ceill()`_ `truncl()`_ 

----------

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

`remainder()`_ `fmodf()`_ `fmodl()`_ 

----------

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

`remainderf()`_ 

----------

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.



See also
~~~~~~~~

`fmod()`_ `fmodf()`_ 

----------

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.



See also
~~~~~~~~

`fclose()`_ `fread()`_ `fwrite()`_ `fgets()`_ `fgetc()`_ `fputs()`_ `fputc()`_ 

----------

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.



See also
~~~~~~~~

`puts()`_ `fputc()`_ `putc()`_ 

----------

fputwc()
========

Synopsis
~~~~~~~~
::

  wint_t fputwc(
     wint_t wc,
     FILE * stream)


Function
~~~~~~~~
::

     Write a wide character to the specified stream.
     Converts the wide character to UTF-8 and writes the byte sequence.


Inputs
~~~~~~
::

     wc - Wide character to write.
     stream - Pointer to the output stream.


Result
~~~~~~
::

     Returns the wide character written, or WEOF on error.


Notes
~~~~~
::

     Handles conversion from wchar_t (Unicode code point) to UTF-8.



See also
~~~~~~~~

`fputws()`_ `putwc()`_ 

----------

fputws()
========

Synopsis
~~~~~~~~
::

  wint_t fputws(
     const wchar_t *ws,
     FILE *stream)


Function
~~~~~~~~
::

     Write a wide-character string to the specified stream.
     Converts each wide character to UTF-8 and writes the sequence of bytes.


Inputs
~~~~~~
::

     ws - Pointer to the null-terminated wide-character string to write.
     stream - Pointer to the output stream.


Result
~~~~~~
::

     Returns a non-negative number on success, or WEOF on error.


Notes
~~~~~
::

     The null terminator is not written.
     Uses fputwc internally for each wide character.



See also
~~~~~~~~

`fputwc()`_ `fwrite()`_ 

----------

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.



See also
~~~~~~~~

`fopen()`_ `fwrite()`_ 

----------

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

`malloc()`_ 

----------

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.



See also
~~~~~~~~

`fopen()`_ `fclose()`_ 

----------

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.



See also
~~~~~~~~

`ldexp()`_ `modf()`_ 

----------

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

`scanf()`_ 

----------

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



See also
~~~~~~~~

`fopen()`_ `fwrite()`_ 

----------

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

`fgetpos()`_ 

----------

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.



See also
~~~~~~~~

`fopen()`_ `fseek()`_ `fwrite()`_ 

----------

fwide()
=======

Synopsis
~~~~~~~~
::

  int fwide(
     FILE *stream,
     int mode)


Function
~~~~~~~~
::

     Sets or queries the orientation of the given stream for wide or byte I/O.
     If mode > 0, sets stream orientation to wide-character.
     If mode < 0, sets stream orientation to byte-oriented.
     If mode == 0, returns current orientation without changing it.


Inputs
~~~~~~
::

     stream - The stream to query or set orientation.
     mode - Orientation mode to set or 0 to query.


Result
~~~~~~
::

     Returns positive value if stream is wide-oriented,
     negative if byte-oriented,
     or 0 if no orientation is set.


Notes
~~~~~
::

     Orientation is locked after first I/O operation.



See also
~~~~~~~~

`fgetwc()`_ `fputwc()`_ 

----------

fwprintf()
==========

Synopsis
~~~~~~~~
::

  int fwprintf(
     struct __sFILE * restrict stream,
     const wchar_t * restrict format,
     ...)


Function
~~~~~~~~
::

     Format a variable list of arguments according to a wide-character
     format string and write the output to the given stream.


Inputs
~~~~~~
::

     stream - Output stream.
     format - A wide-character printf() format string.
     ...    - Additional arguments matching the format specifiers.


Result
~~~~~~
::

     The number of wide characters written to the stream, or a negative
     value if an error occurs.


Notes
~~~~~
::

     This function uses wide-character output and formatting, similar to
     printf(), but targeting wchar_t output streams.



See also
~~~~~~~~

`vfwprintf()`_ `wprintf()`_ `vwprintf()`_ `swprintf()`_ `vswprintf()`_ 

----------

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.



See also
~~~~~~~~

`fopen()`_ `fwrite()`_ 

----------

fwscanf()
=========

Synopsis
~~~~~~~~
::

  int fwscanf(
     FILE       * restrict stream,
     const wchar_t * restrict format,
     ...)


Function
~~~~~~~~
::

     Reads formatted wide-character input from the given file stream
     and stores the results into the provided argument locations.


Inputs
~~~~~~
::

     stream - Read from this wide-character file stream
     format - How to convert the input into the arguments
     ...    - Write the result in these arguments


Result
~~~~~~
::

     The number of converted arguments.



See also
~~~~~~~~

`wscanf()`_ `swscanf()`_ 

----------

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.



See also
~~~~~~~~

`tgamma()`_ `lgamma()`_ 

----------

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.



See also
~~~~~~~~

`fgetc()`_ `fputc()`_ `putc()`_ 

----------

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.



See also
~~~~~~~~

`fgetc()`_ `getc()`_ `fputc()`_ `putc()`_ 

----------

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

`fgets()`_ 

----------

getwchar()
==========

Synopsis
~~~~~~~~
::

  t_t getwchar(
     void)

   FUNCTION
     The getwchar() function is the wide-character equivalent of getchar().
     It reads the next wide character from stdin and returns it as a wint_t
     value. If the end-of-file is reached or an error occurs, WEOF is returned.


Inputs
~~~~~~
::

     None.


Result
~~~~~~
::

     Returns the next wide character read from stdin as a wint_t.
     Returns WEOF if end-of-file is encountered or an error occurs.


Example
~~~~~~~
::

     wint_t wc;
     while ((wc = getwchar()) != WEOF)
         putwchar(wc);


Notes
~~~~~
::

     The behavior of getwchar() depends on the current locale, particularly
     the LC_CTYPE category, which affects the interpretation of multibyte
     sequences as wide characters.
     
     Internally, getwchar() is equivalent to calling fgetwc(stdin).


Bugs
~~~~
::

     If stdin is not a valid input stream or the locale is misconfigured,
     results may be undefined or incorrect.



See also
~~~~~~~~

`fgetwc()`_ `getchar()`_ `putwchar()`_ `getwc()`_ 

----------

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

`time()`_ `ctime()`_ `asctime()`_ `localtime()`_ 

----------

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

`time()`_ `ctime_r()`_ `asctime_r()`_ `localtime_r()`_ 

----------

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.



See also
~~~~~~~~

`hypotf()`_ `hypotl()`_ 

----------

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

`sqrtf()`_ 

----------

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.



See also
~~~~~~~~

`sqrtl()`_ `fabs()`_ 

----------

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

`wctype()`_ `iswalpha()`_ `iswdigit()`_ `iswspace()`_ 

----------

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.



See also
~~~~~~~~

`j1()`_ `y0()`_ `y1()`_ 

----------

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.



See also
~~~~~~~~

`j0()`_ `y0()`_ `y1()`_ 

----------

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.



See also
~~~~~~~~

`yn()`_ `j0()`_ `j1()`_ 

----------

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



See also
~~~~~~~~

`abs()`_ `llabs()`_ 

----------

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

`scalbn()`_ `frexp()`_ 

----------

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

`div()`_ 

----------

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.



See also
~~~~~~~~

`tgamma()`_ `log()`_ 

----------

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.



See also
~~~~~~~~

`tgammal()`_ `gamma()`_ 

----------

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



See also
~~~~~~~~

`abs()`_ `labs()`_ 

----------

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;



See also
~~~~~~~~

`div()`_ `ldiv()`_ 

----------

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

`locale.h </documentation/headerfiles/locale.h>`_ 

----------

localtime()
===========

Synopsis
~~~~~~~~
::

  struct tm * localtime(
     const time_t * tt)


Function
~~~~~~~~
::

     Splits the system time in seconds into a structure.

     See localtime_r() for details.


Inputs
~~~~~~
::

     tt - A time in seconds from the 1. Jan 1970


Result
~~~~~~
::

     A statically allocated buffer with the broken up time. Note that
     the contents of the buffer might get lost with the call of any of
     the date and time functions.


Example
~~~~~~~
::

     time_t      tt;
     struct tm * tm;

     // Get time
     time (&tt);

     // Break time up
     tm = localtime (&tt);


Notes
~~~~~
::

     Resulting tm struct is buffered per stdc.library and shared
     with gmtime().
     



See also
~~~~~~~~

`time()`_ `ctime()`_ `asctime()`_ `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.

     tm_gmtoff - Number of minutes that need to be added to UTC time to
                 get correct local time at time described . Note that this
                 includes DST correction as well.


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

`time()`_ `ctime_r()`_ `asctime_r()`_ `gmtime_r()`_ 

----------

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.



See also
~~~~~~~~

`log10()`_ `exp()`_ 

----------

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.



See also
~~~~~~~~

`log()`_ `log1p()`_ `exp10()`_ 

----------

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.



See also
~~~~~~~~

`logl()`_ `log2l()`_ 

----------

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.



See also
~~~~~~~~

`log()`_ `expm1()`_ `log10()`_ `log2()`_ 

----------

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.



See also
~~~~~~~~

`logl()`_ `expl()`_ 

----------

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.



See also
~~~~~~~~

`log()`_ `log10()`_ 

----------

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.



See also
~~~~~~~~

`log10l()`_ `logl()`_ 

----------

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.



See also
~~~~~~~~

`log10()`_ `exp()`_ 

----------

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

`free()`_ 

----------

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.



See also
~~~~~~~~

`calloc()`_ `free()`_ `malloc()`_ 

----------

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

`mbtowc()`_ `mbstowcs()`_ `wctomb()`_ `wcstombs()`_ 

----------

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()`_ `mbtowc()`_ `mbstowcs()`_ 

----------

mbrlen()
========

Synopsis
~~~~~~~~
::

  e_t mbrlen(
     const char * restrict s, 
     size_t n, 
     mbstate_t * restrict ps)
 

Function
~~~~~~~~
::

     Returns the size of the multibyte character pointed by s, examining at most n bytes.
     The mbrlen function is equivalent to the call: mbrtowc(NULL, s, n, ps)


Inputs
~~~~~~
::

     s   - Pointer to the first byte of a multibyte character.
     n   - Limit on the number of bytes in s that can be examined.
     ps  - Pointer to a mbstate_t object that defines a conversion state.


Result
~~~~~~
::

     Returns a value between zero and n, inclusive, (size_t)(-2), or (size_t)(-1).


Notes
~~~~~
::

     stdc.library currently only implements "C" locale



----------

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

`mbtowc()`_ `mbstowcs()`_ `wcrtomb()`_ 

----------

mbrtowc()
=========

Synopsis
~~~~~~~~
::

  e_t mbrtowc(
 wchar_t * restrict pwc, 
 const char * restrict s, 
 size_t n,
 mbstate_t * restrict ps __unused)


Function
~~~~~~~~
::

     Convert a multibyte sequence to a wide character.


Inputs
~~~~~~
::

     pwc - Pointer to an object of type wchar_t.
     s   - Pointer to the first byte of a multibyte character.
     n   - Maximum number of bytes to read from s.
     ps  - Pointer to a mbstate_t object that defines a conversion state.


Result
~~~~~~
::

     The number of bytes from s used to produce the wide character. 


Notes
~~~~~
::

     stdc.library currently only implements "C" locale
     this means the object ps is marked as unused



----------

mbsrtowcs()
===========

Synopsis
~~~~~~~~
::

  e_t mbsrtowcs(
 wchar_t * restrict dst, 
 const char ** restrict src, 
 size_t len,
 mbstate_t * restrict ps)


Function
~~~~~~~~
::

     Converts a sequence of multibyte characters that begins in the conversion state described by the object pointed to by ps, 
     from the array indirectly pointed to by src into a sequence of corresponding wide characters. 
     If dst is not a null pointer, the converted characters are stored into the array pointed to by dst. 
     Conversion continues up to and including a terminating null character, which is also stored. 
     Conversion stops earlier in two cases: when a sequence of bytes is encountered that does not form a valid multibyte character, 
     or (if dst is not a null pointer) when len wide characters have been stored into the array pointed to by dst. 
     Each conversion takes place as if by a call to the mbrtowc function. 


Inputs
~~~~~~
::

     dst - Pointer to an array of wchar_t elements long enough to store a string of len wide characters.
     src - Pointer to a C multibyte character string to be interpreted (an indirect pointer).
     len - Maximum number of wide characters to write to dst.
     ps  - Pointer to a mbstate_t object that defines a conversion state.


Result
~~~~~~
::

     The number of wide characters that make up the converted part of the wide-character string, 
     not including the terminating null wide character.


Notes
~~~~~
::

     stdc.library currently only implements "C" locale.



----------

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

`mbrtowc()`_ `mbstowcs()`_ `wcstombs()`_ 

----------

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()`_ `wcstombs()`_ `wctomb()`_ `mblen()`_ 

----------

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

`mblen()`_ `mbstowcs()`_ `wctomb()`_ `wcstombs()`_ 

----------

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

`strcmp()`_ `strncmp()`_ `strcasecmp()`_ `strncasecmp()`_ 

----------

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.



See also
~~~~~~~~

`memmove()`_ `memcpy()`_ 

----------

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

`time()`_ `ctime()`_ `asctime()`_ `localtime()`_ `gmtime()`_ 

----------

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.



See also
~~~~~~~~

`floor()`_ `ceil()`_ `frexp()`_ `modff()`_ 

----------

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.



See also
~~~~~~~~

`modf()`_ `frexp()`_ 

----------

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.



See also
~~~~~~~~

`floorl()`_ `ceill()`_ 

----------

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.



See also
~~~~~~~~

`exp()`_ `log()`_ `powf()`_ `powl()`_ 

----------

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)



See also
~~~~~~~~

`pow()`_ `exp()`_ `log()`_ 

----------

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.



See also
~~~~~~~~

`expl()`_ `logl()`_ 

----------

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.



See also
~~~~~~~~

`fprintf()`_ `vprintf()`_ `vfprintf()`_ `sprintf()`_ `vsprintf()`_ `vsnprintf()`_ 

----------

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

`fputc()`_ 

----------

putchar()
=========

Synopsis
~~~~~~~~
::

  int putchar(
     int c)


Function
~~~~~~~~
::

     Equivalent to fputc(stdout)



See also
~~~~~~~~

`fputc()`_ `putc()`_ 

----------

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



See also
~~~~~~~~

`fputs()`_ `printf()`_ `fprintf()`_ `putc()`_ `fputc()`_ 

----------

putwchar()
==========

Synopsis
~~~~~~~~
::

  t_t putwchar(
     wchar_t wc)

   FUNCTION
     The putwchar() function is the wide-character equivalent of putchar().
     It writes the wide character wc to the standard output stream using the
     current locale to convert it to its multibyte representation.


Inputs
~~~~~~
::

     wc - The wide character to be written to stdout.


Result
~~~~~~
::

     Returns the wide character written as a wint_t value on success.
     Returns WEOF if an error occurs.


Example
~~~~~~~
::

     putwchar(L'?');


Notes
~~~~~
::

     The output is affected by the current locale, particularly LC_CTYPE,
     which governs the multibyte encoding used during output.
     
     Internally, putwchar() is equivalent to fputwc(wc, stdout).


Bugs
~~~~
::

     If stdout is not a valid output stream or the locale does not support
     the character, the function may fail or produce unexpected results.



See also
~~~~~~~~

`fputwc()`_ `putchar()`_ `getwchar()`_ `putwc()`_ 

----------

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

`strcmp()`_ `strncmp()`_ `memcmp()`_ `strcasecmp()`_ `strncasecmp()`_ 

----------

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

`srand()`_ 

----------

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.



See also
~~~~~~~~

`calloc()`_ `free()`_ `malloc()`_ 

----------

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.



See also
~~~~~~~~

`free()`_ `malloc()`_ `calloc()`_ `realloc()`_ 

----------

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.



See also
~~~~~~~~

`fmod()`_ `modf()`_ 

----------

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

`fmodf()`_ `remainder()`_ 

----------

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

`remainder()`_ `fmod()`_ `div()`_ 

----------

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

`remainder()`_ `fmod()`_ `div()`_ 

----------

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



See also
~~~~~~~~

`fopen()`_ `fwrite()`_ `fseek()`_ 

----------

scanf()
=======

Synopsis
~~~~~~~~
::

  int scanf(
     const char * restrict format,
     ...)


Result
~~~~~~
::

     The number of converted parameters



See also
~~~~~~~~

`fscanf()`_ `vscanf()`_ `vfscanf()`_ `sscanf()`_ `vsscanf()`_ 

----------

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

`setvbuf()`_ 

----------

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

`locale.h </documentation/headerfiles/locale.h>`_ 

----------

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.



See also
~~~~~~~~

`cos()`_ `tan()`_ `sinf()`_ `sinl()`_ 

----------

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.



See also
~~~~~~~~

`cosf()`_ `tanf()`_ 

----------

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.



See also
~~~~~~~~

`cosh()`_ `tanh()`_ 

----------

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.



See also
~~~~~~~~

`coshf()`_ `tanhf()`_ `sinh()`_ 

----------

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.



See also
~~~~~~~~

`cosh()`_ `tanh()`_ `sinh()`_ 

----------

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.



See also
~~~~~~~~

`cos()`_ `tan()`_ `sinf()`_ `sinl()`_ 

----------

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.



See also
~~~~~~~~

`fprintf()`_ `vprintf()`_ `vfprintf()`_ `snprintf()`_ `vsprintf()`_ `vsnprintf()`_ 

----------

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.



See also
~~~~~~~~

`fprintf()`_ `vprintf()`_ `vfprintf()`_ `snprintf()`_ `vsprintf()`_ `vsnprintf()`_ 

----------

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.



See also
~~~~~~~~

`cbrt()`_ `hypot()`_ 

----------

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.



See also
~~~~~~~~

`sqrt()`_ `sqrtl()`_ 

----------

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.



See also
~~~~~~~~

`sqrt()`_ `cbrtl()`_ 

----------

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

`rand()`_ 

----------

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.



See also
~~~~~~~~

`fscanf()`_ `vscanf()`_ `vfscanf()`_ `vsscanf()`_ 

----------

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

`strncpy()`_ 

----------

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

`isspace()`_ 

----------

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

`strcpy()`_ 

----------

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



See also
~~~~~~~~

`strchr()`_ `strrchr()`_ `strpbrk()`_ 

----------

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

`strrchr()`_ 

----------

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.



See also
~~~~~~~~

`strncpy()`_ `memcpy()`_ `memmove()`_ 

----------

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



----------

strftime()
==========

Synopsis
~~~~~~~~
::

  size_t strftime(
         char *s,
         size_t maxsize,
         const char *format,
         const struct tm *timeptr)


Function
~~~~~~~~
::


     Converts the time information in the struct tm pointed to by 'timeptr'
     into a formatted string according to the 'format' specification.

     The resulting string is placed in the buffer pointed to by 's', which
     can contain up to 'maxsize' characters, including the terminating null.


Inputs
~~~~~~
::


     s           - Pointer to the destination character buffer.
     maxsize     - Maximum number of characters to store in the destination,
                   including the null terminator.
     format      - Format control string containing ordinary characters and
                   conversion specifiers, similar to ANSI strftime().
     timeptr     - Pointer to a struct tm containing the time values to format.


Result
~~~~~~
::

     The number of characters written to the destination buffer, excluding the
     terminating null character.

     Returns 0 if an error occurs (e.g., invalid arguments or formatting failure).


Example
~~~~~~~
::


     struct tm now = { .tm_year = 124, .tm_mon = 6, .tm_mday = 7, .tm_wday = 0,
                       .tm_hour = 15, .tm_min = 30, .tm_sec = 45 };
     char buf[64];

     strftime(buf, sizeof(buf), "%A, %B %d, %Y %H:%M:%S %p", &now);

     // Example output: "Sunday, July 07, 2024 15:30:45 PM"


Notes
~~~~~
::

     Supports a subset of ANSI C strftime() specifiers:
     %a %A - abbreviated and full weekday names
     %b %B - abbreviated and full month names
     %p    - AM/PM indicator
     %d %m %y %Y %H %I %M %S - numeric date/time fields
     %n %t %% - special characters

     Composite formats (%c, %x, %X, etc.) and locale-specific date/time formats
     are not yet implemented.


Bugs
~~~~
::

     - Does not support all strftime() specifiers.
     - Does not use the users actual locale settings.



----------

strlcat()
=========

Synopsis
~~~~~~~~
::

  size_t strlcat(
     char *dst,
     const char *src,
     size_t siz)



----------

strlcpy()
=========

Synopsis
~~~~~~~~
::

  size_t strlcpy(
     char *dst,
     const char *src,
     size_t siz)



----------

strlen()
========

Synopsis
~~~~~~~~
::

  size_t strlen(
     const char * ptr)


Function
~~~~~~~~
::

     Calculate the length of a string (without the terminating 0 byte).


Inputs
~~~~~~
::

     ptr - The string to get its length for


Result
~~~~~~
::

     The length of the string.



----------

strlwr()
========

Synopsis
~~~~~~~~
::

  char * strlwr(
     char * str)


Function
~~~~~~~~
::

     
     Converts a string to all lower case characters. Modifies
     the given string.


Inputs
~~~~~~
::

     str - The string to convert.


Result
~~~~~~
::

     The same string buffer is passed back with all characters converted.



----------

strncasecmp()
=============

Synopsis
~~~~~~~~
::

  int strncasecmp(
     const char * str1,
     const char * str2,
     size_t       n)


Function
~~~~~~~~
::

     Calculate str1 - str2 ignoring case. Up to n characters are taken
     into account.


Inputs
~~~~~~
::

     str1, str2 - Strings to compare


Result
~~~~~~
::

     The difference of the strings. The difference is 0, if both are
     equal, < 0 if str1 < str2 and > 0 if str1 > str2. Note that
     it may be greater then 1 or less than -1.


Notes
~~~~~
::

     This function is not part of a library and may thus be called
     any time.



----------

strncat()
=========

Synopsis
~~~~~~~~
::

  char * strncat(
     char       * dest,
     const char * src,
     size_t       n)


Function
~~~~~~~~
::

     Concatenates two strings. If src is longer than n characters, then
     only the first n characters are copied.


Inputs
~~~~~~
::

     dest - src is appended to this string. Make sure that there
             is enough room for src.
     src - This string is appended to dest
     n - No more than this number of characters of src are copied.


Result
~~~~~~
::

     dest.


Example
~~~~~~~
::

     char buffer[64];

     strcpy (buffer, "Hello ");
     strncat (buffer, "World.!!", 6);

     // Buffer now contains "Hello World."


Notes
~~~~~
::

     The routine makes no checks if dest is large enough. The size of
     dest must be at least strlen(dest)+n+1.



----------

strncmp()
=========

Synopsis
~~~~~~~~
::

  int strncmp(
     const char * str1,
     const char * str2,
     size_t       n)


Function
~~~~~~~~
::

     Calculate str1 - str2 for up to n chars or up to the first 0 byte.


Inputs
~~~~~~
::

     str1, str2 - Strings to compare


Result
~~~~~~
::

     The difference of the strings. The difference is 0, if both are
     equal, < 0 if str1 < str2 and > 0 if str1 > str2. Note that
     it may be greater then 1 or less than -1.


Notes
~~~~~
::

     This function is not part of a library and may thus be called
     any time.



----------

strncpy()
=========

Synopsis
~~~~~~~~
::

  char * strncpy(
     char       * dest,
     const char * src,
     size_t       n)


Function
~~~~~~~~
::

     Copy a string. Works like an assignment "dest=src;". At most
     n characters are copied.


Inputs
~~~~~~
::

     dest - The string is copied into this variable. Make sure it is
             large enough.
     src - This is the new contents of dest.
     n - How many characters to copy at most. If the string src is
             smaller than that, only strlen(str)+1 bytes are copied.


Result
~~~~~~
::

     dest.


Notes
~~~~~
::

     No check is made that dest is large enough for src.



See also
~~~~~~~~

`strncpy()`_ `memcpy()`_ `memmove()`_ 

----------

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



See also
~~~~~~~~

`strchr()`_ `strrchr()`_ 

----------

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

`strrchr()`_ 

----------

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



See also
~~~~~~~~

`strchr()`_ `strrchr()`_ `strpbrk()`_ 

----------

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



See also
~~~~~~~~

`atof()`_ `atoi()`_ `atol()`_ `strtol()`_ `strtoul()`_ 

----------

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.



See also
~~~~~~~~

`strtod()`_ `strtold()`_ 

----------

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



See also
~~~~~~~~

`strtol()`_ `strtoll()`_ 

----------

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



See also
~~~~~~~~

`atof()`_ `atoi()`_ `atol()`_ `strtod()`_ `strtoul()`_ 

----------

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

`strtod()`_ 

----------

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

`strtoull()`_ 

----------

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



See also
~~~~~~~~

`atoi()`_ `atol()`_ `strtod()`_ `strtol()`_ `strtoul()`_ 

----------

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

`strtoll()`_ `strtoull()`_ 

----------

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

`strtoul()`_ `strtoull()`_ 

----------

strupr()
========

Synopsis
~~~~~~~~
::

  char * strupr(
     char * str)


Function
~~~~~~~~
::

     
     Converts a string to all upper case characters. Modifies
     the given string.


Inputs
~~~~~~
::

     str - The string to convert.


Result
~~~~~~
::

     The same string buffer is passed back with all characters converted.



----------

strxfrm()
=========

Synopsis
~~~~~~~~
::

  size_t strxfrm(
     char * restrict dst,
     const char * restrict src,
     size_t n)


Function
~~~~~~~~
::

     The strxfrm() function transforms a null-terminated string pointed to by
     src according to the current locale collation if any, then copies the
     transformed string into dst.  Not more than n characters are copied into
     dst, including the terminating null character added.  If n is set to 0
     (it helps to determine an actual size needed for transformation), dst is
     permitted to be a NULL pointer.

     Comparing two strings using strcmp() after strxfrm() is equal to compar-
     ing two original strings with strcoll().


Inputs
~~~~~~
::

     dst - the destination string's buffer
     src - the source string
     n   - the size of the dst buffer.


Result
~~~~~~
::

     Upon successful completion, strxfrm() returns the length of the trans-
     formed string not including the terminating null character.  If this
     value is n or more, the contents of dst are indeterminate.


Notes
~~~~~
::

     stdc.library only support "C" locale so strxfrm is equivalent to
     strncpy.



----------

swprintf()
==========

Synopsis
~~~~~~~~
::

  int swprintf(
     wchar_t * restrict str,
     size_t   maxsize,
     const wchar_t * restrict format,
     ...)


Function
~~~~~~~~
::

     Format a variable list of arguments according to a wide-character
     format string and store the result in the specified buffer.


Inputs
~~~~~~
::

     s      - Destination buffer for the formatted wide-character string.
     maxsize - Maximum number of wide characters to store in the buffer,
               including the null terminator.
     format - A wide-character printf() format string.
     ...    - Additional arguments matching the format specifiers.


Result
~~~~~~
::

     The number of wide characters written to the buffer, excluding the
     terminating null character. A negative value is returned if an error
     occurs.


Notes
~~~~~
::

     The result is always null-terminated unless maxsize is zero.



See also
~~~~~~~~

`vswprintf()`_ `fwprintf()`_ `vfwprintf()`_ `wprintf()`_ `vwprintf()`_ 

----------

swscanf()
=========

Synopsis
~~~~~~~~
::

  int swscanf(
     const wchar_t * restrict ws,
     const wchar_t * restrict format,
     ...)


Function
~~~~~~~~
::

     Reads formatted wide-character input from the given wide-character string
     and stores the results into the provided argument locations.


Inputs
~~~~~~
::

     ws     - Read from this wide-character string
     format - How to convert the input into the arguments
     ...    - Write the result in these arguments


Result
~~~~~~
::

     The number of converted arguments.



See also
~~~~~~~~

`wscanf()`_ `fwscanf()`_ 

----------

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.



See also
~~~~~~~~

`sin()`_ `cos()`_ `tanh()`_ 

----------

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.



See also
~~~~~~~~

`sinf()`_ `cosf()`_ 

----------

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.



See also
~~~~~~~~

`sinh()`_ `cosh()`_ 

----------

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.



See also
~~~~~~~~

`sinhf()`_ `coshf()`_ 

----------

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.



See also
~~~~~~~~

`sinh()`_ `cosh()`_ 

----------

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.



See also
~~~~~~~~

`sinl()`_ `cosl()`_ 

----------

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.



See also
~~~~~~~~

`lgamma()`_ `erf()`_ 

----------

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.



See also
~~~~~~~~

`lgammal()`_ `gamma()`_ 

----------

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

`ctime()`_ `asctime()`_ `localtime()`_ 

----------

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.



See also
~~~~~~~~

`fopen()`_ `tmpnam()`_ 

----------

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

`tmpfile()`_ 

----------

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

`wctrans()`_ `towlower()`_ `towupper()`_ 

----------

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()`_ `towctrans()`_ 

----------

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

`towlower()`_ `towctrans()`_ 

----------

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

`floor()`_ `ceil()`_ `round()`_ 

----------

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

`floorf()`_ `ceilf()`_ `roundf()`_ 

----------

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

`floorl()`_ `ceill()`_ `roundl()`_ 

----------

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.



See also
~~~~~~~~

`fgetc()`_ `getc()`_ `fputc()`_ `putc()`_ 

----------

ungetwc()
=========

Synopsis
~~~~~~~~
::

  wint_t ungetwc(
     wint_t wc,
     FILE * stream)


Function
~~~~~~~~
::

     Push a wide character back onto the input stream.
     The next read operation will return this character.


Inputs
~~~~~~
::

     wc - Wide character to push back (can be WEOF).
     stream - Pointer to the stream.


Result
~~~~~~
::

     Returns the wide character pushed back, or WEOF on error.


Notes
~~~~~
::

     Only one wide character can be pushed back at a time.
     Subsequent calls without reading will overwrite the previous pushed-back character.



See also
~~~~~~~~

`fgetwc()`_ `fputwc()`_ 

----------

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

`asprintf()`_ `sprintf()`_ `vsprintf()`_ 

----------

vfprintf()
==========

Synopsis
~~~~~~~~
::

  int vfprintf(
     FILE       * restrict stream,
     const char * restrict format,
     va_list      args)


Function
~~~~~~~~
::

     Format a list of arguments and print them on the specified stream.


Inputs
~~~~~~
::

     stream - A stream on which one can write
     format - A printf() format string.
     args - A list of arguments for the format string.


Result
~~~~~~
::

     The number of characters written.



----------

vfscanf()
=========

Synopsis
~~~~~~~~
::

  int vfscanf(
     FILE       * stream,
     const char * format,
     va_list      args)


Function
~~~~~~~~
::

     Read the scream, scan it as the format specified and write the
     result of the conversion into the specified arguments.


Inputs
~~~~~~
::

     stream - A stream to read from
     format - A scanf() format string.
     args - A list of arguments for the results.


Result
~~~~~~
::

     The number of converted arguments.



----------

vfwprintf()
===========

Synopsis
~~~~~~~~
::

  int vfwprintf(
     struct __sFILE * restrict stream,
     const wchar_t * restrict format,
     va_list         arg)


Function
~~~~~~~~
::

     Format a va_list of arguments according to a wide-character
     format string and write the output to the given stream.


Inputs
~~~~~~
::

     stream - Output stream.
     format - A wide-character printf() format string.
     arg    - A va_list containing the arguments for the format string.


Result
~~~~~~
::

     The number of wide characters written to the stream, or a negative
     value if an error occurs.


Notes
~~~~~
::

     This is the va_list version of fwprintf(), similar to vprintf().



See also
~~~~~~~~

`fwprintf()`_ `wprintf()`_ `vwprintf()`_ `swprintf()`_ `vswprintf()`_ 

----------

vfwscanf()
==========

Synopsis
~~~~~~~~
::

  int vfwscanf(
     FILE       * restrict stream,
     const wchar_t * restrict format,
     va_list      arg)


Function
~~~~~~~~
::

     Reads formatted wide-character input from the given file stream,
     parsing according to the given format string, and stores the results
     into the locations described by the argument list.


Inputs
~~~~~~
::

     stream - Read from this wide-character file stream
     format - How to convert the input into the arguments
     arg    - List of argument pointers to receive results


Result
~~~~~~
::

     The number of converted arguments.



See also
~~~~~~~~

`vwscanf()`_ `vswscanf()`_ 

----------

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.



See also
~~~~~~~~

`printf()`_ `sprintf()`_ `fprintf()`_ `vprintf()`_ `vfprintf()`_ `snprintf()`_ `vsnprintf()`_ 

----------

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.



See also
~~~~~~~~

`printf()`_ `sprintf()`_ `fprintf()`_ `vprintf()`_ `vfprintf()`_ `snprintf()`_ `vsnprintf()`_ 

----------

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.



See also
~~~~~~~~

`scanf()`_ `sscanf()`_ `fscanf()`_ `vscanf()`_ `vfscanf()`_ 

----------

vswprintf()
===========

Synopsis
~~~~~~~~
::

  int vswprintf(
     wchar_t * restrict str,
     size_t   maxsize,
     const wchar_t * restrict format,
     va_list         args)


Function
~~~~~~~~
::

     Format a va_list of arguments according to a wide-character
     format string and store the result in the specified buffer.


Inputs
~~~~~~
::

     s       - Destination buffer for the formatted wide-character string.
     maxsize - Maximum number of wide characters to store in the buffer,
               including the null terminator.
     format  - A wide-character printf() format string.
     arg     - A va_list containing the arguments for the format string.


Result
~~~~~~
::

     The number of wide characters written to the buffer, excluding the
     terminating null character. A negative value is returned if an error
     occurs.


Notes
~~~~~
::

     The result is always null-terminated unless maxsize is zero.



See also
~~~~~~~~

`swprintf()`_ `fwprintf()`_ `vfwprintf()`_ `wprintf()`_ `vwprintf()`_ 

----------

vswscanf()
==========

Synopsis
~~~~~~~~
::

  int vswscanf(
     const wchar_t * restrict ws,
     const wchar_t * restrict format,
     va_list      arg)


Function
~~~~~~~~
::

     Reads formatted wide-character input from the given wide-character string,
     parsing according to the given format string, and stores the results
     into the locations described by the argument list.


Inputs
~~~~~~
::

     ws     - Read from this wide-character string
     format - How to convert the input into the arguments
     arg    - List of argument pointers to receive results


Result
~~~~~~
::

     The number of converted arguments.



See also
~~~~~~~~

`vwscanf()`_ `vfwscanf()`_ 

----------

vwprintf()
==========

Synopsis
~~~~~~~~
::

  int vwprintf(
     const wchar_t * restrict format,
     va_list         args)


Function
~~~~~~~~
::

     Format a va_list of arguments according to a wide-character
     format string and print the output to the standard output stream.


Inputs
~~~~~~
::

     format - A wide-character printf() format string.
     arg    - A va_list containing the arguments for the format string.


Result
~~~~~~
::

     The number of wide characters written to the standard output, or a
     negative value if an error occurs.


Notes
~~~~~
::

     Equivalent to vfwprintf() with stdout as the output stream.



See also
~~~~~~~~

`wprintf()`_ `fwprintf()`_ `vfwprintf()`_ `swprintf()`_ `vswprintf()`_ 

----------

vwscanf()
=========

Synopsis
~~~~~~~~
::

  int vwscanf(
     const wchar_t * restrict format,
     va_list      arg)


Function
~~~~~~~~
::

     Reads formatted wide-character input from the standard input stream
     and stores the results into the locations described by the argument list.


Inputs
~~~~~~
::

     format - How to convert the input into the arguments
     arg    - List of argument pointers to receive results


Result
~~~~~~
::

     The number of converted arguments.



See also
~~~~~~~~

`vfwscanf()`_ `vswscanf()`_ 

----------

wcrtomb()
=========

Synopsis
~~~~~~~~
::

  e_t wcrtomb(
 char * restrict s, 
 wchar_t wc,
 mbstate_t * restrict ps)


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 an array large enough to hold a multibyte sequence.
     wc - Wide character of type wchar_t.
     ps - Pointer to a mbstate_t object that defines a conversion state.


Result
~~~~~~
::

     Returns 1. (see notes)


Notes
~~~~~
::

     stdc.library currently only implements "C" locale
     this means the function will always return 1.



----------

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

`wctomb()`_ `mbtowc()`_ `mbrtowc()`_ `wcstombs()`_ `mbstowcs()`_ 

----------

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. 



----------

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.



----------

wcsftime()
==========

Synopsis
~~~~~~~~
::

  size_t wcsftime(
     wchar_t *s,
     size_t maxsize,
     const wchar_t *format,
     const struct tm *timeptr)


Function
~~~~~~~~
::

     Format time/date according to locale-dependent format.
     This is the wide character version of strftime().


Inputs
~~~~~~
::

     s - buffer to store the formatted string
     maxsize - maximum number of wide characters to store
     format - format string with conversion specifiers
     timeptr - pointer to tm structure containing time/date


Result
~~~~~~
::

     Number of wide characters stored in s (excluding null terminator),
     or 0 if the result would not fit in maxsize characters.


Example
~~~~~~~
::

     wchar_t buffer[100];
     struct tm *timeinfo;
     time_t rawtime;
     
     time(&rawtime);
     timeinfo = localtime(&rawtime);
     wcsftime(buffer, 100, L"Today is %A, %B %d, %Y", timeinfo);


Notes
~~~~~
::

     Function does not take localization into account at the moment.
     Conversion specifiers are the same as strftime().



See also
~~~~~~~~

`strftime()`_ 

----------

wcslen()
========

Synopsis
~~~~~~~~
::

  size_t wcslen(
     const wchar_t *wcstr)


Function
~~~~~~~~
::

     Returns the length of a wide string.


Inputs
~~~~~~
::

     wcstr - wide string to tally.


Result
~~~~~~
::

     The number of non-null wide characters, in the wide string.



----------

wcsncat()
=========

Synopsis
~~~~~~~~
::

  ar_t *wcsncat(
 wchar_t *dest,
 const wchar_t *src,
 size_t n)


Function
~~~~~~~~
::

     Appends at most n wide characters from the wide string src to the end
     of the wide string dest, and null-terminates the result.


Inputs
~~~~~~
::

     dest - Destination wide string buffer. Must be large enough to hold the
            resulting concatenated string including the terminating null.
     src  - Source wide string to append.
     n    - Maximum number of wide characters to append from src.


Result
~~~~~~
::

     Returns a pointer to the destination string dest.


Example
~~~~~~~
::


     wchar_t buf[20] = L"Hello, ";
     wcsncat(buf, L"World!", 3);
     // buf now contains L"Hello, Wor"


Notes
~~~~~
::

     Appends characters up to n or until a null wide character in src is
     encountered, whichever comes first. The resulting string in dest is
     always null-terminated. Behavior is undefined if dest and src overlap.



See also
~~~~~~~~

`wcscat()`_ `wcsncpy()`_ 

----------

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.



----------

wcsnrtombs()
============

Synopsis
~~~~~~~~
::

  e_t wcsnrtombs(
     char * restrict dst, 
     const wchar_t ** restrict src,
     size_t nwc, 
     size_t len, 
     mbstate_t * restrict ps)


Function
~~~~~~~~
::

     The wcsnrtombs() function is like the wcsrtombs() function, 
     except that the number of wide characters to be converted, starting at *src, 
     is limited to nwc.


Inputs
~~~~~~
::

     dst - Pointer to an array of char elements long enough to store a C string of len bytes.
     src - Pointer to a C wide string to be translated.
     nwc - Maximum number of bytes the conversion is limited to.
     len - Maximum number of bytes characters to write to dst.
     ps  - Pointer to a mbstate_t object that defines a conversion state.


Result
~~~~~~
::

     Returns the number of bytes that make up the converted part of multibyte sequence,
     not including the terminating null byte.


Notes
~~~~~
::

     stdc.library currently only implements "C" locale.



----------

wcspbrk()
=========

Synopsis
~~~~~~~~
::

  ar_t *wcspbrk(
 const wchar_t *s,
 const wchar_t *accept)


Function
~~~~~~~~
::

     Scans the wide string s for the first occurrence of any character
     in the wide string accept.


Inputs
~~~~~~
::

     s      - Wide string to scan.
     accept - Wide string containing characters to match.


Result
~~~~~~
::

     Returns a pointer to the first occurrence in s of any character from accept,
     or NULL if no such character is found.



See also
~~~~~~~~

`wcschr()`_ `wcsrchr()`_ `wmemchr()`_ 

----------

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 the wide character c in the wide string s.


Inputs
~~~~~~
::

     s - Wide string to search.
     c - Wide character to locate.


Result
~~~~~~
::

     Returns a pointer to the last occurrence of c in s,
     or NULL if c is not found. If c is the null character,
     returns a pointer to the null terminator.



See also
~~~~~~~~

`wcschr()`_ `wmemchr()`_ 

----------

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
~~~~~~~~
::

  e_t wcsrtombs(
     char * restrict dst, 
     const wchar_t ** restrict src,
     size_t len, 
     mbstate_t * restrict ps)


Function
~~~~~~~~
::

     Converts a sequence of up to len wide characters from the array indirectly pointed to by src,
     into a sequence of corresponding multibyte characters that begins in the conversion
     state described by the object pointed to by ps.


Inputs
~~~~~~
::

     dst - Pointer to an array of char elements long enough to store a C string of len bytes.
     src - Pointer to a C wide string to be translated.
     len - Maximum number of bytes characters to write to dst.
     ps  - Pointer to a mbstate_t object that defines a conversion state.


Result
~~~~~~
::

     The number of bytes written to dst, not including the eventual terminating null character.


Notes
~~~~~
::

     stdc.library currently only implements "C" locale.



----------

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

`wcrtomb()`_ `wcstombs()`_ `mbstowcs()`_ `mbsrtowcs()`_ 

----------

wcsspn()
========

Synopsis
~~~~~~~~
::

  e_t wcsspn(
 const wchar_t *s1, 
 const wchar_t *s2)


Function
~~~~~~~~
::

     Calculates the length of the initial segment of s1 which consists
     entirely of wide characters in s2.


Inputs
~~~~~~
::

     s1 - wide string to be scanned.
     s2 - wide string containing the characters to match.


Result
~~~~~~
::

     Length of the initial segment of s1 which contains only
     wide characters from s2.



----------

wcsstr()
========

Synopsis
~~~~~~~~
::

  ar_t *wcsstr(
 const wchar_t *s1, 
 const wchar_t *s2)


Function
~~~~~~~~
::

     Locates the first occurrence in the wide string pointed to by s1 of the sequence 
     of wide characters (excluding the terminating null wide character) in the wide string 
     pointed to by s2.


Inputs
~~~~~~
::

     s1  - wide string to be scanned.
     s2  - wide string containing the sequence of characters to match.


Result
~~~~~~
::

     Returns a pointer to the first occurrence in s1 of the entire sequence of characters 
     specified in s2, or a null pointer if the sequence is not present in s1.



----------

wcstod()
========

Synopsis
~~~~~~~~
::

  ble wcstod(
 const wchar_t *nptr,
 wchar_t **endptr)


Function
~~~~~~~~
::

     Converts the initial portion of the wide string nptr to a double-precision
     floating-point number. Conversion stops at the first invalid character.


Inputs
~~~~~~
::

     nptr   - Wide string to convert.
     endptr - If not NULL, set to point to the character after the last used
              in conversion.


Result
~~~~~~
::

     Returns the converted double value. Returns 0.0 if no conversion could
     be performed. On overflow, returns HUGE_VAL and sets errno to ERANGE.


Example
~~~~~~~
::


     wchar_t *end;
     double val = wcstod(L"3.14159xyz", &end);
     // val == 3.14159, *end == L'x'


Notes
~~~~~
::

     Recognizes optional whitespace, optional sign, decimal and exponential
     notation, and special values such as "inf" and "nan".



See also
~~~~~~~~

`strtod()`_ `wcstof()`_ `wcstold()`_ 

----------

wcstof()
========

Synopsis
~~~~~~~~
::

  at wcstof(
 const wchar_t *nptr,
 wchar_t **endptr)


Function
~~~~~~~~
::

     Converts the initial portion of the wide string nptr to a single-precision
     floating-point number. Stops at the first invalid character.


Inputs
~~~~~~
::

     nptr   - Wide string to convert.
     endptr - If not NULL, updated to point after the last consumed character.


Result
~~~~~~
::

     Returns the converted float value, or 0.0 if no conversion was possible.
     On overflow, returns HUGE_VALF and sets errno to ERANGE.


Example
~~~~~~~
::


     wchar_t *end;
     float val = wcstof(L"2.71828abc", &end);
     // val == 2.71828f, *end == L'a'


Notes
~~~~~
::

     Supports whitespace, optional sign, decimal/exponential notation, and
     special values like "inf" and "nan".



See also
~~~~~~~~

`strtof()`_ `wcstod()`_ `wcstold()`_ 

----------

wcstok()
========

Synopsis
~~~~~~~~
::

  ar_t *wcstok(
 wchar_t * restrict s1, 
 const wchar_t * restrict s2, 
 wchar_t ** restrict ptr)


Function
~~~~~~~~
::

     Split wide string into tokens.


Inputs
~~~~~~
::

     s1  - wide string to truncate.
     s2  - wide string containing the delimiter wide characters.
     ptr - Pointer to a wchar_t pointer.


Result
~~~~~~
::

     Returns a pointer to the first wide character of a token, 
     or a null pointer if there is no token. 



----------

wcstol()
========

Synopsis
~~~~~~~~
::

  g wcstol(
 const wchar_t *nptr,
 wchar_t **endptr,
 int base)


Function
~~~~~~~~
::

     Converts the initial part of wide string nptr to a long integer value,
     using the specified base (2 to 36) or auto-detect if base is 0.


Inputs
~~~~~~
::

     nptr   - Wide string to convert.
     endptr - If not NULL, set to character after last used in conversion.
     base   - Numeric base for conversion (0, or 2 to 36).


Result
~~~~~~
::

     Returns the converted long integer. On overflow, returns LONG_MAX or
     LONG_MIN and sets errno to ERANGE. Returns 0 if no conversion was done.


Example
~~~~~~~
::


     wchar_t *end;
     long val = wcstol(L"0x10abc", &end, 0);
     // val == 16, *end == L'a'


Notes
~~~~~
::

     Skips optional whitespace and supports optional '+' or '-' sign.
     Base 0 auto-detects hexadecimal (0x), octal (0), or decimal.



See also
~~~~~~~~

`strtol()`_ `wcstoll()`_ `wcstoul()`_ `wcstoull()`_ 

----------

wcstold()
=========

Synopsis
~~~~~~~~
::

  g double wcstold(
 const wchar_t *nptr,
 wchar_t **endptr)


Function
~~~~~~~~
::

     Converts the initial portion of the wide string nptr to a long double
     floating-point number. Stops at first invalid character.


Inputs
~~~~~~
::

     nptr   - Wide string input.
     endptr - If not NULL, set to the character after last converted character.


Result
~~~~~~
::

     Returns converted long double value. Returns 0.0L if no conversion.
     On overflow, returns HUGE_VALL and sets errno to ERANGE.


Example
~~~~~~~
::


     wchar_t *end;
     long double val = wcstold(L"1.2345e10xyz", &end);
     // val == 1.2345e10L, *end == L'x'


Notes
~~~~~
::

     Handles optional whitespace, sign, decimal and exponential notation,
     and special values "inf" and "nan".



See also
~~~~~~~~

`wcstod()`_ `wcstof()`_ 

----------

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

`wcrtomb()`_ `mbstowcs()`_ `wctomb()`_ `mbtowc()`_ 

----------

wcstoul()
=========

Synopsis
~~~~~~~~
::

  igned long wcstoul(
 const wchar_t *nptr,
 wchar_t **endptr,
 int base)


Function
~~~~~~~~
::

     Converts the initial part of the wide string nptr to an unsigned long
     integer according to the specified base or auto-detect if base is 0.


Inputs
~~~~~~
::

     nptr   - Wide string input.
     endptr - If not NULL, set to character after last used in conversion.
     base   - Numeric base (0 or 2 to 36).


Result
~~~~~~
::

     Returns the converted unsigned long integer. On overflow, returns ULONG_MAX
     and sets errno to ERANGE. Returns 0 if no conversion.


Example
~~~~~~~
::


     wchar_t *end;
     unsigned long val = wcstoul(L"0755abc", &end, 0);
     // val == 493, *end == L'a'


Notes
~~~~~
::

     Supports optional whitespace and optional plus sign. Base 0 auto-detects.



See also
~~~~~~~~

`wcstol()`_ `wcstoull()`_ 

----------

wcsxfrm()
=========

Synopsis
~~~~~~~~
::

  size_t wcsxfrm(
     wchar_t *dest, const wchar_t *src, size_t n)


Function
~~~~~~~~
::

     Transforms the wide-character string 'src' into a form suitable
     for comparison using wcscmp(), and stores it in 'dest'.


Inputs
~~~~~~
::

     dest -- destination buffer to store the transformed string
     src  -- source wide-character string
     n    -- maximum number of characters to store in dest


Result
~~~~~~
::

     Returns the length of the transformed string (as if no limit was applied),
     not counting the null terminator.


Notes
~~~~~
::

     This naive implementation simply copies 'src' to 'dest' up to
     'n' characters (including the null terminator if space permits).
     This implementation does not perform locale-specific transformations;
     it is equivalent to wcsncpy() + wcslen()



See also
~~~~~~~~

`wcscmp()`_ `wcscoll()`_ `wcscpy()`_ `wcsncpy()`_ 

----------

wctob()
=======

Synopsis
~~~~~~~~
::

  wctob(
     wint_t wc)

   FUNCTION
     The wctob() function attempts to convert a wide character to a
     single-byte character, according to the current locale's encoding.
     The conversion is only successful if the wide character maps to
     a single byte.


Inputs
~~~~~~
::

     wc - A wide character (wint_t) to convert.


Result
~~~~~~
::

     Returns the corresponding single-byte character (as an unsigned char)
     cast to int, or EOF if the character cannot be represented as a
     single-byte sequence.


Example
~~~~~~~
::

     int c = wctob(L'A');   // Might return 'A' if in ASCII-compatible locale.


Notes
~~~~~
::

     This function only succeeds for wide characters that map directly
     to a single byte in the current locale encoding.


Bugs
~~~~
::

     Fails for wide characters that require multibyte sequences (e.g.,
     most non-ASCII characters in UTF-8).



See also
~~~~~~~~

`btowc()`_ `wcrtomb()`_ `setlocale()`_ 

----------

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

`wcrtomb()`_ `mbtowc()`_ `mbrtowc()`_ `wcstombs()`_ `mbstowcs()`_ 

----------

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

`towctrans()`_ `towupper()`_ `towlower()`_ 

----------

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

`iswctype()`_ `towctrans()`_ `wctrans()`_ 

----------

wmemchr()
=========

Synopsis
~~~~~~~~
::

  ar_t *wmemchr(
 const wchar_t *s,
 wchar_t c,
 size_t n)


Function
~~~~~~~~
::

     Scans the initial n wide characters of the memory area pointed to by s
     for the first occurrence of the wide character c.


Inputs
~~~~~~
::

     s - Memory area to scan.
     c - Wide character to locate.
     n - Number of wide characters to scan.


Result
~~~~~~
::

     Returns a pointer to the first occurrence of c within the first n
     wide characters of s, or NULL if c is not found.



See also
~~~~~~~~

`wmemcpy()`_ `wmemmove()`_ 

----------

wmemcmp()
=========

Synopsis
~~~~~~~~
::

  wmemcmp(
 const wchar_t * s1, 
 const wchar_t * s2, 
 size_t n)


Function
~~~~~~~~
::

      Compares the first n wide characters of the object pointed to by s1 
      to the first n wide characters of the object pointed to by s2.


Inputs
~~~~~~
::

     s1 - Pointer to block of elements of type wchar_t.
     s2 - Pointer to block of elements of type wchar_t.
     n  - Number of elements of type wchar_t to compare.


Result
~~~~~~
::

     Returns an integral value indicating the relationship between the content of the blocks:
     A zero value indicates that the contents of both memory blocks are equal.
     A value greater than zero indicates that the first wide character that does not match 
     in both memory blocks has a greater value in ptr1 than in ptr2; 
     And a value less than zero indicates the opposite.



----------

wmemcpy()
=========

Synopsis
~~~~~~~~
::

  ar_t *wmemcpy(
 wchar_t * restrict s1,
 const wchar_t * restrict s2,
 size_t n)


Function
~~~~~~~~
::

     Copies n wide characters from s2 to s1.
     The memory areas must not overlap.


Inputs
~~~~~~
::

     s1 - Destination buffer.
     s2 - Source buffer.
     n  - Number of wide characters to copy.


Result
~~~~~~
::

     Returns s1.



See also
~~~~~~~~

`wmemmove()`_ 

----------

wmemmove()
==========

Synopsis
~~~~~~~~
::

  ar_t *wmemmove(
 wchar_t *s1,
 const wchar_t *s2,
 size_t n)


Function
~~~~~~~~
::

     Copies n wide characters from s2 to s1.
     The memory areas may overlap.


Inputs
~~~~~~
::

     s1 - Destination buffer.
     s2 - Source buffer.
     n  - Number of wide characters to copy.


Result
~~~~~~
::

     Returns s1.



See also
~~~~~~~~

`wmemcpy()`_ 

----------

wmemset()
=========

Synopsis
~~~~~~~~
::

  ar_t *wmemset(
 wchar_t *s, 
 wchar_t c, 
 size_t n)


Function
~~~~~~~~
::

     Copies the value of c into each of the first n wide characters of the object pointed to by s.


Inputs
~~~~~~
::

     s - Pointer to the array to fill.
     c - Value to be set.
     n - Number of bytes to be set to the value.


Result
~~~~~~
::

     Returns the value of s. 



----------

wprintf()
=========

Synopsis
~~~~~~~~
::

  int wprintf(
     const wchar_t * restrict format,
     ...)


Function
~~~~~~~~
::

     Format a variable list of arguments according to a wide-character
     format string and print the output to the standard output stream.


Inputs
~~~~~~
::

     format - A wide-character printf() format string.
     ...    - Additional arguments matching the format specifiers.


Result
~~~~~~
::

     The number of wide characters written to the standard output, or a
     negative value if an error occurs.


Notes
~~~~~
::

     Equivalent to fwprintf() with stdout as the output stream.



See also
~~~~~~~~

`vwprintf()`_ `fwprintf()`_ `vfwprintf()`_ `swprintf()`_ `vswprintf()`_ 

----------

wscanf()
========

Synopsis
~~~~~~~~
::

  int wscanf(
     const wchar_t * restrict format,
     ...)


Function
~~~~~~~~
::

     Reads formatted wide-character input from the standard input stream
     and stores the results into the provided argument locations.


Inputs
~~~~~~
::

     format - How to convert the input into the arguments
     ...    - Write the result in these arguments


Result
~~~~~~
::

     The number of converted arguments.



See also
~~~~~~~~

`scanf()`_ `fwscanf()`_ 

----------

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.



See also
~~~~~~~~

`y1()`_ `j0()`_ `j1()`_ 

----------

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.



See also
~~~~~~~~

`y0()`_ `j0()`_ `j1()`_ 

----------

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.



See also
~~~~~~~~

`jn()`_ `y0()`_ `y1()`_ 

