===== Policy on Extensions =====

The documentation below refers to the ''shepherd'' branch.

==== Design Intentions ====

PDCLib intends to be a strict, fully conforming implementation of the runtime library component of the ISO C standard, and the portion of said library incorporated into the ISO C++ standard. It is not intended to conform to POSIX, nor the Signal Unix Specification or any other OS standard.

That said, there are some extensions (defined by POSIX or otherwise) which are widely used and applicable, not OS dependent, and do not duplicate functionality already in the standard. Examples of these include

  * strdup
  * strndup
  * The OpenBSD strl* series of functions

The outright ruling out of extensions would therefore be both painful to software developers and make the porting of code to PDCLib based systems unduly more difficult. It is therefore necessary to have a policy on extensions.

==== Requirements for the consideration of an extension ====

  * Widely used: It must be implemented by more than one existing system
  * Clean semantics: The semantics of it must be tightly defined
  * Not OS dependent: It must not expose any facet of the underlying operating system not defined by the C standard. For example, fdopen is a widely used POSIX function, but its inclusion would expose "file descriptors" to the end user, therefore it is excluded
  * Not redundant with functionality contained within the C standard: For example, posix_memalign is widely used, but C11 introduces aligned_alloc, which duplicates its functionality
  * Require no or minimal additional support from the host OS: The extension should not require significant additional support from the OS glue layer than that already required by the standard. 

==== Exposure of Extensions ====

Extensions are all disabled by default, and must be explicitly requested. The methods of doing this are:

  * Define _PDCLIB_ALL. This will expose every function PDCLib implements; where a function has been changed by successive versions of a standard, it will expose the latest version
  * Define the appropriate extension macro as defined by the originating standard. At present, supported macros are _XOPEN_SOURCE and _POSIX_C_SOURCE.

==== Implemented Extensions ====

  * strdup (POSIX 2008, XSI)
  * strndup (POSIX 2008)
  * strnlen (POSIX 2008)

==== Extensions under consideration ====

  * BSD strl*
  * open_memstream, open_wmemstream, fmemopen (POSIX 2008)