#ifndef _PDCLIB_CONFIG_H
#define _PDCLIB_CONFIG_H
+
/* Internal PDCLib configuration <_PDCLIB_config.h>
(Gandr platform)
Permission is granted to use, modify, and / or redistribute at will.
*/
+/* -------------------------------------------------------------------------- */
+/* Misc */
+/* -------------------------------------------------------------------------- */
-
-/* end of line */
+/* The character (sequence) your platform uses as newline. */
#define _PDCLIB_endl "\n"
-/* exit() */
+/* exit() can signal success to the host environment by the value of zero or */
+/* the constant EXIT_SUCCESS. Failure is signaled by EXIT_FAILURE. Note that */
+/* any other return value is "implementation-defined", i.e. your environment */
+/* is not required to handle it gracefully. Set your definitions here. */
#define _PDCLIB_SUCCESS 0
#define _PDCLIB_FAILURE -1
-/* trivial memswp */
+/* qsort() in <stdlib.h> requires a function that swaps two memory areas. */
+/* Below is a naive implementation that can be improved significantly for */
+/* specific platforms, e.g. by swapping int instead of char. */
#define _PDCLIB_memswp( i, j, size ) char tmp; do { tmp = *i; *i++ = *j; *j++ = tmp; } while ( --size );
+/* -------------------------------------------------------------------------- */
+/* Integers */
+/* -------------------------------------------------------------------------- */
+/* Assuming 8-bit char, two's-complement architecture here. 'short' being */
+/* 16 bit, 'int' being either 16, 32 or 64 bit, 'long' being either 32 or 64 */
+/* bit (but 64 bit only if 'int' is 32 bit), and 'long long' being 64 bit if */
+/* 'long' is not, 64 or 128 bit otherwise. */
+/* Author is quite willing to support other systems but would like to hear of */
+/* interest in such support and details on the to-be-supported architecture */
+/* first, before going to lengths about it. */
+/* -------------------------------------------------------------------------- */
#if defined(__arm__)
- #define _PDCLIB_CHAR_SIGNED 0
+#define _PDCLIB_CHAR_SIGNED 0
#else
- #define _PDCLIB_CHAR_SIGNED 1
+#define _PDCLIB_CHAR_SIGNED 1
#endif
/* Width of the integer types short, int, long, and long long, in bytes. */
/* compiler manuals. */
#define _PDCLIB_SHRT_BYTES 2
#define _PDCLIB_INT_BYTES 4
-#if defined(__lp64__)
- #define _PDCLIB_LONG_BYTES 8
+#if defined(__LP64__)
+#define _PDCLIB_LONG_BYTES 8
#else
- #define _PDCLIB_LONG_BYTES 4
+#define _PDCLIB_LONG_BYTES 4
#endif
#define _PDCLIB_LLONG_BYTES 8
-/* layout of div_t, ldiv_t, lldiv_t */
-struct _PDCLIB_div_t { int quot; int rem; };
-struct _PDCLIB_ldiv_t { long int quot; long int rem; };
-struct _PDCLIB_lldiv_t { long long int quot; long long int rem; };
+/* <stdlib.h> defines the div() function family that allows taking quotient */
+/* and remainder of an integer division in one operation. Many platforms */
+/* support this in hardware / opcode, and the standard permits ordering of */
+/* the return structure in any way to fit the hardware. That is why those */
+/* structs can be configured here. */
+
+struct _PDCLIB_div_t
+{
+ int quot;
+ int rem;
+};
+
+struct _PDCLIB_ldiv_t
+{
+ long int quot;
+ long int rem;
+};
+
+struct _PDCLIB_lldiv_t
+{
+ long long int quot;
+ long long int rem;
+};
+
+/* -------------------------------------------------------------------------- */
+/* <stdint.h> defines a set of integer types that are of a minimum width, and */
+/* "usually fastest" on the system. (If, for example, accessing a single char */
+/* requires the CPU to access a complete int and then mask out the char, the */
+/* "usually fastest" type of at least 8 bits would be int, not char.) */
+/* If you do not have information on the relative performance of the types, */
+/* the standard allows you to define any type that meets minimum width and */
+/* signedness requirements. */
+/* The defines below are just configuration for the real typedefs and limit */
+/* definitions done in <_PDCLIB_int.h>. The uppercase define shall be either */
+/* SHRT, INT, LONG, or LLONG (telling which values to use for the *_MIN and */
+/* *_MAX limits); the lowercase define either short, int, long, or long long */
+/* (telling the actual type to use). */
+/* The third define is the length modifier used for the type in printf() and */
+/* scanf() functions (used in <inttypes.h>). */
+/* If you require a non-standard datatype to define the "usually fastest" */
+/* types, PDCLib as-is doesn't support that. Please contact the author with */
+/* details on your platform in that case, so support can be added. */
+/* -------------------------------------------------------------------------- */
-/* fast* datatypes. This is a bit of a blunt instrument. */
#define _PDCLIB_FAST8 CHAR
#define _PDCLIB_fast8 char
#define _PDCLIB_FAST8_CONV hh
#define _PDCLIB_fast64 long long
#define _PDCLIB_FAST64_CONV ll
-/* ptrdiff_t */
+/* -------------------------------------------------------------------------- */
+/* What follows are a couple of "special" typedefs and their limits. Again, */
+/* the actual definition of the limits is done in <_PDCLIB_int.h>, and the */
+/* defines here are merely "configuration". See above for details. */
+/* -------------------------------------------------------------------------- */
+
+/* The types used for size_t and ptrdiff_t should not have an integer conversion
+ rank greater than that of signed long int unless the implementation supports
+ objects large enough to make this necessary.
+*/
+
+/* Result type of substracting two pointers (must be signed) */
#define _PDCLIB_ptrdiff long
#define _PDCLIB_PTRDIFF LONG
#define _PDCLIB_PTR_CONV l
#define _PDCLIB_size unsigned long
#define _PDCLIB_SIZE ULONG
-/* intptr_t */
-#define _PDCLIB_intptr long
-#define _PDCLIB_INTPTR LONG
-
-/* sig_atomic_t */
+/* An integer type that can be accessed as atomic entity (think asynchronous
+ interrupts). The type itself is not defined in a freestanding environment,
+ but its limits are. (Don't ask.)
+*/
#define _PDCLIB_sig_atomic char
#define _PDCLIB_SIG_ATOMIC CHAR
-/* wint_t, wchar_t */
-#define _PDCLIB_wint signed int
+/* Object type whose alignment is as great as supported by implementation
+ in all contexts.
+*/
+#define _PDCLIB_max_align long double
+
+/* Integer type whose range of values can represent distinct codes for
+ all members of the largest extended character set specified among the
+ supported locales.
+ Note that the definition of this type must agree with the type used
+ by the compiler for L"" string and L'' character literals.
+*/
#define _PDCLIB_wchar unsigned int
#define _PDCLIB_WCHAR UINT
+/* Each member of the basic character set shall have a code value equal
+ to its value when used as the lone character in an integer character
+ constant. If that is not the case, uncomment the following line.
+#define __STDC_MB_MIGHT_NEQ_WC__
+*/
-/* Largest supported integer type */
+/* Integer type unchanged by default argument promotions that can hold any
+ value corresponding to characters of the extended character set, as well
+ as at least one value that does not correspond to any member of the
+ extended character set (WEOF).
+*/
+#define _PDCLIB_wint signed int
+
+#define _PDCLIB_intptr long
+#define _PDCLIB_INTPTR LONG
+
+/* Largest supported integer type. Implementation note: see _PDCLIB_atomax(). */
#define _PDCLIB_intmax long long int
#define _PDCLIB_INTMAX LLONG
#define _PDCLIB_MAX_CONV ll
+/* You are also required to state the literal suffix for the intmax type */
#define _PDCLIB_INTMAX_LITERAL ll
-struct _PDCLIB_imaxdiv_t { _PDCLIB_intmax quot; _PDCLIB_intmax rem; };
+/* <inttypes.h> defines imaxdiv(), which is equivalent to the div() function */
+/* family (see further above) with intmax_t as basis. */
+
+struct _PDCLIB_imaxdiv_t
+{
+ _PDCLIB_intmax quot;
+ _PDCLIB_intmax rem;
+};
-/* time_t */
+/* <time.h>: time_t
+ * The C standard doesn't define what representation of time is stored in
+ * time_t when returned by time() , but POSIX defines it to be seconds since the
+ * UNIX epoch and most appplications expect that.
+ *
+ * time_t is also used as the tv_sec member of struct timespec, which *is*
+ * defined as a linear count of seconds.
+ *
+ * time_t is defined as a "real type", so may be a floating point type, but with
+ * the presence of the nanosecond accurate struct timespec, and with the lack of
+ * any functions for manipulating more accurate values of time_t, this is
+ * probably not useful.
+ */
#define _PDCLIB_time unsigned long long
-/* clock_t */
+/* <time.h>: clock_t
+ *
+ * A count of "clock ticks", where the length of a clock tick is unspecified by
+ * the standard. The implementation is required to provide a macro,
+ * CLOCKS_PER_SEC, which is the number of "clock ticks" which corresponds to one
+ * second.
+ *
+ * clock_t may be any real type (i.e. integral or floating), and its type on
+ * various systems differs.
+ *
+ * On XSI systems, CLOCKS_PER_SEC must be defined to 1000000
+ */
#define _PDCLIB_clock unsigned
#define _PDCLIB_CLOCKS_PER_SEC 1000000
-/* timespec_get */
+/* <time.h>: TIME_UTC
+ *
+ * The TIME_UTC parameter is passed to the timespec_get function in order to get
+ * the system time in UTC since an implementation defined epoch (not necessarily
+ * the same as that used for time_t). That said, on POSIX the obvious
+ * implementation of timespec_get for TIME_UTC is to wrap
+ * clock_gettime(CLOCK_REALTIME, ...), which is defined as time in UTC since the
+ * same epoch.
+ *
+ * This may be any non-zero integer value.
+ */
#define _PDCLIB_TIME_UTC 1
/* -------------------------------------------------------------------------- */
#define _PDCLIB_FLOAT_TYPE SINGLE
#define _PDCLIB_DOUBLE_TYPE DOUBLE
#if defined(__i386__) || defined(__amd64__)
- #define _PDCLIB_LDOUBLE_TYPE EXTENDED
+#define _PDCLIB_LDOUBLE_TYPE EXTENDED
#else
- #define _PDCLIB_LDOUBLE_TYPE DOUBLE
+#define _PDCLIB_LDOUBLE_TYPE DOUBLE
#endif
/* -------------------------------------------------------------------------- */
/* Platform-dependent macros defined by the standard headers. */
/* -------------------------------------------------------------------------- */
-/* offsetof */
+/* The offsetof macro
+ Contract: Expand to an integer constant expression of type size_t, which
+ represents the offset in bytes to the structure member from the beginning
+ of the structure. If the specified member is a bitfield, behaviour is
+ undefined.
+ There is no standard-compliant way to do this.
+ This implementation casts an integer zero to 'pointer to type', and then
+ takes the address of member. This is undefined behaviour but should work on
+ most compilers.
+*/
#define _PDCLIB_offsetof( type, member ) __builtin_offsetof( type, member )
-/* stdarg.h */
+/* Variable Length Parameter List Handling (<stdarg.h>)
+ The macros defined by <stdarg.h> are highly dependent on the calling
+ conventions used, and you probably have to replace them with builtins of
+ your compiler.
+*/
+
typedef __builtin_va_list _PDCLIB_va_list;
#define _PDCLIB_va_arg( ap, type ) (__builtin_va_arg( (ap), type ))
#define _PDCLIB_va_copy( dest, src ) (__builtin_va_copy( (dest), (src) ))
#define _PDCLIB_va_end( ap ) (__builtin_va_end( ap ) )
#define _PDCLIB_va_start( ap, parmN ) (__builtin_va_start( (ap), (parmN) ))
-/* "OS glue" */
+/* -------------------------------------------------------------------------- */
+/* OS "glue", part 1 */
+/* These are values and data type definitions that you would have to adapt to */
+/* the capabilities and requirements of your OS. */
+/* The actual *functions* of the OS interface are declared in _PDCLIB_glue.h. */
+/* -------------------------------------------------------------------------- */
/* Memory management -------------------------------------------------------- */
+/* Set this to the page size of your OS. If your OS does not support paging, set
+ to an appropriate value. (Too small, and malloc() will call the kernel too
+ often. Too large, and you will waste memory.)
+*/
#define _PDCLIB_MALLOC_PAGESIZE 4096
#define _PDCLIB_MALLOC_ALIGN 16
#define _PDCLIB_MALLOC_GRANULARITY 4096
#define _PDCLIB_MALLOC_MMAP_THRESHOLD 256*1024
#define _PDCLIB_MALLOC_RELEASE_CHECK_RATE 4095
+/* TODO: Better document these */
+
/* Locale --------------------------------------------------------------------*/
/* Locale method. See _PDCLIB_locale.h. If undefined, POSIX per-thread locales
- * will be disabled
- */
+ will be disabled
+*/
/* #define _PDCLIB_LOCALE_METHOD _PDCLIB_LOCALE_METHOD_TSS */
/* wchar_t encoding */
/* The default size for file buffers. Must be at least 256. */
#define _PDCLIB_BUFSIZ 1024
+/* We need \n -> \r\n translation for text files */
+#define _PDCLIB_NEED_EOL_TRANSLATION 1
+
/* Minimum number of files we can open simultaneously. C says this must be >= 8,
* so we say that. May actually be a lie in some cases...
*/
/* Number of distinct file names that can be generated by tmpnam(). */
#define _PDCLIB_TMP_MAX 50
-/* SEEK_SET, CUR, END */
+/* The values of SEEK_SET, SEEK_CUR and SEEK_END, used by fseek().
+ Since at least one platform (POSIX) uses the same symbols for its own "seek"
+ function, we use whatever the host defines (if it does define them).
+*/
#define _PDCLIB_SEEK_SET 0
#define _PDCLIB_SEEK_CUR 1
#define _PDCLIB_SEEK_END 2
-/* How much can you ungetc? Not much, thankfully */
+/* The number of characters that can be buffered with ungetc(). The standard
+ guarantees only one (1); anything larger would make applications relying on
+ this capability dependent on implementation-defined behaviour (not good).
+*/
#define _PDCLIB_UNGETCBUFSIZE 1
/* errno -------------------------------------------------------------------- */
-/* errno values as per C++11 */
-#define _PDCLIB_ERANGE 1
-#define _PDCLIB_EDOM 2
-#define _PDCLIB_EILSEQ 3
-#define _PDCLIB_E2BIG 4
-#define _PDCLIB_ECONNRESET 5
-#define _PDCLIB_EISCONN 6
-#define _PDCLIB_ENOENT 7
-#define _PDCLIB_ENOTRECOVERABLE 8
-#define _PDCLIB_EROFS 9
-#define _PDCLIB_EACCES 10
-#define _PDCLIB_EDEADLK 11
-#define _PDCLIB_EISDIR 12
-#define _PDCLIB_ENOEXEC 13
-#define _PDCLIB_ENOTSOCK 14
-#define _PDCLIB_ESPIPE 15
-#define _PDCLIB_EADDRINUSE 16
-#define _PDCLIB_EDESTADDRREQ 17
-#define _PDCLIB_ELOOP 18
-#define _PDCLIB_ENOLCK 19
-#define _PDCLIB_ENOTSUPP 20
-#define _PDCLIB_ESRCH 21
-#define _PDCLIB_EADDRNOTAVAIL 22
-#define _PDCLIB_EMFILE 23
-#define _PDCLIB_ENOLINK 24
-#define _PDCLIB_ENOTTY 25
-#define _PDCLIB_ETIME 26
-#define _PDCLIB_EAFNOSUPPORT 27
-#define _PDCLIB_EEXIST 28
-#define _PDCLIB_EMLINK 29
-#define _PDCLIB_ENOMEM 30
-#define _PDCLIB_ENXIO 31
-#define _PDCLIB_ETIMEDOUT 32
-#define _PDCLIB_EAGAIN 33
-#define _PDCLIB_EFAULT 34
-#define _PDCLIB_EMSGSIZE 35
-#define _PDCLIB_ENOMSG 36
-#define _PDCLIB_EOPNOTSUPP 37
-#define _PDCLIB_ETXTBSY 38
-#define _PDCLIB_EALREADY 39
-#define _PDCLIB_EFBIG 40
-#define _PDCLIB_ENAMETOOLONG 41
-#define _PDCLIB_ENOPROTOOPT 42
-#define _PDCLIB_EOVERFLOW 43
-#define _PDCLIB_EWOULDBLOCK _PDCLIB_EAGAIN
-#define _PDCLIB_EBADF 44
-#define _PDCLIB_EHOSTUNREACH 45
-#define _PDCLIB_ENETDOWN 46
-#define _PDCLIB_ENOSPC 47
-#define _PDCLIB_EOWNERDEAD 48
-#define _PDCLIB_EXDEV 49
-#define _PDCLIB_EBADMSG 50
-#define _PDCLIB_EIDRM 51
-#define _PDCLIB_ENETRESET 52
-#define _PDCLIB_ENOSR 53
-#define _PDCLIB_EPERM 54
-#define _PDCLIB_EBUSY 55
-#define _PDCLIB_ENETUNREACH 56
-#define _PDCLIB_ENOSTR 57
-#define _PDCLIB_EPIPE 58
-#define _PDCLIB_ECANCELED 59
-#define _PDCLIB_EINPROGRESS 60
-#define _PDCLIB_ENFILE 61
-#define _PDCLIB_ENOSYS 62
-#define _PDCLIB_EPROTO 63
-#define _PDCLIB_ECHILD 64
-#define _PDCLIB_EINTR 65
-#define _PDCLIB_ENOBUFS 66
-#define _PDCLIB_ENOTCONN 67
-#define _PDCLIB_EPROTONOSUPPORT 68
-#define _PDCLIB_ECONNABORTED 69
-#define _PDCLIB_EINVAL 70
-#define _PDCLIB_ENODATA 71
-#define _PDCLIB_ENOTDIR 72
-#define _PDCLIB_EPROTOTYPE 73
-#define _PDCLIB_EIO 74
-
-#define _PDCLIB_ERRNO_MAX 74
+/* These are the values that _PDCLIB_errno can be set to by the library.
+
+ By keeping PDCLib's errno in the _PDCLIB_* namespace, the library is capable
+ to "translate" between errno values used by the hosting operating system and
+ those used and passed out by the library.
+
+ Example: In the example platform, the remove() function uses the unlink()
+ system call as backend. Linux sets its errno to EISDIR if you try to unlink()
+ a directory, but POSIX demands EPERM. Within the remove() function, you can
+ catch the 'errno == EISDIR', and set '_PDCLIB_errno = _PDCLIB_EPERM'. Anyone
+ using PDCLib's <errno.h> will "see" EPERM instead of EISDIR (the _PDCLIB_*
+ prefix removed by <errno.h> mechanics).
+
+ If you do not want that kind of translation, you might want to "match" the
+ values used by PDCLib with those used by the host OS, as to avoid confusion.
+
+ The C standard only defines three distinct errno values: ERANGE, EDOM, and
+ EILSEQ. The standard leaves it up to "the implementation" whether there are
+ any more beyond those three.
+
+ However, C++11 introduced the whole list of POSIX errno values into the
+ standard, so PDCLib might as well define those as well.
+
+ Sometimes the standard says to set errno to indicate an error, but does not
+ prescribe a value. We will use a value from the following list. If POSIX
+ defines a value, we use that; otherwise, we use as seems suitable.
+*/
+
+#define _PDCLIB_ERANGE 1
+#define _PDCLIB_EDOM 2
+#define _PDCLIB_EILSEQ 3
+#define _PDCLIB_E2BIG 4
+#define _PDCLIB_ECONNRESET 5
+#define _PDCLIB_EISCONN 6
+#define _PDCLIB_ENOENT 7
+#define _PDCLIB_ENOTRECOVERABLE 8
+#define _PDCLIB_EROFS 9
+#define _PDCLIB_EACCES 10
+#define _PDCLIB_EDEADLK 11
+#define _PDCLIB_EISDIR 12
+#define _PDCLIB_ENOEXEC 13
+#define _PDCLIB_ENOTSOCK 14
+#define _PDCLIB_ESPIPE 15
+#define _PDCLIB_EADDRINUSE 16
+#define _PDCLIB_EDESTADDRREQ 17
+#define _PDCLIB_ELOOP 18
+#define _PDCLIB_ENOLCK 19
+#define _PDCLIB_ENOTSUP 20
+#define _PDCLIB_ESRCH 21
+#define _PDCLIB_EADDRNOTAVAIL 22
+#define _PDCLIB_EMFILE 23
+#define _PDCLIB_ENOLINK 24
+#define _PDCLIB_ENOTTY 25
+#define _PDCLIB_ETIME 26
+#define _PDCLIB_EAFNOSUPPORT 27
+#define _PDCLIB_EEXIST 28
+#define _PDCLIB_EMLINK 29
+#define _PDCLIB_ENOMEM 30
+#define _PDCLIB_ENXIO 31
+#define _PDCLIB_ETIMEDOUT 32
+#define _PDCLIB_EAGAIN 33
+#define _PDCLIB_EFAULT 34
+#define _PDCLIB_EMSGSIZE 35
+#define _PDCLIB_ENOMSG 36
+#define _PDCLIB_EOPNOTSUPP 37
+#define _PDCLIB_ETXTBSY 38
+#define _PDCLIB_EALREADY 39
+#define _PDCLIB_EFBIG 40
+#define _PDCLIB_ENAMETOOLONG 41
+#define _PDCLIB_ENOPROTOOPT 42
+#define _PDCLIB_EOVERFLOW 43
+#define _PDCLIB_EWOULDBLOCK _PDCLIB_EAGAIN
+#define _PDCLIB_EBADF 44
+#define _PDCLIB_EHOSTUNREACH 45
+#define _PDCLIB_ENETDOWN 46
+#define _PDCLIB_ENOSPC 47
+#define _PDCLIB_EOWNERDEAD 48
+#define _PDCLIB_EXDEV 49
+#define _PDCLIB_EBADMSG 50
+#define _PDCLIB_EIDRM 51
+#define _PDCLIB_ENETRESET 52
+#define _PDCLIB_ENOSR 53
+#define _PDCLIB_EPERM 54
+#define _PDCLIB_EBUSY 55
+#define _PDCLIB_ENETUNREACH 56
+#define _PDCLIB_ENOSTR 57
+#define _PDCLIB_EPIPE 58
+#define _PDCLIB_ECANCELED 59
+#define _PDCLIB_EINPROGRESS 60
+#define _PDCLIB_ENFILE 61
+#define _PDCLIB_ENOSYS 62
+#define _PDCLIB_EPROTO 63
+#define _PDCLIB_ECHILD 64
+#define _PDCLIB_EINTR 65
+#define _PDCLIB_ENOBUFS 66
+#define _PDCLIB_ENOTCONN 67
+#define _PDCLIB_EPROTONOSUPPORT 68
+#define _PDCLIB_ECONNABORTED 69
+#define _PDCLIB_EINVAL 70
+#define _PDCLIB_ENODATA 71
+#define _PDCLIB_ENOTDIR 72
+#define _PDCLIB_EPROTOTYPE 73
+#define _PDCLIB_EIO 74
+#define _PDCLIB_ECONNREFUSED 75
+#define _PDCLIB_ENODEV 76
+#define _PDCLIB_ENOTEMPTY 77
+
+/* This is used to set the size of the array in struct lconv (<locale.h>) */
+/* holding the error messages for the strerror() and perror() fuctions. If */
+/* you change this value because you are using additional errno values, you */
+/* *HAVE* to provide appropriate error messages for *ALL* locales. */
+/* Needs to be one higher than the highest errno value above. */
+#define _PDCLIB_ERRNO_MAX 78
#endif