--- /dev/null
+PDCLib - the `Public Domain C Library<http://pdclib.e43.eu>`_\r
+================================\r
+\r
+What is it\r
+----------\r
+\r
+This is a C Standard Library - what's defined in ISO/IEC 9899 "Information \r
+technology — Programming languages — C" or extensions to the above defined in\r
+ISO/IEC 14882 "Information technology — Programming languages — C++". A few \r
+extensions may optionally be provided.\r
+\r
+License\r
+-------\r
+\r
+Written in 2003-2012 by Martin "Solar" Baute,\r
+ 2012- by Owen Shepherd\r
+\r
+To the extent possible under law, the author(s) have dedicated all copyright \r
+and related and neighboring rights to this software to the public domain \r
+worldwide. This software is distributed without any warranty.\r
+\r
+You should have received a copy of the CC0 Public Domain Dedication along with \r
+this software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.\r
+\r
+ **Exception:** Portions of the test suite are under different licenses. \r
+ Where this is the case, it is clearly noted in the relevant location.\r
+\r
+ The license of this code has no bearing upon the licensing of the built \r
+ library (as it does not comprise part of it).\r
+\r
+ At the time this was written, this exception only applies to portions of the\r
+ printf test suite, which are released under the terms of the 2-clause BSD\r
+ license (see testing/printf_testcases.h for full details)\r
+\r
+Terms for extensions\r
+--------------------\r
+Extensions are permitted only if they pass the following tests:\r
+\r
+Pre-existing wide usage\r
+ On most systems, the system C library must maintain its application binary\r
+ interface for long periods of time (potentially eternity). Existing wide \r
+ usage demonstrates utility\r
+\r
+In keeping with the spirit of the standard\r
+ The extension should respect the design, intentions and conventions of the C\r
+ standard, and feel like a natural extension to the offered capability. \r
+\r
+Not system dependent\r
+ The extension should not add any additional dependencies on the underlying \r
+ system\r
+\r
+Non-duplicative\r
+ Extensions should not duplicate functionality already provided by the \r
+ standard\r
+\r
+Disabled by default\r
+ PDCLib will always default to a "strictly conforming" mode exposing only\r
+ functionality offered by the version of the standard specified by the\r
+ __STDC_VERSION__, __STDC__ or __cplusplus macro; extensions will only be \r
+ exposed when requested.\r
+\r
+Additionally, extra consideration will be given to extensions which are \r
+difficult or impossible to implement without access to internal structures of \r
+the C library.\r
+\r
+Conrete Examples:\r
+\r
+strndup\r
+ **Included.** strndup is easily defined in terms of existing standard \r
+ functions, follows the standard's naming conventions, is in wide usage, and\r
+ does not duplicate features already provided.\r
+\r
+posix_memalign\r
+ **Rejected.** Has existing wide usage, is not system dependent (can be \r
+ implemented, albeit inefficiently, on top of malloc), but naming is not \r
+ consistent with the naming used by the standard (posix_ prefix) and \r
+ duplicates functionality provided by the C11 standard\r
+\r
+open, close, read, write, ...\r
+ **Rejected.** Widely used, but duplicates functionality provided by the \r
+ standard (FILE objects set to be unbuffered), and not able to implement full\r
+ semantics (e.g. in relation to POSIX fork and other functionality from the \r
+ same defining standard) in a platform-neutral way\r
+\r
+strl*\r
+ **Rejected.** Used somewhat widely, in keeping with the standard, not system\r
+ dependent, but duplicative of functionality provided by (optional) Annex K \r
+ of the C standard. \r
+\r
+flockfile, funlockfile, getc_unlocked, putc_unlocked, fwrite_unlocked, ...\r
+ **Accepted.** Provide functionality not provided by the standard (and \r
+ useful in light of the C11 addition of threading). Can be trivially \r
+ implemented in terms of the <threads.h> mutex functions and the bodies of \r
+ the existing I/O functions, and impossible to implement externally\r
+\r
+Internals\r
+---------\r
+\r
+As a namespace convention, everything (files, typedefs, functions,\r
+macros) not defined in ISO/IEC 9899 is prefixed with _PDCLIB.\r
+The standard defines any identifiers starting with '_' and a capital\r
+letter as reserved for the implementation, and since the chances of\r
+your compiler using an identifier in the _PDCLIB range are slim,\r
+any strictly conforming application should work with this library.\r
+\r
+PDCLib consists of several parts:\r
+\r
+1) standard headers;\r
+2) implementation files for standard functions;\r
+3) internal header files keeping complex stuff out of the standard\r
+ headers;\r
+4) the central, platform-specific file _PDCLIB_config.h;\r
+5) platform-specific implementation files;\r
+\r
+The standard headers (in ./includes/) only contain what they are\r
+defined to contain. Where additional logic or macro magic is\r
+necessary, that is deferred to the internal files. This has been done\r
+so that the headers are actually educational as to what they provide\r
+(as opposed to how the library does it).\r
+\r
+There is a seperate implementation file (in ./function/{header}/) for\r
+every function defined by the standard, named {function}.c. Not only\r
+does this avoid linking in huge amounts of unused code when you use\r
+but a single function, it also allows the optimization overlay to work\r
+(see below).\r
+\r
+(The directory ./functions/_PDCLIB/ contains internal and helper\r
+functions that are not part of the standard.)\r
+\r
+Then there are internal header files (in ./internal/), which contain\r
+all the "black magic" and "code fu" that was kept out of the standard\r
+headers. You should not have to touch them if you want to adapt PDCLib\r
+to a new platform. Note that, if you *do* have to touch them, I would\r
+consider it a serious design flaw, and would be happy to fix it in the\r
+next PDCLib release. Any adaption work should be covered by the steps\r
+detailed below.\r
+\r
+For adapting PDCLib to a new platform (the trinity of CPU, operating\r
+system, and compiler), make a copy of ./platform/example/ named\r
+./platform/{your_platform}/, and modify the files of your copy to suit\r
+the constraints of your platform. When you are done, copy the contents\r
+of your platform directory over the source directory structure\r
+of PDCLib (or link them into the appropriate places). That should be\r
+all that is actually required to make PDCLib work for your platform.\r
+\r
+Future directions\r
+-----------------\r
+Obviously, full C89, C99 and C11 conformance; and full support for the \r
+applicable portions of C++98, C++03 and C++11 (the version which acomplishes \r
+this will be christened "1.0").\r
+\r
+Support for "optimization overlays." These would allow efficient \r
+implementations of certain functions on individual platforms, for example \r
+memcpy, strcpy and memset. This requires further work to only compile in one\r
+version of a given function.\r
+\r
+Post 1.0, support for C11 Annexe K "Bounds checking interfaces"\r
+\r
+Development Status\r
+------------------\r
+\r
+v0.1 - 2004-12-12\r
+Freestanding-only C99 implementation without any overlay, and missing\r
+the INTN_C() / UINTN_C() macros. <float.h> still has the enquire.c\r
+values hardcoded into it; not sure whether to include enquire.c in the\r
+package, to leave <float.h> to the overlay, or devise some parameterized\r
+macro magic as for <limits.h> / <stdint.h>. Not thoroughly tested, but\r
+I had to make the 0.1 release sometime so why not now.\r
+\r
+v0.2 - 2005-01-12\r
+Adds implementations for <string.h> (excluding strerror()), INTN_C() /\r
+UINTN_C() macros, and some improvements in the internal headers.\r
+Test drivers still missing, but added warnings about that.\r
+\r
+v0.3 - 2005-11-21\r
+Adds test drivers, fixes some bugs in <string.h>.\r
+\r
+v0.4 - 2005-02-06\r
+Implementations for parts of <stdlib.h>. Still missing are the floating\r
+point conversions, and the wide-/multibyte-character functions.\r
+\r
+v0.4.1 - 2006-11-16\r
+With v0.5 (<stdio.h>) taking longer than expected, v0.4.1 was set up as\r
+a backport of bugfixes in the current development code.\r
+- #1 realloc( NULL, size ) fails (fixed)\r
+- #2 stdlib.h - insufficient documentation (fixed)\r
+- #4 Misspelled name in credits (fixed)\r
+- #5 malloc() splits off too-small nodes (fixed)\r
+- #6 qsort() stack overflow (fixed)\r
+- #7 malloc() bug in list handling (fixed)\r
+- #8 strncmp() does not terminate at '\0' (fixed)\r
+- #9 stdint.h dysfunctional (fixed)\r
+- #10 NULL redefinition warnings (fixed)\r
+\r
+v0.5 - 2010-12-22\r
+Implementations for <inttypes.h>, <errno.h>, most parts of <stdio.h>,\r
+and strerror() from <string.h>.\r
+Still no locale / wide-char support. Enabled all GCC compiler warnings I\r
+could find, and fixed everything that threw a warning. (You see this,\r
+maintainers of Open Source software? No warnings whatsoever. Stop telling\r
+me it cannot be done.) Fixed all known bugs in the v0.4 release.\r
+\r
+Near Future\r
+-----------\r
+Current development directions are:\r
+\r
+Implement portions of the C11 standard that have a direct impact on the way \r
+that PDCLib itself is built. For example, in order to support multithreading,\r
+PDCLib needs a threading abstraction; therefore, C11's thread library is being\r
+implemented to provide the backing for this (as there is no purpose in \r
+implementing two abstractions)\r
+\r
+Cleanup portions of <stdio.h>, particularly the backend. _PDCLIB_fillbuffer and\r
+_PDCLIB_flushbuffer in particular do not feel 'well' factored and need to know\r
+too much about FILE's internals. \r
+\r
+Modularize the library somewhat. This can already be seen with components under \r
+"opt/". This structure is preliminary; it will likely change as the process \r
+continues.
\ No newline at end of file
projects / pdclib.old / blobdiff