Ignore:
Timestamp:
Mar 13, 2004, 3:03:25 AM (21 years ago)
Author:
bird
Message:

logging and strict features.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/emx/include/InnoTekLIBC/log.h

    • Property cvs2svn:cvs-rev changed from 1.1 to 1.2
    r1287 r1288  
    22/** @file
    33 *
    4  * Debug Logging Features - internal libc use only.
     4 * InnoTek LIBC - Debug Logging and Strict Checking Features.
    55 *
    66 * InnoTek Systemberatung GmbH confidential
    … …  
    1616#define __InnoTekLIBC_LOG_H__
    1717
    18 
    19 #ifdef DEBUG_LOGGING
    20 /*
    21  * Logging is enabled.
    22  */
     18/** @defgroup   __libc_log      Debug Logging and Strict Checking Features
     19 *
     20 * The logging feature is not accessible unless DEBUG_LOGGING is #defined.
     21 *
     22 * The user of this feature must #define __LIBC_LOG_GROUP to a valid group
     23 * number before including this file.
     24 *
     25 * The user may also #define __LIBC_LOG_INSTANCE if it doesn't want to use
     26 * the default logging device.
     27 *
     28 * Note that all everything but the main logger macros are using the default
     29 * prefix to avoid namespace pollution. The main logger macros are not
     30 * prefixed with the double underscore because that would make the code less
     31 * readable (and it's more to type which for me means more pain).
     32 *
     33 * @{
     34 */
     35
     36
     37/*******************************************************************************
     38*   Defined Constants And Macros                                               *
     39*******************************************************************************/
     40/**
     41 * The user may also #define __LIBC_LOG_INSTANCE if it doesn't want to use
     42 * the default logging device.
     43 */
     44#ifdef DEBUG_LOGGING
     45#ifndef __LIBC_LOG_INSTANCE
     46#define __LIBC_LOG_INSTANCE NULL
     47#endif
     48#endif
     49
     50/**
     51 * The user of this feature must #define __LIBC_LOG_GROUP to a valid group
     52 * number before including this file.
     53 */
     54#ifdef DEBUG_LOGGING
     55#ifndef __LIBC_LOG_GROUP
     56#define __LIBC_LOG_GROUP    0
     57#error "__LIBC_LOG_GROUP must be defined before including InnoTekLIBC/log.h"
     58#endif
     59#endif
     60
     61/** Macro to log a function entry. */
     62#ifdef DEBUG_LOGGING
     63#define LIBCLOG_ENTER(...) \
     64    unsigned __libclog_uEnterTS__ = __libc_LogEnter(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __VA_ARGS__)
     65#else
     66#define LIBCLOG_ENTER(...)  //hmm
     67#endif
     68
     69/** Macro to log a generic message within a function entered by LIBCLOG_ENTER(). */
     70#ifdef DEBUG_LOGGING
     71#define LIBCLOG_MSG(...) \
     72    __libc_LogMsg(__libclog_uEnterTS__, __LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __VA_ARGS__)
     73#else
     74#define LIBCLOG_MSG(...)    do {} while (0)
     75#endif
     76
     77/** Macro to log a generic message within a functionw. */
     78#ifdef DEBUG_LOGGING
     79#define LIBCLOG_MSG2(...) \
     80    __libc_LogMsg(~0, __LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __VA_ARGS__)
     81#else
     82#define LIBCLOG_MSG2(...)   do {} while (0)
     83#endif
     84
     85/** Macro to log a raw message. */
     86#ifdef DEBUG_LOGGING
     87#define LIBCLOG_RAW(string, maxlen) \
     88    __libc_LogRaw(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, string, maxlen)
     89#else
     90#define LIBCLOG_RAW(...)    do {} while (0)
     91#endif
     92
     93/** Macro to log a function exit. */
     94#ifdef DEBUG_LOGGING
     95#define LIBCLOG_LEAVE(...) \
     96    __libc_LogLeave(__libclog_uEnterTS__, __LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __VA_ARGS__)
     97#else
     98#define LIBCLOG_LEAVE(...)  do {} while (0)
     99#endif
     100/** Macro to log a void return and do the return. */
     101#define LIBCLOG_RETURN_VOID()    do { LIBCLOG_LEAVE("ret void\n");                      return;      } while (0)
     102/** Macro to log an int return and do the return. */
     103#define LIBCLOG_RETURN_INT(rc)   do { LIBCLOG_LEAVE("ret %d (%#x)\n", (rc), (rc));      return (rc); } while (0)
     104/** Macro to log an unsigned int return and do the return. */
     105#define LIBCLOG_RETURN_UINT(rc)  do { LIBCLOG_LEAVE("ret %u (%#x)\n", (rc), (rc));      return (rc); } while (0)
     106/** Macro to log an long int return and do the return. */
     107#define LIBCLOG_RETURN_LONG(rc)  do { LIBCLOG_LEAVE("ret %ld (%#lx)\n", (rc), (rc));    return (rc); } while (0)
     108/** Macro to log an unsigned long int return and do the return. */
     109#define LIBCLOG_RETURN_ULONG(rc) do { LIBCLOG_LEAVE("ret %lu (%#lx)\n", (rc), (rc));    return (rc); } while (0)
     110/** Macro to log a pointer return and do the return. */
     111#define LIBCLOG_RETURN_P(rc)     do { LIBCLOG_LEAVE("ret %p\n", (rc));                  return (rc); } while (0)
     112
     113
     114/** @defgroup   __libc_log_groups   Default Logging Groups
     115 * @{ */
     116/** whatever. */
     117#define __LIBCLOG_GRP_NOGROUP       0
     118
     119/*-- LIBC --*/
     120/** Process APIs. */
     121#define __LIBCLOG_GRP_PROCESS       1
     122/** Heap APIs. */
     123#define __LIBCLOG_GRP_HEAP          2
     124/** File stream APIs. */
     125#define __LIBCLOG_GRP_STREAM        3
     126/** Other I/O APIs. */
     127#define __LIBCLOG_GRP_IO            4
     128/** String APIs. */
     129#define __LIBCLOG_GRP_STRING        5
     130/** Locale APIs. */
     131#define __LIBCLOG_GRP_LOCALE        6
     132/** Regular expression APIs. */
     133#define __LIBCLOG_GRP_REGEX         7
     134/** Math APIs. */
     135#define __LIBCLOG_GRP_MATH          8
     136/** Time APIs. */
     137#define __LIBCLOG_GRP_TIME          9
     138/** BSD DB APIs. */
     139#define __LIBCLOG_GRP_BSD_DB        10
     140/** GLIBC POSIX APIs. */
     141#define __LIBCLOG_GRP_GLIBC_POSIX   11
     142
     143/** Backend APIs. */
     144#define __LIBCLOG_GRP_BACKEND       28
     145/** Misc APIs. */
     146#define __LIBCLOG_GRP_MISC          29
     147/** BSD Gen APIs. */
     148#define __LIBCLOG_GRP_BSD_GEN       30
     149/** GLIBC Misc APIs. */
     150#define __LIBCLOG_GRP_GLIBC_MISC    31
     151
     152/*-- other libraries/APIs --*/
     153/** Socket APIs. */
     154#define __LIBCLOG_GRP_SOCKET        32
     155/** Other TCP/IP APIs. */
     156#define __LIBCLOG_GRP_TCPIP         33
     157/** iconv APIs. */
     158#define __LIBCLOG_GRP_ICONV         34
     159/** Dynamic Library (libdl) APIs. */
     160#define __LIBCLOG_GRP_DLFCN         35
     161/** Posix thread APIs. */
     162#define __LIBCLOG_GRP_PTHREAD       36
     163
     164/** @todo complete this */
     165#define __LIBCLOG_GRP_MAX           36
     166/** @} */
     167
     168
     169/** @defgroup   __libc_log_strict   Strict Assertions
     170 * @{ */
     171
     172/** Generic assertion.
     173 * @param expr  Boolean expression,
     174 */
     175#ifdef DEBUG_STRICT
     176#define LIBC_ASSERT(expr) ((expr) ? (void)0 \
     177    : __libc_LogAssert(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __FILE__, __LINE__, #expr, \
     178                       NULL))
     179#else
     180#define LIBC_ASSERT(expr) ((void)0)
     181#endif
     182
     183/** Assert that a memory buffer is readable.
     184 * @param pv    Pointer to buffer.
     185 * @param cb    Size of buffer.
     186 */
     187#ifdef DEBUG_STRICT
     188#define LIBC_ASSERT_MEM_R(pv, cb) (__libc_StrictMemoryR((pv), (cb)) ? (void)0 \
     189    : __libc_LogAssert(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __FILE__, __LINE__, #pv "; " #cb, \
     190                       "Memory buffer at %p of %d bytes isn't readable!\n", (pv), (cb)))
     191#else
     192#define LIBC_ASSERT_MEM_R(pv, cb) ((void)0)
     193#endif
     194
     195/** Assert that a memory buffer is readable and writable.
     196 * @param pv    Pointer to buffer.
     197 * @param cb    Size of buffer.
     198 */
     199#ifdef DEBUG_STRICT
     200#define LIBC_ASSERT_MEM_RW(pv, cb) (__libc_StrictMemoryRW((pv), (cb)) ? (void)0 \
     201    : __libc_LogAssert(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __FILE__, __LINE__, #pv "; " #cb, \
     202                       "Memory buffer at %p of %d bytes isn't readable and writable!\n", (pv), (cb)))
     203#else
     204#define LIBC_ASSERT_MEM_RW(pv, cb) ((void)0)
     205#endif
     206
     207/** Assert that a zero terminated string is readable.
     208 * @param psz    Pointer to buffer.
     209 */
     210#ifdef DEBUG_STRICT
     211#define LIBC_ASSERT_STR(psz) (__libc_StrictStringR((psz), ~0) ? (void)0 \
     212    : __libc_LogAssert(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __FILE__, __LINE__, #psz, \
     213                       "String at %p isn't readable!\n", (psz)))
     214#else
     215#define LIBC_ASSERT_STR(psz) ((void)0)
     216#endif
     217
     218/** Assert that a zero terminated string with a maximum lenght is readable.
     219 * @param psz       Pointer to buffer.
     220 * @param cchMax    Max string length.
     221 */
     222#ifdef DEBUG_STRICT
     223#define LIBC_ASSERT_NSTR(psz, cchMax) (__libc_StrictStringR((psz), cchMax) ? (void)0 \
     224    : __libc_LogAssert(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __FILE__, __LINE__, #psz " " #cchMax, \
     225                       "String at %p of maximum %d bytes isn't readable!\n", (psz), (cchMax)))
     226#else
     227#define LIBC_ASSERT_NSTR(psz, cchMax) ((void)0)
     228#endif
     229
     230
     231/** Generic assertion, custom message.
     232 * @param expr  Boolean expression,
     233 * @param ...   Custom error message.
     234 */
     235#ifdef DEBUG_STRICT
     236#define LIBC_ASSERTM(expr, ...) ((expr) ? (void)0 \
     237    : __libc_LogAssert(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __FILE__, __LINE__, #expr, \
     238                       __VA_ARGS__))
     239#else
     240#define LIBC_ASSERTM(expr, ...) ((void)0)
     241#endif
     242
     243/** Assert that a memory buffer is readable, custom message
     244 * @param pv    Pointer to buffer.
     245 * @param cb    Size of buffer.
     246 */
     247#ifdef DEBUG_STRICT
     248#define LIBC_ASSERTM_MEM_R(pv, cb, ...) (__libc_StrictMemoryR((pv), (cb)) ? (void)0 \
     249    : __libc_LogAssert(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __FILE__, __LINE__, #pv "; " #cb, \
     250                       __VA_ARGS__))
     251#else
     252#define LIBC_ASSERTM_MEM_R(pv, cb, ...) ((void)0)
     253#endif
     254
     255/** Assert that a memory buffer is readable and writable, custom message
     256 * @param pv    Pointer to buffer.
     257 * @param cb    Size of buffer.
     258 */
     259#ifdef DEBUG_STRICT
     260#define LIBC_ASSERTM_MEM_RW(pv, cb, ...) (__libc_StrictMemoryRW((pv), (cb)) ? (void)0 \
     261    : __libc_LogAssert(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __FILE__, __LINE__, #pv "; " #cb, \
     262                       __VA_ARGS__))
     263#else
     264#define LIBC_ASSERTM_MEM_RW(pv, cb, ...) ((void)0)
     265#endif
     266
     267/** Assert that a zero terminated string is readable, custom message
     268 * @param psz    Pointer to buffer.
     269 */
     270#ifdef DEBUG_STRICT
     271#define LIBC_ASSERTM_STR(psz, ...) (__libc_StrictStringR((psz), ~0) ? (void)0 \
     272    : __libc_LogAssert(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __FILE__, __LINE__, #psz, \
     273                       __VA_ARGS__))
     274#else
     275#define LIBC_ASSERTM_STR(psz, ...) ((void)0)
     276#endif
     277
     278/** Assert that a zero terminated string with a maximum lenght is readable, custom message
     279 * @param psz       Pointer to buffer.
     280 * @param cchMax    Max string length.
     281 */
     282#ifdef DEBUG_STRICT
     283#define LIBC_ASSERTM_NSTR(psz, cchMax, ...) (__libc_StrictStringR((psz), cchMax) ? (void)0 \
     284    : __libc_LogAssert(__LIBC_LOG_INSTANCE, __LIBC_LOG_GROUP, __PRETTY_FUNCTION__, __FILE__, __LINE__, #psz " " #cchMax, \
     285                       __VA_ARGS__))
     286#else
     287#define LIBC_ASSERTM_NSTR(psz, cchMax, ...) ((void)0)
     288#endif
     289
     290/** @} */
     291
     292
     293/*******************************************************************************
     294*   Structures and Typedefs                                                    *
     295*******************************************************************************/
     296/** Logging group. */
     297typedef struct __libc_log_group
     298{
     299    /** Set if logging for the group is enabled, clear if it's disabled. */
     300    int             fEnabled;
     301    /** Group name */
     302    const char *    pszGroupName;
     303} __LIBC_LOGGROUP, *__LIBC_PLOGGROUP;
     304
     305/** Ordered collection of logging groups. */
     306typedef struct __libc_log_groups
     307{
     308    /** Group index base. This value is subtracted from the group part of the
     309     * fFlagsAndGroups arguments to make an index into paGroups. */
     310    unsigned            uBase;
     311    /** Number of groups in the array. */
     312    unsigned            cGroups;
     313    /** Array of log groups. */
     314    __LIBC_PLOGGROUP    paGroups;
     315} __LIBC_LOGGROUPS, __LIBC_PLOGGROUPS;
     316
     317
     318/*******************************************************************************
     319*   External Functions                                                         *
     320*******************************************************************************/
     321/**
     322 * Create a logger.
     323 *
     324 * @returns Pointer to a logger instance on success.
     325 * @returns NULL on failure. errno is set.
     326 * @param   fFlags              Flags reserved for future use. Set to zero.
     327 * @param   pGroups             Pointer to a table of logging groups used for this
     328 *                              logger instance.
     329 * @param   pszFilenameFormat   Format string for making up the log filename.
     330 * @param   ...                 Arguments to the format string.
     331 */
     332extern void *__libc_logInit(unsigned fFlags, __LIBC_PLOGGROUPS pGroups, const char *pszFilenameFormat, ...) __printflike(3, 4);
     333
     334/**
     335 * Terminate (or close if you like) a logger instance.
     336 * This means flushing any buffered messages and writing a termination
     337 * message before closing the log file.
     338 *
     339 * @returns 0 on succes.
     340 * @returns -1 on failure, error is set.
     341 * @param   pvInstance      Logger instance.
     342 */
     343extern int   __libc_logTerm(void *pvInstance);
     344
    23345/**
    24346 * Output an enter function log message.
    … …  
    27349 *
    28350 * @returns Current timestamp.
     351 * @param   pvInstance      Logger instance. If NULL the message goes to the
     352 *                          default log instance.
     353 * @param   fGroupAndFlags  Logging group and logging flags.
    29354 * @param   pszFunction     Name of the function which was entered.
    30355 * @param   pszFormat       Format string to display arguments.
    31356 * @param   ...             Arguments to the format string.
    32357 */
    33 extern unsigned __libc_LogEnter(const char *pszFunction, const char *pszFormat, ...) __printflike(2, 3);
     358extern unsigned __libc_LogEnter(void *pvInstance, unsigned fGroupAndFlags, const char *pszFunction, const char *pszFormat, ...) __printflike(4, 5);
     359
    34360/**
    35361 * Output a leave function log message.
    … …  
    38364 *
    39365 * @param   uEnterTS        The timestamp returned by LogEnter.
     366 * @param   pvInstance      Logger instance. If NULL the message goes to the
     367 *                          default log instance.
     368 * @param   fGroupAndFlags  Logging group and logging flags.
    40369 * @param   pszFunction     Name of the function which was entered.
    41370 * @param   pszFormat       Format string to display the result.
    42371 * @param   ...             Arguments to the format string.
    43372 */
    44 extern void     __libc_LogLeave(unsigned uEnterTS, const char *pszFunction, const char *pszFormat, ...) __printflike(3, 4);
     373extern void     __libc_LogLeave(unsigned uEnterTS, void *pvInstance, unsigned fGroupAndFlags, const char *pszFunction, const char *pszFormat, ...) __printflike(5, 6);
    45374
    46375/**
    … …  
    50379 *
    51380 * @param   uEnterTS        The timestamp returned by LogEnter.
     381 * @param   pvInstance      Logger instance. If NULL the message goes to the
     382 *                          default log instance.
     383 * @param   fGroupAndFlags  Logging group and logging flags.
    52384 * @param   pszFunction     Name of the function which was entered.
    53385 * @param   pszFormat       Format string for the message to log.
    54386 * @param   ...             Arguments to the format string.
    55387 */
    56 extern void     __libc_LogMsg(unsigned uEnterTS, const char *pszFunction, const char *pszFormat, ...) __printflike(3, 4);
    57 
    58 /** Macro to log a function entry. */
    59 #define LIBCLOG_ENTER(...) \
    60     unsigned __libclog_uEnterTS__ = __libc_LogEnter(__PRETTY_FUNCTION__, __VA_ARGS__)
    61 #define LIBCLOG_LEAVE(...) \
    62     __libc_LogLeave(__libclog_uEnterTS__, __PRETTY_FUNCTION__, __VA_ARGS__)
    63 #define LIBCLOG_MSG(...) \
    64     __libc_LogLeave(__libclog_uEnterTS__, __PRETTY_FUNCTION__, __VA_ARGS__)
    65 #define LIBCLOG_MSG2(...) \
    66     __libc_LogLeave(~0, __PRETTY_FUNCTION__, __VA_ARGS__)
    67 
    68 #else
    69 /*
    70  * Logging is disabled.
    71  */
    72 #define LIBCLOG_ENTER(...) //hmm
    73 #define LIBCLOG_LEAVE(...)  do {} while (0)
    74 #define LIBCLOG_MSG(...)    do {} while (0)
    75 #define LIBCLOG_MSG2(...)    do {} while (0)
    76 
    77 #endif
    78 
    79 /* helpers */
    80 #define LIBCLOG_RETURN_VOID()    do { LIBCLOG_LEAVE("ret void\n");                      return;      } while (0)
    81 #define LIBCLOG_RETURN_INT(rc)   do { LIBCLOG_LEAVE("ret %d (%#x)\n", (rc), (rc));      return (rc); } while (0)
    82 #define LIBCLOG_RETURN_UINT(rc)  do { LIBCLOG_LEAVE("ret %u (%#x)\n", (rc), (rc));      return (rc); } while (0)
    83 #define LIBCLOG_RETURN_LONG(rc)  do { LIBCLOG_LEAVE("ret %ld (%#lx)\n", (rc), (rc));    return (rc); } while (0)
    84 #define LIBCLOG_RETURN_ULONG(rc) do { LIBCLOG_LEAVE("ret %lu (%#lx)\n", (rc), (rc));    return (rc); } while (0)
    85 #define LIBCLOG_RETURN_P(rc)     do { LIBCLOG_LEAVE("ret %p\n", (rc));                  return (rc); } while (0)
    86 
    87 #endif
     388extern void     __libc_LogMsg(unsigned uEnterTS, void *pvInstance, unsigned fGroupAndFlags, const char *pszFunction, const char *pszFormat, ...) __printflike(5, 6);
     389
     390/**
     391 * Output a raw log message.
     392 * Nothing is prepended. No newline is appended.
     393 *
     394 * @param   uEnterTS        The timestamp returned by LogEnter.
     395 * @param   pvInstance      Logger instance. If NULL the message goes to the
     396 *                          default log instance.
     397 * @param   fGroupAndFlags  Logging group and logging flags.
     398 * @param   pszFunction     Name of the function which was entered.
     399 * @param   pszString       Pointer to raw log message.
     400 * @param   cchMax          Maximum number of bytes to write.
     401 */
     402extern void     __libc_LogRaw(void *pvInstance, unsigned fGroupAndFlags, const char *pszString, unsigned cchMax);
     403
     404/**
     405 * Assertion helper.
     406 * Logs and displays (stderr) an assertion failed message.
     407 *
     408 * @param   pvInstance      Logger instance. If NULL the message goes to the
     409 *                          default log instance.
     410 * @param   pszFunction     Name of the function which was entered.
     411 * @param   pszFile         Source filename.
     412 * @param   uLine           Line number.
     413 * @param   pszExpression   Expression.
     414 * @param   pszFormat       Format string for the message to log.
     415 * @param   ...             Arguments to the format string.
     416 */
     417extern void     __libc_LogAssert(void *pvInstance, unsigned fGroupAndFlags,
     418                                 const char *pszFunction, const char *pszFile, unsigned uLine, const char *pszExpression,
     419                                 const char *pszFormat, ...) __printflike(7, 8);
     420
     421/**
     422 * Validate a memory area for read access.
     423 * @returns 1 if readable.
     424 * @returns 0 if not entirely readable.
     425 * @param   pv      Pointer to memory area.
     426 * @param   cb      Size of memory area.
     427 */
     428extern int      __libc_StrictMemoryR(const void *pv, size_t cb);
     429
     430/**
     431 * Validate a memory area for read & write access.
     432 * @returns 1 if readable and writable.
     433 * @returns 0 if not entirely readable and writable.
     434 * @param   pv      Pointer to memory area.
     435 * @param   cb      Size of memory area.
     436 */
     437extern int      __libc_StrictMemoryRW(void *pv, size_t cb);
     438
     439/**
     440 * Validate a zero terminated string for read access.
     441 * @returns 1 if readable.
     442 * @returns 0 if not entirely readable.
     443 * @param   psz         Pointer to string.
     444 * @param   cchMax      Max string length. Use ~0 if to very all the
     445 *                      way to the terminator.
     446 */
     447extern int      __libc_StrictStringR(const void *psz, size_t cchMax);
     448
     449
     450/** @} */
     451
     452#endif
Note: See TracChangeset for help on using the changeset viewer.