-------------------------------------------------------------------------------
What macros are pre-defined

Gcc at least man probably other compilers will list the predefined macros
which given a -v option

EG:  gcc -v hello_world.c
Reading specs from /usr/lib/gcc-lib/i486-linux/egcs-2.91.66/specs
gcc version egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)
 /usr/lib/gcc-lib/i486-linux/egcs-2.91.66/cpp -lang-c -v -undef
 -D__GNUC__=2 -D__GNUC_MINOR__=91 -D__ELF__ -Dunix -Di386 -D__i386__ -Dlinux
 -D__ELF__ -D__unix__ -D__i386__ -D__i386__ -D__linux__ -D__unix -D__i386
 -D__linux -Asystem(posix) -Asystem(unix) -Acpu(i386) -Amachine(i386) -Di386
 -D__i386 -D__i386__ -D__tune_i486__

-------------------------------------------------------------------------------
Concatation Macro

This marco is used to concatate two identifiers together into one
identifier for the compler. This macro is normally defined in
ansi C include files: memvar.h.

    #ifndef CAT
    #  undef  IDENT
    #  define IDENT(x)        x
    #  ifdef __STDC__
    #    define CAT(a,b)  a##b
    #  else
    #    define CAT(a,b)  IDENT(a)b
    #  endif
    #endif

-------------------------------------------------------------------------------

BSD to SysV Marco converters

For System V machine
   /* SysV memcpy for bcopy (note argument positions) */
   #define bcopy(s,d,n) memcpy(d,s,n)
   #define bzero(p,n)   memset(p,'\0',n)
   #define index(p,c)   strchr(p,c)

For BSD
   #define memcpy(d,s,n) bcopy(s,d,n)

-------------------------------------------------------------------------------
Tests on string defines

Cpp normall can not compare string defines. However through the use
of some carefully trickery it can be done

EG:
    #define anthony 1           ! any number other than 0 would work here
    #define jonh    2           ! any different number here
    #if USER == anthony
    #  define AUTHOR     "Anthony Thyssen"
    #elif USER == john
    #  define AUTHOR     "John Doe"
    #endif
    #undef anthony              ! don't forget or other problems may occur
    #undef john

Idea (for X resources) by:  Johnny Tolliver      jxt@ca12.cad.ornl.gov

-------------------------------------------------------------------------------
Rules for writing C macros.

  * never put a final `;' on the end of a macro -- let the caller
    provide this.

  * Bracket all arguments and the total macro expression. This
    avoids

    Bad Case:
        #define   multiply(a,b)   a * b
        multiply(5,2+10)  -->  5 * 2 + 10  -->  20

    Corrected:
        #define   multiply(a,b)   ( (a) * (b) )
        multiply(5,2+10)  -->  ( (5)*(2+10) )  -->  60

  * If possible only use a argument once to avoid expression duplication
    and thus duplication of side effects, such as pre/post increments.

    Example:
        #define   abs(x)  ( (x)>0 ? (x) : -(x) )
        abs( i++ );     /* i will be double incremented by the macro! */

    To stop this assign the expression argument given to a temporary
    variable and thus only evaluating that expression only once.
    EG:
        int tmp;     /* temporary variable for macro */
        #define   assign(ary,int)  ( tmp = (int), ary[tmp] = tmp )
        assign(my_array, i++);   /* i is not double incremented */

  * Expression Macros...

    Expression macros, are numerical expressions that "return" a
    result into the code where they are placed. These macros are the
    most common type of macro in use and is characterized by the use
    of brackets  (...).

    Problems with Expression Macros:-
       * No looping or recursion.
       * No variable declarations
       * can be very obtusicated
       * be careful about argument side effects (like increment)

  * Proceedural macros...

    Proceedural macros, allow the use of loops and variable declarations
    and usually consist of a brace block {...} to group all the statements,
    This is to avoid problems with looping statements and within if
    constructs.

    For example (bad)...
        #define  swap(a,b)  { int t=a; a=b; b=t; }

    However C syntax does NOT permit a `;' to be placed after the close brace
    when an else follows...

    For example using the above brace macro...
          if (x<y) swap(x,y); else ...
    results in this syntax error on the semi-colon...
          if (...) {...} ; else

    Using just braces to enclose the block is a problem.  The solution is to
    make the brace block a do loop which is executed only once. Aluturnatively
    a if statment though a missing semi-colon could be a problem in this case.

    General solutions to the brace-block problem.
       #define   macro(x)   do { statements; } while (0)   /* prefered */
       #define   macro(x)   if (1) { statements; } else

    Our swap macro then becomes

       #define swap(a,b) do {  \
                 int t=(a); (a)=(b); (b)=t; \
               } while(0) /* no trailing ; */

    This technique is also known as "swallowing the semicolon".

    Problems with proceedure macros:-
       * Brace-block problem requires extra code which is removed by
         the compiler (optimization) but lint will complain about.
       * No value return (void macro proceedures only)
       * No recursion  though looping is possible.

    Good Points..
       * temporary variables and loops
       8 whcih can be used to prevent argument side-effects.
       * 'break' to exit early (exception handling)!


  * Conversion between Expression and Proceedual Macros..

    The General concenses is to avoid proceedural macros whenever
    possible using expressional macros instead. The following is a
    conversion table between the two marco types.

       Proceedures use                  Expression macros use
         do {...} while(0)                    (...)
               ;                                ,
         if (...) ...                    ( (...) && (...) )
         if (!(...)) ...                 ( (...) || (...) )
         if(...) ... else ...            ( ... ? ... : ... )

     Example:
       #define   strdup(new,old)    (new) = malloc(strlen(old)+1); \
                                    strcpy((new),(old))
     Proceedural:
       # define  strdup(new,old)   do { \
              (new) = malloc(strlen(old)+1); strcpy((new),(old)) \
              } while(0)  /* no trailing ; */

     Espressional:
       #define   strdup(new,old) \
               (  (new) = strcpy( malloc(strlen(old)+1), (old) )  )


-------------------------------------------------------------------------------
Variable Number of Arguments in a macro

  The best `trick' is to define a macro with a single set of parentheses
  and call it with a double set of parentheses, which appear to
  the preprocessor to indicate a single argument:

          #define DEBUG(args) (printf("DEBUG: "), printf args)

          if(n != 0) DEBUG(("n is %d\n", n));

  It is often better to use a bona-fide function, which can take a
  variable number of arguments in a well-defined way.

-------------------------------------------------------------------------------