This is libsupp 6.2 for MSDOS/DJGPP.


1.:    Introduction.
       =============

       This is a support library for DJGPP 2.04 and 2.03.  It shall provide a
       small set of new functions that still have not been implemented for DJGPP
       or improved versions of functions from DJGPP's CVS source tree so that
       the original functions provided with DJGPP's libc.a (2.04 and 2.03) can
       be replaced with these new ones.
       The decision which function is part and which one is not part of this
       library is based on the usefulness for porting current GNU packages.  If
       the amount of provided functions increases in the future will depend on
       the requirements of the GNU packages to be ported.


       This release provides fixed or improved versions of certain headers and
       functions.  To easy porting efforts a little bit the following issues have
       been tackled:
       1: libsupp.h has been modified to:
          - provide sane defaults for the family of macros SA_NOCLDSTOP,
            SA_RESTART, SA_NODEFER, SA_RESETHAND, SA_ONESHOT and SA_NOMASK.
            These macros are not are neither supported not defined by DJGPP so
            they have been defined to zero.  This shall make porting efforts
            easier in all those cases where inconditionaly it is assumed that
            the macros are defined.
          - define _O_TEMPORARY as an alias for O_TEMPORARY if not defined.
            This shall make porting efforts easier in all those cases where
            inconditionaly it is checked for _O_TEMPORARY and not for O_TEMPORARY.
       2: The function _doscan() and the scanf family of functions have been
          improved to support the %[aA] conversion specifier.  To implement this
          support the atof() and _atold() functions had to be adjusted to call
          the modified stro[fdld] family of functions.
       3: The functions fopen() and open() have been improved to be more POSIX
          compliant.  If the filename ends in a slash and one of the modes
          O_CREAT, O_WRONLY or O_RDWR is specified, then the functions will
          fail with EISDIR.  Also if the filename ends in a slash and the file
          descriptor of the named file without the slash does not refer to a
          directory, then the functions will fail with ENOTDIR.  The same
          modifications are provided for the 2.03 versions of fopen() and
          open().
       4: GCC-4.4.X specific definitions for va_arg, va_start and va_end have
          been added.
       5: towupper() is a wrapper to toupper().  If the wchar is less than 0xFF,
          it is passed to toupper, else it is returned unaltered.
       6: To have a consistent file handling with djgpp 2.03 an d2.04 the
          following files have been added:
          - for 2.03:  fclose_2_03, fflush_2_03, _flsbuf_2_03, fopen_2_03,
            freopen_2_03, fseek_2_03, ftell_2_03, rewind_2_03, select_2_03,
            fsync_2_03, ftruncate_2_03, _close_2_03, _write_2_03, fcntl_2_03,
            fdopen_2_03, dup2_2_03, dup_2_03, lseek_2_03, read_2_03, write_2_03
            and fstat_2_03
          - for 2.04: fclose, fflush, _flsbuf, fopen, freopen, fseek, ftell,
            rewind, select, fsync, ftruncate, llseek, _close, _write,
            _write_fill_seek_gap, _write_int, fcntl, open, fdopen, fchmod,
           fstat, stat, fstatvfs, close, dup2, dup, lseek, pipe, read, write
           and lfilelength
       appart of the other ones that have already been added before.  The 2.03
       ones are only available when djdev203 is used; the 2.04 versions are only
       available when using djdev204.  It is not the intention to make 2.04
       functionality available to 2.03.



       The following functions have already been provided in previous versions
       of this library:
         mblen()
         mbsinit()
         mbrtowc()
         mbtowc()
         access()
         __chdir()
         _fixpath()
         __canonicalize_path()
         realpath()
         lstat()    only for 2.04
         stat()     only for 2.03
         symlink()  only for 2.03
         opendir()
         readdir()
         rewinddir()
         __set_need_fake_dot_dotdot()
         open()
         close()
         fchdir()
         strndup()
         strnlen()
         argz_add()
         argz_add_sep()
         argz_append()
         argz_count()
         argz_create()
         argz_createsep()
         argz_delete()
         argz_extract()
         argz_insert()
         argz_next()
         argz_replace()
         argz_stringify()
         strtod()
         strtof()
         strtold()
         signbit()
         __signbitd()
         __signbitf()
         __signbitld()
         asnprintf()
         asprintf()
         cprintf()
         fprintf()
         fseeko()
         ftello()
         printf()
         snprintf()
         sprintf()
         vasnprintf()
         vasprintf()
         vfprintf()
         vprintf()
         vsnprntf()
         vsprintf()
         _doprnt()


       Version 6.1:
       ============
       This is a bug fix release.
       The following functions have been reimplemented:
         mblen()
         mbsinit()
         mbrtowc()
         mbtowc()
       They work all with a mbstate_t structure like the one defined by GNU glibc
       instead of the one provided by DJGPP's libc.  Please note that although
       the structure records the conversion state no reentrancy neither support
       for anything else than POSIX/C locale is provided.  Also note that the
       structure and the functions replace the ones that come with DJGPP, so
       you cannot use both in the same code segment.  The only reason to provide
       these functions is to ease porting efforts.  If you prefer to use the
       versions of these functions that come with DJGPP's libc.a, then use the
       macro USE_DJGPP_MBTOWC_FCTNS like this:
         gcc -DUSE_DJGPP_MBTOWC_FCTNS -O2 -c code.c
       or define it in your source file before including libsupp.h:
         #define  USE_DJGPP_MBTOWC_FCTNS
         #include <libsupp.h>
       If USE_DJGPP_MBTOWC_FCTNS is not defined always the libsupp versions will
       be used else the DJGPP versions will be used.


       Version 6.0:
       ============
       The following function:
         strftime()
       has been modified to improve the compatibility with GNU glibc.
       The following functions have been implemented:
         towlower()
         mbsinit()
         mbrtowc()
         memmem()
         strlcat()
         strlcpy()
       1) towlower() is a wrapper to tolower().  If the wchar is less than 0xFF,
       it is passed to tolower, else it is returned unaltered.  It is implemented
       to ease porting efforts.
       2) mbsinit() is implemented for easing porting efforts.
       3) mbrtowc() is a wrapper to mbtowc() with the goal to ease porting efforts.
       The wrapper does not provide any reentrant capability .
       4) memmem() is a GNU compatibility function to ease porting efforts.
       5) strlcat() and strlcpy() are replacement versions of the functions
       that are part of DJGPP's libc.  These routines have been deliberately
       designed to not require any assistance from the standard libraries.
       They have been coded and contributed by C.B. Falconer.  The original
       archive that includes the original BSD documentation can be downloaded
       as:
         <http://cbfalconer.home.att.net/download/strlcpy.zip>
       If you prefer to use the versions of these functions that come with
       libc.a, then use the macro USE_DJGPP_STRL_FCTNS like this:
         gcc -DUSE_DJGPP_STRL_FCTNS -O2 -c code.c
       or define it in your source file before including libsupp.h:
         #define  USE_DJGPP_STRL_FCTNS
         #include <libsupp.h>
       If USE_DJGPP_STRL_FCTNS is not defined always the libsupp versions will
       be used.


       Version 5.3:
       ============
       This is a bug fix release.
       One issue has been fixed in function:
         __canonicalize_path

       __canonicalize_path, that is used by realpath and _fixpath, will no
       longer set errno to ENOSYS to signal that the used OS does not provide
       a LFN API.  This value of errno does not reflect the result of the
       operation preformed to canonicalize the given path and will confuse the
       calling function of realpath or _fixpath.  This bug appears in both
       versions of libc.a, the one of djdev204 and the one of djdev203.


       Version 5.2:
       ============
       This is a bug fix release.
       Two issues have been fixed in function:
         __get_current_directory

       1) Apart from upper case drive specifier characters, now lower case
          drive specifier characters will also be recognized as valid drive
          specifiers.
       2) For WinNT/2K/XP with LFN enabled if the CWD is the root directory,
          a malformed path string is returned as canonicalized path by _fixpath
          and realpath.  For example if the path string "foo/bar" was passed as
          argument to _fixpath, "C:\/foo/bar" will be returned, assuming that
          CWD is "c:/".  Please note the backslash after the drive specifier.
       This bug appears in both versions of libc.a, the one of djdev204 and the
       one of djdev203.  __get_current_directory() is an internal function of
       __canonicalize_path() that is used by _fixpath, realpath, lstat and some
       others file system functions.  This implies that this version of libsupp
       will provide all functions that depend of the patched function to replace
       their original versions of libc.a.  These are:
          access()
          __chdir()
          _fixpath()
          __canonicalize_path()
          realpath()
          lstat()    only for 2.04
          stat()     only for 2.03
          symlink()  only for 2.03
       Depending of the value of __DJGPP_MINOR__ ones or the other ones will be
       available.


       Version 5.1:
       ============
       This is a bug fix release.
       The implementation of the following function was brocken and has been
       fixed:
         strndup()
       and the missed function:
         closedir()
       has been added.
       A new fix provided by Andris Pavenis for include/ieeefp.h has been
       applied and the no longer need fix for emu387.cc has been removed.
       Also a bug fix in the symlink supporting code in readdir has been added.


       Version 5.0:
       ============
       The following functions have been modified to fix a bug.
         opendir()
         readdir()
         rewinddir()
         __set_need_fake_dot_dotdot()
       The bug is in the code segment of readdir() that handles with symlink
       files and thus is only triggerd if the file is a symlink.  The reason
       for the bug is the different assumption about what should be the content
       of member string "name" in the structure "DIR".  In the version fixed by
       me, the containt of "name" will be canonicalized path as returned by
       _fixpath() with an appended slash.  The function versions of djdev203
       have the same "malformed" path in "name" but because they have not the
       symlink code, they do not need to be modified.  This means, that only if
       you compile your application with djdev204.zip, the above mentioned
       functions will be replaced by the ones provided by this version of
       libsupp.
       It should be noticed that the dirent structure provided with libsupp is
       the same than the one defined in djdev204.  This means that it will
       provide the mode member.

       To ease the porting of POSIX centric source code for people still using
       djdev203, the following functions are provided:
         open()
         close()
         fchdir()
       These functions have been taken from the CVS reporitory and have been
       striped from the whole symlink support.  The goal is to have necessary
       POSIX support available to open directories using fchdir().  Because the
       symlink support has been completely removed, the mode bits O_NOLINK and
       and O_NOFOLLOW will be ignored.  These functions are only intended to be
       used with djdev203 and will only be available if __DJGPP_MINOR__ is
       equal '3'.


       Version 4.0:
       ============
       The strndup() and strnlen() functions have been implemented to improve
       compatibility with GNU glibc.


       Version 3.0:
       ============
       The argz functions store strings in a contiguous chunk of memory using
       '\0' as separator token. They are GNU extensions to glibc and have been
       implemented to make porting easier.

       The strto[dfld] functions now support the conversion of the hex format
       strings like this:
         "0xh.hhhhP[+|-]ddd"
       into variables of the type float, double and long double.


       Version 2.0:
       ============
       signbit returns 0 if the sign of the mantissa of a floating point number
       is positive; if the sign is negative it returns non-zero.  __signbit[dfld]
       are the internal implementations and should not be called except through
       the macro signbit.

       fseeko() and ftello() are wrappers for fseek() and ftell().


       Version 1.0:
       ============
       Apart from the features already provided by the familiy of printf()
       functions from djdev204, this version of the functions will provide:
         1: Flags.
            ': This flag allows to format the integer part with the thousands'
               character.  Because DJGPP only offers C/POSIX locale and this
               do not define a thousands' character the flag is ignored.
         2: Length modifiers.
            DJGPP provides all of them.
         3: Conversion specifiers.
            %F: 'F' Has been added and works like 'f'.
         %[aA]: With this conversion specifier a floating point number will be
                converted in the style "[-]0xh.hhhhp[-]d", where h are hexadecimal
                digits, p stands for the power of 2 and d is exponent expressed
                in decimal digits.  %a prints lower case characters and %A
                prints upper case characters.
           %n$: This implementation of printf family of functions also supports
           *n$  numbered conversion specifiers (%n$ for defining the position
                of the argument to be printed in the argument list, and *n$ for
                defining the position of the field width and precision to be
                used in the argument list).
         4: To increase compatibility with glibc's printf, _doprnt() has been
            changed to return for 80 bit floating point numbers starting with
            0 integer bit and non-zero exponent (Pseudo-NaN, Pseudo-Infinity,
            Pseudo-Zero and denormalized numbers (unnormal)) "nan" or "NAN"
            instead of "Unnormal" as used to be.  This may break backward
            compatibility but makes it easier to port GNU programs.

       To be able to use the new functions you will have to include the header
       (libsupp.h) in your source code.  This header will provide the macros
       to map the conventional function names to their real library names.
       All library names start with the prefix "libsupp_".  E.g.:
         printf --> libsupp_printf
       If you still use djdev203 then the header will also provide the data
       types definitions for intmax_t and uintmax_t.  The definitios have been
       taken from stdint.h and I have not been able to figure out a way to
       check if your code already provides a definition of these data types,
       so these are always defined and this may trigger warnings or errors when
       your code is compiled.  If this happens it will be your job to fix your
       code.

       Because the provided functions depend on other libc functions, this
       library must be linked before the standard C library, libc.a, is linked
       into your programs by gcc.  E.g.:
         gcc -Wall -O2 prog.c -lsupp

       The /diffs directory contains two patches that documents the changes I
       have done.  The diffs-cvs patch shows all changes I have done against
       the sources stored in the CVS tree as checked out on 2008-09-17.  The
       second patch is diffs-lib and shows the changes against the *patched*
       checked out CVS sources that are required to create the sources of this
       library.  It is your choice if you prefer to check out the CVS sources,
       patch them using diffs-cvs and build your own libc.a with the proposed
       new functionality or if you prefer to continue using libc.a distributed
       by djdev203 or djdev204 together with this library.



