1 /* General utilities <stdlib.h>
3 This file is part of the Public Domain C Library (PDCLib).
4 Permission is granted to use, modify, and / or redistribute at will.
7 #ifndef _PDCLIB_STDLIB_H
8 #define _PDCLIB_STDLIB_H _PDCLIB_STDLIB_H
9 #include <_PDCLIB_int.h>
15 #ifndef _PDCLIB_SIZE_T_DEFINED
16 #define _PDCLIB_SIZE_T_DEFINED _PDCLIB_SIZE_T_DEFINED
17 typedef _PDCLIB_size_t size_t;
20 #ifndef _PDCLIB_NULL_DEFINED
21 #define _PDCLIB_NULL_DEFINED _PDCLIB_NULL_DEFINED
22 #define NULL _PDCLIB_NULL
25 #ifndef _PDCLIB_MB_CUR_MAX_DEFINED
26 #define _PDCLIB_MB_CUR_MAX_DEFINED
27 #define MB_CUR_MAX (_PDCLIB_mb_cur_max())
30 /* Numeric conversion functions */
32 /* TODO: atof(), strtof(), strtod(), strtold() */
34 double atof( const char * nptr ) _PDCLIB_nothrow;
35 double strtod( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;
36 float strtof( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;
37 long double strtold( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr ) _PDCLIB_nothrow;
39 /* Seperate the character array nptr into three parts: A (possibly empty)
40 sequence of whitespace characters, a character representation of an integer
41 to the given base, and trailing invalid characters (including the terminating
42 null character). If base is 0, assume it to be 10, unless the integer
43 representation starts with 0x / 0X (setting base to 16) or 0 (setting base to
44 8). If given, base can be anything from 0 to 36, using the 26 letters of the
45 base alphabet (both lowercase and uppercase) as digits 10 through 35.
46 The integer representation is then converted into the return type of the
47 function. It can start with a '+' or '-' sign. If the sign is '-', the result
48 of the conversion is negated.
49 If the conversion is successful, the converted value is returned. If endptr
50 is not a NULL pointer, a pointer to the first trailing invalid character is
52 If no conversion could be performed, zero is returned (and nptr in *endptr,
53 if endptr is not a NULL pointer). If the converted value does not fit into
54 the return type, the functions return LONG_MIN, LONG_MAX, ULONG_MAX,
55 LLONG_MIN, LLONG_MAX, or ULLONG_MAX respectively, depending on the sign of
56 the integer representation and the return type, and errno is set to ERANGE.
58 /* There is strtoimax() and strtoumax() in <inttypes.h> operating on intmax_t /
59 uintmax_t, if the long long versions do not suit your needs.
61 long int strtol( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
62 long long int strtoll( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
63 unsigned long int strtoul( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
64 unsigned long long int strtoull( const char * _PDCLIB_restrict nptr, char * * _PDCLIB_restrict endptr, int base ) _PDCLIB_nothrow;
66 /* These functions are the equivalent of (int)strtol( nptr, NULL, 10 ),
67 strtol( nptr, NULL, 10 ) and strtoll(nptr, NULL, 10 ) respectively, with the
68 exception that they do not have to handle overflow situations in any defined
70 (PDCLib does not simply forward these to their strtox() equivalents, but
71 provides a simpler atox() function that saves a couple of tests and simply
72 continues with the conversion in case of overflow.)
74 int atoi( const char * nptr ) _PDCLIB_nothrow;
75 long int atol( const char * nptr ) _PDCLIB_nothrow;
76 long long int atoll( const char * nptr ) _PDCLIB_nothrow;
78 /* Pseudo-random sequence generation functions */
80 extern unsigned long int _PDCLIB_seed;
82 #define RAND_MAX 32767
84 /* Returns the next number in a pseudo-random sequence, which is between 0 and
86 (PDCLib uses the implementation suggested by the standard document, which is
87 next = next * 1103515245 + 12345; return (unsigned int)(next/65536) % 32768;)
89 int rand( void ) _PDCLIB_nothrow;
91 /* Initialize a new pseudo-random sequence with the starting seed. Same seeds
92 result in the same pseudo-random sequence. The default seed is 1.
94 void srand( unsigned int seed ) _PDCLIB_nothrow;
96 /* Memory management functions */
98 /* Allocate a chunk of memory of given size. If request could not be
99 satisfied, return NULL. Otherwise, return a pointer to the allocated
100 memory. Memory contents are undefined.
102 void * malloc( size_t size ) _PDCLIB_nothrow;
104 /* Allocate a chunk of memory that is large enough to hold nmemb elements of
105 the given size, and zero-initialize that memory. If request could not be
106 satisfied, return NULL. Otherwise, return a pointer to the allocated
109 void * calloc( size_t nmemb, size_t size ) _PDCLIB_nothrow;
111 /* Allocate a chunk of memory of given size, with specified alignment (which
112 must be a power of two; if it is not, the next greater power of two is
113 used). If request could not be satisfied, return NULL. Otherwise, return
114 a pointer to the allocated memory.
116 void * aligned_alloc( size_t alignment, size_t size ) _PDCLIB_nothrow;
118 /* De-allocate a chunk of heap memory previously allocated using malloc(),
119 calloc(), or realloc(), and pointed to by ptr. If ptr does not match a
120 pointer previously returned by the mentioned allocation functions, or
121 free() has already been called for this ptr, behaviour is undefined.
123 void free( void * ptr ) _PDCLIB_nothrow;
125 /* Resize a chunk of memory previously allocated with malloc() and pointed to
126 by ptr to the given size (which might be larger or smaller than the original
127 size). Returns a pointer to the reallocated memory, or NULL if the request
128 could not be satisfied. Note that the resizing might include a memcpy()
129 from the original location to a different one, so the return value might or
130 might not equal ptr. If size is larger than the original size, the value of
131 memory beyond the original size is undefined. If ptr is NULL, realloc()
132 behaves like malloc().
134 void * realloc( void * ptr, size_t size ) _PDCLIB_nothrow;
136 /* Communication with the environment */
138 /* These two can be passed to exit() or _Exit() as status values, to signal
139 successful and unsuccessful program termination, respectively. EXIT_SUCCESS
140 can be replaced by 0. How successful or unsuccessful program termination are
141 signaled to the environment, and what happens if exit() or _Exit() are being
142 called with a value that is neither of the three, is defined by the hosting
143 OS and its glue function.
145 #define EXIT_SUCCESS _PDCLIB_SUCCESS
146 #define EXIT_FAILURE _PDCLIB_FAILURE
148 /* Initiate abnormal process termination, unless programm catches SIGABRT and
149 does not return from the signal handler.
150 This implementantion flushes all streams, closes all files, and removes any
151 temporary files before exiting with EXIT_FAILURE.
152 abort() does not return.
154 _PDCLIB_noreturn void abort( void ) _PDCLIB_nothrow;
156 /* Register a function that will be called on exit(), or when main() returns.
157 At least 32 functions can be registered this way, and will be called in
158 reverse order of registration (last-in, first-out).
159 Returns zero if registration is successfull, nonzero if it failed.
161 int atexit( void (*func)( void ) ) _PDCLIB_nothrow;
163 /* Normal process termination. Functions registered by atexit() (see above) are
164 called, streams flushed, files closed and temporary files removed before the
165 program is terminated with the given status. (See comment for EXIT_SUCCESS
166 and EXIT_FAILURE above.)
167 exit() does not return.
169 _PDCLIB_noreturn void exit( int status ) _PDCLIB_nothrow;
171 /* Normal process termination. Functions registered by atexit() (see above) are
172 NOT CALLED. This implementation DOES flush streams, close files and removes
173 temporary files before the program is teminated with the given status. (See
174 comment for EXIT_SUCCESS and EXIT_FAILURE above.)
175 _Exit() does not return.
177 _PDCLIB_noreturn void _Exit( int status ) _PDCLIB_nothrow;
179 /* Search an environment-provided key-value map for the given key name, and
180 return a pointer to the associated value string (or NULL if key name cannot
181 be found). The value string pointed to might be overwritten by a subsequent
182 call to getenv(). The library never calls getenv() itself.
183 Details on the provided keys and how to set / change them are determined by
184 the hosting OS and its glue function.
186 char * getenv( const char * name ) _PDCLIB_nothrow;
188 /* If string is a NULL pointer, system() returns nonzero if a command processor
189 is available, and zero otherwise. If string is not a NULL pointer, it is
190 passed to the command processor. If system() returns, it does so with a
191 value that is determined by the hosting OS and its glue function.
193 int system( const char * string ) _PDCLIB_nothrow;
195 /* Searching and sorting */
197 /* Do a binary search for a given key in the array with a given base pointer,
198 which consists of nmemb elements that are of the given size each. To compare
199 the given key with an element from the array, the given function compar is
200 called (with key as first parameter and a pointer to the array member as
201 second parameter); the function should return a value less than, equal to,
202 or greater than 0 if the key is considered to be less than, equal to, or
203 greater than the array element, respectively.
204 The function returns a pointer to the first matching element found, or NULL
205 if no match is found.
209 void * bsearch( const void * key, const void * base, size_t nmemb, size_t size, int (*compar)( const void *, const void * ) );
211 /* Do a quicksort on an array with a given base pointer, which consists of
212 nmemb elements that are of the given size each. To compare two elements from
213 the array, the given function compar is called, which should return a value
214 less than, equal to, or greater than 0 if the first argument is considered
215 to be less than, equal to, or greater than the second argument, respectively.
216 If two elements are compared equal, their order in the sorted array is not
221 void qsort( void * base, size_t nmemb, size_t size, int (*compar)( const void *, const void * ) );
223 /* Integer arithmetic functions */
225 /* Return the absolute value of the argument. Note that on machines using two-
226 complement's notation (most modern CPUs), the largest negative value cannot
227 be represented as positive value. In this case, behaviour is unspecified.
229 int abs( int j ) _PDCLIB_nothrow;
230 long int labs( long int j ) _PDCLIB_nothrow;
231 long long int llabs( long long int j ) _PDCLIB_nothrow;
233 /* These structures each have a member quot and a member rem, of type int (for
234 div_t), long int (for ldiv_t) and long long it (for lldiv_t) respectively.
235 The order of the members is platform-defined to allow the div() functions
236 below to be implemented efficiently.
238 typedef struct _PDCLIB_div_t div_t;
239 typedef struct _PDCLIB_ldiv_t ldiv_t;
240 typedef struct _PDCLIB_lldiv_t lldiv_t;
242 /* Return quotient (quot) and remainder (rem) of an integer division in one of
245 div_t div( int numer, int denom ) _PDCLIB_nothrow;
246 ldiv_t ldiv( long int numer, long int denom ) _PDCLIB_nothrow;
247 lldiv_t lldiv( long long int numer, long long int denom ) _PDCLIB_nothrow;
249 /* TODO: Multibyte / wide character conversion functions */
251 /* TODO: Macro MB_CUR_MAX */
254 int mblen( const char * s, size_t n );
255 int mbtowc( wchar_t * _PDCLIB_restrict pwc, const char * _PDCLIB_restrict s, size_t n );
256 int wctomb( char * s, wchar_t wc );
257 size_t mbstowcs( wchar_t * _PDCLIB_restrict pwcs, const char * _PDCLIB_restrict s, size_t n );
258 size_t wcstombs( char * _PDCLIB_restrict s, const wchar_t * _PDCLIB_restrict pwcs, size_t n );