X-Git-Url: https://pd.if.org/git/?p=pdclib;a=blobdiff_plain;f=platform%2Fexample%2Finternals%2F_PDCLIB_config.h;h=0059a7f6d9b9c41975e43bbb7eef0d46f8215619;hp=0f0c21c7e5fc5ea02dacbb43a3a74ebc5a6c7cb0;hb=ce0e5d8cd76b50f239fb8e95170502b146247b35;hpb=01c88bc38e78e9b2c47917b85b9b497187946e3c diff --git a/platform/example/internals/_PDCLIB_config.h b/platform/example/internals/_PDCLIB_config.h index 0f0c21c..0059a7f 100644 --- a/platform/example/internals/_PDCLIB_config.h +++ b/platform/example/internals/_PDCLIB_config.h @@ -32,6 +32,14 @@ /* to nothing. (This is to avoid warnings with the exit functions under GCC.) */ #define _PDCLIB_NORETURN __attribute__(( noreturn )) +/* The maximum value that errno can be set to. This is used to set the size */ +/* of the array in struct lconv () holding error messages for the */ +/* strerror() and perror() functions. (If you change this value because you */ +/* are using additional errno values, you *HAVE* to provide appropriate error */ +/* messages for *ALL* locales.) */ +/* Default is 2 (0, ERANGE, EDOM). */ +#define _PDCLIB_ERRNO_MAX 3 + /* -------------------------------------------------------------------------- */ /* Integers */ /* -------------------------------------------------------------------------- */ @@ -286,38 +294,60 @@ typedef int _PDCLIB_fd_t; */ #define _PDCLIB_UNGETCBUFSIZE 1 -/* Signals ------------------------------------------------------------------ */ +/* errno -------------------------------------------------------------------- */ + +/* These are the values that _PDCLIB_errno can be set to by the library. -/* A word on signals, to the people using PDCLib in their OS projects. + 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. - The way they are defined by the C standard severely limits their usefulness, - to the point where a library implementation need not interface with the OS' - signals at all (which is what the PDCLib example implementation does). - (Other issues include, for example, that signal handlers are not re-entrant.) + 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 will "see" EPERM instead of EISDIR (the _PDCLIB_* + prefix removed by mechanics). - Thus, it is strongly discouraged to try bolting on a signal handling infra- - structure onto . Since C's signal handling is so limited to begin - with, and code using it is pretty much non-portable anyway, it would be - smarter to keep in the barely functional state it is in, and - instead create a better, OS-specific API. + 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. - That being said, the below signals require to be defined to a positive int - value. I took what my Linux box defined them to; if you have to change them, - and what value to change them *to*, depends heavily on your environment and - what you are expecting to accomplish (see above). + The 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. There is some controversy as to whether errno is + such a good idea at all, so you might want to come up with a different error + reporting facility for your platform. Since errno values beyond the three + defined by the standard are not portable anyway (unless you look at POSIX), + having your own error reporting facility would not hurt anybody either. */ -#define _PDCLIB_SIGABRT 6 -#define _PDCLIB_SIGFPE 8 -#define _PDCLIB_SIGILL 4 -#define _PDCLIB_SIGINT 2 -#define _PDCLIB_SIGSEGV 11 -#define _PDCLIB_SIGTERM 15 - -/* The following should be defined to pointer values that could NEVER point to - a valid function. (They are used as special arguments to signal().) Again, I - took the values of my Linux box, which should be as good as any other value. +#define _PDCLIB_ERANGE 1 +#define _PDCLIB_EDOM 2 +#define _PDCLIB_EILSEQ 3 + +/* The following is not strictly "configuration", but there is no better place + to explain it than here. + + PDCLib strives to be as generic as possible, so by default it does NOT define + any values beyond the three standard ones above, even where it would have + been prudent and convenient to do so. Any errno "caught" from the host OS, + and some internal error conditions as well, are all lumped together into the + value of '_PDCLIB_ERROR'. + + '_PDCLIB_ERROR' is STRICLY meant as a PLACEHOLDER only. + + You should NEVER ship an adaption of PDCLib still using that particular + value. You should NEVER write code that *tests* for that value. Indeed it is + not even conforming, since errno values should be defined as beginning with + an uppercase 'E', and there is no mechanics in to unmask that + particular value (for exactly that reason). + + The idea is that you scan the source of PDCLib for occurrences of this macro + and replace _PDCLIB_ERROR with whatever additional errno value you came up + with for your platform. + + If you cannot find it within you to do that, tell your clients to check for + an errno value larger than zero. That, at least, would be standard compliant + (and fully portable). */ -#define _PDCLIB_SIG_DFL (void (*)( int ))0 -#define _PDCLIB_SIG_ERR (void (*)( int ))-1 -#define _PDCLIB_SIG_IGN (void (*)( int ))1 +#define _PDCLIB_ERROR 4