2.:    Installation.
       =============

       The binary package provides a header file, libsupp.h, the library file,
       libsupp.a, and the info docs.  All this is installed in the standard
       places of your DJGPP installation tree.  Copy the binary distribution
       into the top DJGPP installation directory, just unzip it preserving
       the directory structure running *one* of the following commands:
         unzip32 lsuppNNa.zip      or
         djtarx lsuppNNa.zip       or
         pkunzip -d lsuppNNa.zip
       where NN stands for the current version of the library.
       You must add an entry in your /info/dir file to be able to read the
       docs.  Edit manually your /info/dir and add the following lines:

From lsuppNNa.zip

* libsupp.a: (libsupp).
	The Support Library Reference




3.:    Building the binaries from sources.
       ===================================

       The library can *only* be build with *djdev204*.

3.1.:  Create a temporary directory and copy the source package into the
       directory.  Just unzip it preserving the directory structure running
       *one* of the following commands:
         unzip32 lsuppNNs.zip      or
         djtarx lsuppNNs.zip       or
         pkunzip -d lsuppNNs.zip

3.2.:  To build the library cd into the top srcdir and run the shell script
       like this:
         sh mklib.sh
       The script accepts only a single optional argument that specifies the
       installation directory.  If it is omitted the products will be stored
       in the /_build_ directory created in the top srcdir.
       The script will build the library and the info docs; if everything is
       successfully build then the test program in the /tests directory is
       build and started.  The output of the test program is stored in
       /tests/test.txt for inspection.  During the building of the test
       program a lot of warnings will appear.  This is intentional to test
       that the compiler recognizes the new functions as functions of the type
       of printf family and produces the typical warnings if flag combinations
       are used that are not allowed or defined.

       You *cannot* build the library with djdev203.  If you want to run the
       test program with djdev203 and the library, compile it with a command
       like this:
         gcc -Wall -O2 test.c -o test.exe -lsupp
       start it and inspect the output stored in test.txt.

       The description of printf() can be found at:
         <http://www.opengroup.org/onlinepubs/000095399/functions/printf.html>
       The description of signbit() can be found at:
         <http://www.opengroup.org/onlinepubs/000095399/functions/signbit.html>
       The description of strto[dfld]() can be found at:
         <http://www.opengroup.org/onlinepubs/000095399/functions/strtod.html>



       Send suggestions and bug reports concerning the library to
       comp.os.msdos.djgpp or <djgpp@delorie.com>.


Enjoy.

       Guerrero, Juan Manuel <juan.guerrero@gmx.de>
