1 ==============================================================
2 PDCLib - the `Public Domain C Library <http://pdclib.e43.eu>`_
3 ==============================================================
8 This is a C Standard Library - what's defined in ISO/IEC 9899 "Information
9 technology — Programming languages — C" or extensions to the above defined in
10 ISO/IEC 14882 "Information technology — Programming languages — C++". A few
11 extensions may optionally be provided.
17 * 2003-2012 by Martin "Solar" Baute,
18 * 2012- by Owen Shepherd
20 To the extent possible under law, the author(s) have dedicated all copyright
21 and related and neighboring rights to this software to the public domain
22 worldwide. This software is distributed without any warranty.
24 You should have received a copy of the CC0 Public Domain Dedication along with
25 this software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
30 Unicode Character Data
31 ~~~~~~~~~~~~~~~~~~~~~~
32 PDCLib necessarily includes Unicode character data derived from that provided by
33 Unicode, Inc in its' implementation of the localization and wide character
34 support (in particular for use by the ctype.h and wctype.h functions.)
36 Unicode, Inc licenses that data under a license agreement which can be found at
37 <http://www.unicode.org/copyright.html#Exhibit1>, or in the file
38 UNICODE_DATA_LICENSE.txt. found in the same directory as this file.
42 Portions of the test suite are under different licenses. Where this is the case,
43 it is clearly noted in the relevant location.
45 The license of this code has no bearing upon the licensing of the built library
46 (as it does not comprise part of it).
48 At the time this was written, this exception only applies to portions of the
49 printf test suite, which are released under the terms of the 2-clause BSD
50 license (see testing/printf_testcases.h for full details)
54 Extensions are permitted only if they pass the following tests:
56 Pre-existing wide usage
57 On most systems, the system C library must maintain its application binary
58 interface for long periods of time (potentially eternity). Existing wide
59 usage demonstrates utility
61 In keeping with the spirit of the standard
62 The extension should respect the design, intentions and conventions of the C
63 standard, and feel like a natural extension to the offered capability.
66 The extension should not add any additional dependencies on the underlying
70 Extensions should not duplicate functionality already provided by the
74 PDCLib will always default to a "strictly conforming" mode exposing only
75 functionality offered by the version of the standard specified by the
76 __STDC_VERSION__, __STDC__ or __cplusplus macro; extensions will only be
77 exposed when requested.
79 Additionally, extra consideration will be given to extensions which are
80 difficult or impossible to implement without access to internal structures of
86 **Included.** strndup is easily defined in terms of existing standard
87 functions, follows the standard's naming conventions, is in wide usage, and
88 does not duplicate features already provided.
91 **Rejected.** Has existing wide usage, is not system dependent (can be
92 implemented, albeit inefficiently, on top of malloc), but naming is not
93 consistent with the naming used by the standard (posix_ prefix) and
94 duplicates functionality provided by the C11 standard
96 open, close, read, write, ...
97 **Rejected.** Widely used, but duplicates functionality provided by the
98 standard (FILE objects set to be unbuffered), and not able to implement full
99 semantics (e.g. in relation to POSIX fork and other functionality from the
100 same defining standard) in a platform-neutral way
103 **Rejected.** Used somewhat widely, in keeping with the standard, not system
104 dependent, but duplicative of functionality provided by (optional) Annex K
107 flockfile, funlockfile, getc_unlocked, putc_unlocked, fwrite_unlocked, ...
108 **Accepted.** Provide functionality not provided by the standard (and
109 useful in light of the C11 addition of threading). Can be trivially
110 implemented in terms of the <threads.h> mutex functions and the bodies of
111 the existing I/O functions, and impossible to implement externally
116 As a namespace convention, everything (files, typedefs, functions,
117 macros) not defined in ISO/IEC 9899 is prefixed with _PDCLIB.
118 The standard defines any identifiers starting with '_' and a capital
119 letter as reserved for the implementation, and since the chances of
120 your compiler using an identifier in the _PDCLIB range are slim,
121 any strictly conforming application should work with this library.
123 PDCLib consists of several parts:
126 2) implementation files for standard functions;
127 3) internal header files keeping complex stuff out of the standard
129 4) the central, platform-specific file _PDCLIB_config.h;
130 5) platform-specific implementation files;
132 The standard headers (in ./includes/) only contain what they are
133 defined to contain. Where additional logic or macro magic is
134 necessary, that is deferred to the internal files. This has been done
135 so that the headers are actually educational as to what they provide
136 (as opposed to how the library does it).
138 There is a seperate implementation file (in ./function/{header}/) for
139 every function defined by the standard, named {function}.c. Not only
140 does this avoid linking in huge amounts of unused code when you use
141 but a single function, it also allows the optimization overlay to work
144 (The directory ./functions/_PDCLIB/ contains internal and helper
145 functions that are not part of the standard.)
147 Then there are internal header files (in ./internal/), which contain
148 all the "black magic" and "code fu" that was kept out of the standard
149 headers. You should not have to touch them if you want to adapt PDCLib
150 to a new platform. Note that, if you *do* have to touch them, I would
151 consider it a serious design flaw, and would be happy to fix it in the
152 next PDCLib release. Any adaption work should be covered by the steps
155 For adapting PDCLib to a new platform (the trinity of CPU, operating
156 system, and compiler), make a copy of ./platform/example/ named
157 ./platform/{your_platform}/, and modify the files of your copy to suit
158 the constraints of your platform. When you are done, copy the contents
159 of your platform directory over the source directory structure
160 of PDCLib (or link them into the appropriate places). That should be
161 all that is actually required to make PDCLib work for your platform.
165 Obviously, full C89, C99 and C11 conformance; and full support for the
166 applicable portions of C++98, C++03 and C++11 (the version which acomplishes
167 this will be christened "1.0").
169 Support for "optimization overlays." These would allow efficient
170 implementations of certain functions on individual platforms, for example
171 memcpy, strcpy and memset. This requires further work to only compile in one
172 version of a given function.
174 Post 1.0, support for C11 Annexe K "Bounds checking interfaces"
179 ``v0.1 - 2004-12-12``
180 Freestanding-only C99 implementation without any overlay, and missing
181 the INTN_C() / UINTN_C() macros. <float.h> still has the enquire.c
182 values hardcoded into it; not sure whether to include enquire.c in the
183 package, to leave <float.h> to the overlay, or devise some parameterized
184 macro magic as for <limits.h> / <stdint.h>. Not thoroughly tested, but
185 I had to make the 0.1 release sometime so why not now.
187 ``v0.2 - 2005-01-12``
188 Adds implementations for <string.h> (excluding strerror()), INTN_C() /
189 UINTN_C() macros, and some improvements in the internal headers.
190 Test drivers still missing, but added warnings about that.
192 ``v0.3 - 2005-11-21``
193 Adds test drivers, fixes some bugs in <string.h>.
195 ``v0.4 - 2005-02-06``
196 Implementations for parts of <stdlib.h>. Still missing are the floating
197 point conversions, and the wide-/multibyte-character functions.
199 ``v0.4.1 - 2006-11-16``
200 With v0.5 (<stdio.h>) taking longer than expected, v0.4.1 was set up as
201 a backport of bugfixes in the current development code.
203 - #1 realloc( NULL, size ) fails
204 - #2 stdlib.h - insufficient documentation
205 - #4 Misspelled name in credits
206 - #5 malloc() splits off too-small nodes
207 - #6 qsort() stack overflow
208 - #7 malloc() bug in list handling
209 - #8 strncmp() does not terminate at '\0'
210 - #9 stdint.h dysfunctional
211 - #10 NULL redefinition warnings
213 ``v0.5 - 2010-12-22``
214 Implementations for <inttypes.h>, <errno.h>, most parts of <stdio.h>,
215 and strerror() from <string.h>.
216 Still no locale / wide-char support. Enabled all GCC compiler warnings I
217 could find, and fixed everything that threw a warning. (You see this,
218 maintainers of Open Source software? No warnings whatsoever. Stop telling
219 me it cannot be done.) Fixed all known bugs in the v0.4 release.
223 Current development directions are:
225 Implement portions of the C11 standard that have a direct impact on the way
226 that PDCLib itself is built. For example, in order to support multithreading,
227 PDCLib needs a threading abstraction; therefore, C11's thread library is being
228 implemented to provide the backing for this (as there is no purpose in
229 implementing two abstractions)
231 Modularize the library somewhat. This can already be seen with components under
232 "opt/". This structure is preliminary; it will likely change as the process