Missing declarations / definitions added to stdlib.h.

[pdclib] / includes / stdlib.h

diff --git a/includes/stdlib.h b/includes/stdlib.h
index 1bf1fc26872df4cbec70405f5aac9e3e95b8dc9a..e751dbe0c7bd5c240b43d42c883e2e5c16bab767 100644 (file)
--- a/includes/stdlib.h
+++ b/includes/stdlib.h
@@ -1,7 +1,3 @@
-/* $Id$ */
-
-/* Release $Name$ */
-

 /* General utilities <stdlib.h>
 
    This file is part of the Public Domain C Library (PDCLib).
 /* General utilities <stdlib.h>
 
    This file is part of the Public Domain C Library (PDCLib).


@@ -10,10 +6,10 @@
 
 #ifndef _PDCLIB_STDLIB_H
 #define _PDCLIB_STDLIB_H _PDCLIB_STDLIB_H
 
 #ifndef _PDCLIB_STDLIB_H
 #define _PDCLIB_STDLIB_H _PDCLIB_STDLIB_H

-
-#ifndef _PDCLIB_INT_H
-#define _PDCLIB_INT_H _PDCLIB_INT_H

 #include <_PDCLIB_int.h>
 #include <_PDCLIB_int.h>

+
+#ifdef __cplusplus
+extern "C" {

 #endif
 
 #ifndef _PDCLIB_SIZE_T_DEFINED
 #endif
 
 #ifndef _PDCLIB_SIZE_T_DEFINED


@@ -26,14 +22,28 @@ typedef _PDCLIB_size_t size_t;
 #define NULL _PDCLIB_NULL
 #endif
 
 #define NULL _PDCLIB_NULL
 #endif
 

+#ifndef __cplusplus
+
+#ifndef _PDCLIB_WCHAR_T_DEFINED
+#define _PDCLIB_WCHAR_T_DEFINED _PDCLIB_WCHAR_T_DEFINED
+typedef _PDCLIB_wchar_t wchar_t;
+#endif
+
+#endif
+
+#ifndef _PDCLIB_MB_CUR_MAX_DEFINED
+#define _PDCLIB_MB_CUR_MAX_DEFINED
+#define MB_CUR_MAX (_PDCLIB_mb_cur_max())
+#endif
+

 /* Numeric conversion functions */
 
 /* TODO: atof(), strtof(), strtod(), strtold() */
 
 /* Numeric conversion functions */
 
 /* TODO: atof(), strtof(), strtod(), strtold() */
 

-double atof( const char * nptr );
-double strtod( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr );
-float strtof( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr );
-long double strtold( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr );
+double atof( const char * nptr ) _PDCLIB_nothrow;
+double strtod( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;
+float strtof( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;
+long double strtold( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;

 
 /* Seperate the character array nptr into three parts: A (possibly empty)
    sequence of whitespace characters, a character representation of an integer
 
 /* Seperate the character array nptr into three parts: A (possibly empty)
    sequence of whitespace characters, a character representation of an integer


@@ -54,10 +64,13 @@ long double strtold( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restri
    LLONG_MIN, LLONG_MAX, or ULLONG_MAX respectively, depending on the sign of
    the integer representation and the return type, and errno is set to ERANGE.
 */
    LLONG_MIN, LLONG_MAX, or ULLONG_MAX respectively, depending on the sign of
    the integer representation and the return type, and errno is set to ERANGE.
 */

-long int strtol( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base );
-long long int strtoll( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base );
-unsigned long int strtoul( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base );
-unsigned long long int strtoull( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base );
+/* There is strtoimax() and strtoumax() in <inttypes.h> operating on intmax_t /
+   uintmax_t, if the long long versions do not suit your needs.
+*/
+long int strtol( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
+long long int strtoll( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
+unsigned long int strtoul( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
+unsigned long long int strtoull( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;

 
 /* These functions are the equivalent of (int)strtol( nptr, NULL, 10 ),
    strtol( nptr, NULL, 10 ) and strtoll(nptr, NULL, 10 ) respectively, with the
 
 /* These functions are the equivalent of (int)strtol( nptr, NULL, 10 ),
    strtol( nptr, NULL, 10 ) and strtoll(nptr, NULL, 10 ) respectively, with the


@@ -67,9 +80,9 @@ unsigned long long int strtoull( const char * _PDCLIB_restrict nptr, char * * _P
    provides a simpler atox() function that saves a couple of tests and simply
    continues with the conversion in case of overflow.)
 */
    provides a simpler atox() function that saves a couple of tests and simply
    continues with the conversion in case of overflow.)
 */

-int atoi( const char * nptr );
-long int atol( const char * nptr );
-long long int atoll( const char * nptr );
+int atoi( const char * nptr ) _PDCLIB_nothrow;
+long int atol( const char * nptr ) _PDCLIB_nothrow;
+long long int atoll( const char * nptr ) _PDCLIB_nothrow;

 
 /* Pseudo-random sequence generation functions */
 
 
 /* Pseudo-random sequence generation functions */
 


@@ -82,34 +95,41 @@ extern unsigned long int _PDCLIB_seed;
    (PDCLib uses the implementation suggested by the standard document, which is
    next = next * 1103515245 + 12345; return (unsigned int)(next/65536) % 32768;)
 */
    (PDCLib uses the implementation suggested by the standard document, which is
    next = next * 1103515245 + 12345; return (unsigned int)(next/65536) % 32768;)
 */

-int rand( void );
+int rand( void ) _PDCLIB_nothrow;

 
 /* Initialize a new pseudo-random sequence with the starting seed. Same seeds
    result in the same pseudo-random sequence. The default seed is 1.
 */
 
 /* Initialize a new pseudo-random sequence with the starting seed. Same seeds
    result in the same pseudo-random sequence. The default seed is 1.
 */

-void srand( unsigned int seed );
+void srand( unsigned int seed ) _PDCLIB_nothrow;

 
 /* Memory management functions */
 
 
 /* Memory management functions */
 

-/* Allocate a chunk of heap memory of given size. If request could not be
+/* Allocate a chunk of memory of given size. If request could not be

    satisfied, return NULL. Otherwise, return a pointer to the allocated
    memory. Memory contents are undefined.
 */
    satisfied, return NULL. Otherwise, return a pointer to the allocated
    memory. Memory contents are undefined.
 */

-void * malloc( size_t size );
+void * malloc( size_t size ) _PDCLIB_nothrow;

 
 

-/* Allocate a chunk of heap memory that is large enough to hold nmemb elements
-   of the given size, and zero-initialize that memory. If request could not be
+/* Allocate a chunk of memory that is large enough to hold nmemb elements of
+   the given size, and zero-initialize that memory. If request could not be

    satisfied, return NULL. Otherwise, return a pointer to the allocated
    memory.
 */
    satisfied, return NULL. Otherwise, return a pointer to the allocated
    memory.
 */

-void * calloc( size_t nmemb, size_t size );
+void * calloc( size_t nmemb, size_t size ) _PDCLIB_nothrow;
+
+/* Allocate a chunk of memory of given size, with specified alignment (which
+   must be a power of two; if it is not, the next greater power of two is
+   used). If request could not be satisfied, return NULL. Otherwise, return
+   a pointer to the allocated memory.
+*/
+void * aligned_alloc( size_t alignment, size_t size ) _PDCLIB_nothrow;

 
 /* De-allocate a chunk of heap memory previously allocated using malloc(),
    calloc(), or realloc(), and pointed to by ptr. If ptr does not match a
    pointer previously returned by the mentioned allocation functions, or
    free() has already been called for this ptr, behaviour is undefined.
 */
 
 /* De-allocate a chunk of heap memory previously allocated using malloc(),
    calloc(), or realloc(), and pointed to by ptr. If ptr does not match a
    pointer previously returned by the mentioned allocation functions, or
    free() has already been called for this ptr, behaviour is undefined.
 */

-void free( void * ptr );
+void free( void * ptr ) _PDCLIB_nothrow;

 
 /* Resize a chunk of memory previously allocated with malloc() and pointed to
    by ptr to the given size (which might be larger or smaller than the original
 
 /* Resize a chunk of memory previously allocated with malloc() and pointed to
    by ptr to the given size (which might be larger or smaller than the original


@@ -120,7 +140,7 @@ void free( void * ptr );
    memory beyond the original size is undefined. If ptr is NULL, realloc()
    behaves like malloc().
 */
    memory beyond the original size is undefined. If ptr is NULL, realloc()
    behaves like malloc().
 */

-void * realloc( void * ptr, size_t size );
+void * realloc( void * ptr, size_t size ) _PDCLIB_nothrow;

 
 /* Communication with the environment */
 
 
 /* Communication with the environment */
 


@@ -140,14 +160,21 @@ void * realloc( void * ptr, size_t size );
    temporary files before exiting with EXIT_FAILURE.
    abort() does not return.
 */
    temporary files before exiting with EXIT_FAILURE.
    abort() does not return.
 */

-void abort( void );
+_PDCLIB_noreturn void abort( void ) _PDCLIB_nothrow;
+
+/* Register a function that will be called on exit(), or when main() returns.
+   At least 32 functions can be registered this way, and will be called in
+   reverse order of registration (last-in, first-out).
+   Returns zero if registration is successfull, nonzero if it failed.
+*/
+int atexit( void (*func)( void ) ) _PDCLIB_nothrow;

 
 

-/* Register a function that will be called on exit(), _Exit(), or when main()
-   returns. At least 32 functions can be registered this way, and will be
-   called in reverse order of registration (last-in, first-out).
+/* Register a function that will be called on quick_exit(), or when main() returns.
+   At least 32 functions can be registered this way, and will be called in
+   reverse order of registration (last-in, first-out).

    Returns zero if registration is successfull, nonzero if it failed.
 */
    Returns zero if registration is successfull, nonzero if it failed.
 */

-int atexit( void (*func)( void ) ); 
+int at_quick_exit( void (*func)( void ) ) _PDCLIB_nothrow;

 
 /* Normal process termination. Functions registered by atexit() (see above) are
    called, streams flushed, files closed and temporary files removed before the
 
 /* Normal process termination. Functions registered by atexit() (see above) are
    called, streams flushed, files closed and temporary files removed before the


@@ -155,7 +182,7 @@ int atexit( void (*func)( void ) );
    and EXIT_FAILURE above.)
    exit() does not return.
 */
    and EXIT_FAILURE above.)
    exit() does not return.
 */

-void exit( int status );
+_PDCLIB_noreturn void exit( int status ) _PDCLIB_nothrow;

 
 /* Normal process termination. Functions registered by atexit() (see above) are
    NOT CALLED. This implementation DOES flush streams, close files and removes
 
 /* Normal process termination. Functions registered by atexit() (see above) are
    NOT CALLED. This implementation DOES flush streams, close files and removes


@@ -163,7 +190,14 @@ void exit( int status );
    comment for EXIT_SUCCESS and EXIT_FAILURE above.)
    _Exit() does not return.
 */
    comment for EXIT_SUCCESS and EXIT_FAILURE above.)
    _Exit() does not return.
 */

-void _Exit( int status );
+_PDCLIB_noreturn void _Exit( int status ) _PDCLIB_nothrow;
+
+/* Quick process termination. Functions registered by at_quick_exit() (see
+   above) are called, and the process terminated. No functions registered
+   with atexit() (see above) or signal handlers are called.
+   quick_exit() does not return.
+*/
+_PDCLIB_noreturn void quick_exit( int status );

 
 /* Search an environment-provided key-value map for the given key name, and
    return a pointer to the associated value string (or NULL if key name cannot
 
 /* Search an environment-provided key-value map for the given key name, and
    return a pointer to the associated value string (or NULL if key name cannot


@@ -172,14 +206,14 @@ void _Exit( int status );
    Details on the provided keys and how to set / change them are determined by
    the hosting OS and its glue function.
 */
    Details on the provided keys and how to set / change them are determined by
    the hosting OS and its glue function.
 */

-char * getenv( const char * name );
+char * getenv( const char * name ) _PDCLIB_nothrow;

 
 /* If string is a NULL pointer, system() returns nonzero if a command processor
    is available, and zero otherwise. If string is not a NULL pointer, it is
    passed to the command processor. If system() returns, it does so with a
    value that is determined by the hosting OS and its glue function.
 */
 
 /* If string is a NULL pointer, system() returns nonzero if a command processor
    is available, and zero otherwise. If string is not a NULL pointer, it is
    passed to the command processor. If system() returns, it does so with a
    value that is determined by the hosting OS and its glue function.
 */

-int system( const char * string );
+int system( const char * string ) _PDCLIB_nothrow;

 
 /* Searching and sorting */
 
 
 /* Searching and sorting */
 


@@ -192,6 +226,8 @@ int system( const char * string );
    greater than the array element, respectively.
    The function returns a pointer to the first matching element found, or NULL
    if no match is found.
    greater than the array element, respectively.
    The function returns a pointer to the first matching element found, or NULL
    if no match is found.

+
+   ** May throw **

 */
 void * bsearch( const void * key, const void * base, size_t nmemb, size_t size, int (*compar)( const void *, const void * ) );
 
 */
 void * bsearch( const void * key, const void * base, size_t nmemb, size_t size, int (*compar)( const void *, const void * ) );
 


@@ -202,6 +238,8 @@ void * bsearch( const void * key, const void * base, size_t nmemb, size_t size,
    to be less than, equal to, or greater than the second argument, respectively.
    If two elements are compared equal, their order in the sorted array is not
    specified.
    to be less than, equal to, or greater than the second argument, respectively.
    If two elements are compared equal, their order in the sorted array is not
    specified.

+
+   ** May throw **

 */
 void qsort( void * base, size_t nmemb, size_t size, int (*compar)( const void *, const void * ) );
 
 */
 void qsort( void * base, size_t nmemb, size_t size, int (*compar)( const void *, const void * ) );
 


@@ -211,9 +249,9 @@ void qsort( void * base, size_t nmemb, size_t size, int (*compar)( const void *,
    complement's notation (most modern CPUs), the largest negative value cannot
    be represented as positive value. In this case, behaviour is unspecified.
 */
    complement's notation (most modern CPUs), the largest negative value cannot
    be represented as positive value. In this case, behaviour is unspecified.
 */

-int abs( int j );
-long int labs( long int j );
-long long int llabs( long long int j );
+int abs( int j ) _PDCLIB_nothrow;
+long int labs( long int j ) _PDCLIB_nothrow;
+long long int llabs( long long int j ) _PDCLIB_nothrow;

 
 /* These structures each have a member quot and a member rem, of type int (for
    div_t), long int (for ldiv_t) and long long it (for lldiv_t) respectively.
 
 /* These structures each have a member quot and a member rem, of type int (for
    div_t), long int (for ldiv_t) and long long it (for lldiv_t) respectively.


@@ -227,20 +265,87 @@ typedef struct _PDCLIB_lldiv_t lldiv_t;
 /* Return quotient (quot) and remainder (rem) of an integer division in one of
    the structs above.
 */
 /* Return quotient (quot) and remainder (rem) of an integer division in one of
    the structs above.
 */

-div_t div( int numer, int denom );
-ldiv_t ldiv( long int numer, long int denom );
-lldiv_t lldiv( long long int numer, long long int denom );
+div_t div( int numer, int denom ) _PDCLIB_nothrow;
+ldiv_t ldiv( long int numer, long int denom ) _PDCLIB_nothrow;
+lldiv_t lldiv( long long int numer, long long int denom ) _PDCLIB_nothrow;

 
 

-/* TODO: Multibyte / wide character conversion functions */
+/* Multibyte / wide character conversion functions */

 
 

-/* TODO: Macro MB_CUR_MAX */
+/* Affected by LC_CTYPE of the current locale. For state-dependent encoding,
+   each function is placed into its initial conversion state at program
+   startup, and can be returned to that state by a call with its character
+   pointer argument s being a null pointer.
+   Changing LC_CTYPE causes the conversion state to become indeterminate.
+*/

 
 

-/*
+/* If s is not a null pointer, returns the number of bytes contained in the
+   multibyte character pointed to by s (if the next n or fewer bytes form a
+   valid multibyte character); -1, if they don't; or 0, if s points to the
+   null character.
+   If s is a null pointer, returns nonzero if multibyte encodings in the
+   current locale are stateful, and zero otherwise.
+*/

 int mblen( const char * s, size_t n );
 int mblen( const char * s, size_t n );

+
+/* If s is not a null pointer, and the next n bytes (maximum) form a valid
+   multibyte character sequence (possibly including shift sequences), the
+   corresponding wide character is stored in pwc (unless that is a null
+   pointer). If the wide character is the null character, the function is
+   left in the initial conversion state.
+   Returns the number of bytes in the consumed multibyte character sequence;
+   or 0, if the resulting wide character is the null character. If the next
+   n bytes do not form a valid sequence, returns -1.
+   In no case will the returned value be greater than n or MB_CUR_MAX.
+   If s is a null pointer, returns nonzero if multibyte encodings in the
+   current locale are stateful, and zero otherwise.
+*/

 int mbtowc( wchar_t * _PDCLIB_restrict pwc, const char * _PDCLIB_restrict s, size_t n );
 int mbtowc( wchar_t * _PDCLIB_restrict pwc, const char * _PDCLIB_restrict s, size_t n );

+
+/* Converts the wide character wc into the corresponding multibyte character
+   sequence (including shift sequences). If s is not a null pointer, the
+   multibyte sequence (at most MB_CUR_MAX characters) is stored at that
+   location. If wc is a null character, a null byte is stored, preceded by
+   any shift sequence needed to restore the initial shift state, and the
+   function is left in the initial conversion state.
+   Returns the number of bytes in the generated multibyte character sequence.
+   If wc does not correspond to a valid multibyte character, returns -1.
+   In no case will the returned value be greater than MB_CUR_MAX.
+   If s is a null pointer, returns nonzero if multibyte encodings in the
+   current locale are stateful, and zero otherwise.
+*/

 int wctomb( char * s, wchar_t wc );
 int wctomb( char * s, wchar_t wc );

+
+/* Convert a sequence of multibyte characters beginning in the initial shift
+   state from the array pointed to by s into the corresponding wide character
+   sequence, storing no more than n wide characters into pwcs. A null
+   character is converted into a null wide character, and marks the end of
+   the multibyte character sequence.
+   If copying takes place between objects that overlap, behaviour is
+   undefined.
+   Returns (size_t)-1 if an invalid multibyte sequence is encountered.
+   Otherwise, returns the number of array elements modified, not including
+   a terminating null wide character, if any. (Target string will not be
+   null terminated if the return value equals n.)
+*/

 size_t mbstowcs( wchar_t * _PDCLIB_restrict pwcs, const char * _PDCLIB_restrict s, size_t n );
 size_t mbstowcs( wchar_t * _PDCLIB_restrict pwcs, const char * _PDCLIB_restrict s, size_t n );

-size_t wcstombs( char * _PDCLIB_restrict s, const wchar_t * _PDCLIB_restrict pwcs, size_t n );
+
+/* Convert a sequence of wide characters from the array pointed to by pwcs
+   into a sequence of corresponding multibyte characters, beginning in the
+   initial shift state, storing them in the array pointed to by s, stopping
+   if the next multibyte character would exceed the limit of n total bytes
+   or a null character is stored.
+   If copying takes place between objects that overlap, behaviour is
+   undefined.
+   Returns (size_t)-1 if a wide character is encountered that does not
+   correspond to a valid multibyte character. Otherwise, returns the number
+   of array elements modified, not including a terminating null character,
+   if any. (Target string will not be null terminated if the return value
+   equals n.)

 */
 */

+size_t wcstombs( char * _PDCLIB_restrict s, const wchar_t * _PDCLIB_restrict pwcs, size_t n );
+
+#ifdef __cplusplus
+}
+#endif

 
 #endif
 
 #endif