platform_helper.c

Go to the documentation of this file.

//           _         _     __                               _            _                            //
//    _ __  | |  __ _ | |_  / _|  ___   _ __  _ __ ___       | |__    ___ | | _ __    ___  _ __  ___    //
//   | '_ \ | | / _` || __|| |_  / _ \ | '__|| '_ ` _ \      | '_ \  / _ \| || '_ \  / _ \| '__|/ __|   //
//   | |_) || || (_| || |_ |  _|| (_) || |   | | | | | |     | | | ||  __/| || |_) ||  __/| | _| (__    //
//   | .__/ |_| \__,_| \__||_|   \___/ |_|   |_| |_| |_|_____|_| |_| \___||_|| .__/  \___||_|(_)\___|   //
//   |_|                                               |_____|               |_|                        //
//                                                                                                      //
//                        platform-specific code to rectify various issues                              //
//                                                                                                      //

/*****************************************************************************

    X11workbench - X11 programmer's 'work bench' application and toolkit
    Copyright (c) 2010-2019 by Bob Frazier (aka 'Big Bad Bombastic Bob')


  DISCLAIMER:  The X11workbench application and toolkit software are supplied
               'as-is', with no warranties, either implied or explicit.
               Any claims to alleged functionality or features should be
               considered 'preliminary', and might not function as advertised.

  MIT-like license:

  There is no restriction as to what you can do with this software, so long
  as you include the above copyright notice and DISCLAIMER for any distributed
  work that is equal to or derived from this one, along with this paragraph
  that explains the terms of the license if the source is also being made
  available.  A "derived work" describes a work that uses a significant portion
  of the source files or algorithms that are included with this one.
  Specifically excluded from this are files that were generated by the software,
  or anything that is included with the software that is part of another package
  (such as files that were created or added during the 'configure' process).
  Specifically included is the use of part or all of any of the X11 workbench
  toolkit source or header files in your distributed application.  If you do not
  ship the source, the above copyright statement is still required to be placed
  in a reasonably prominent place, such as documentation, splash screens, and/or
  'about the application' dialog boxes.

  Use and distribution are in accordance with GPL, LGPL, and/or the above
  MIT-like license.  See COPYING and README files for more information.


  Additional information at http://sourceforge.net/projects/X11workbench

******************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
#include <string.h>
#include <memory.h>
#ifndef WIN23
#include <pthread.h>
#include <unistd.h>
#include <fcntl.h>
#include <errno.h>
#include <signal.h>
#include <time.h>
#include <sys/time.h>
#include <dlfcn.h> /* dynamic library support */
#include <sys/wait.h>
#include <sys/types.h>
#include <sys/stat.h>
#ifdef __FreeBSD__
#include <sys/sysctl.h> // to use the 'sysctlXXX' APIs
#endif // __FreeBSD__

#include <time.h> // clock_gettime etc.
#include <locale.h>
#endif // !WIN32

#include "platform_helper.h" // includes X11 headers as well
#include "window_helper.h"
#include "file_help.h"
//#include "draw_text.h"

#ifdef HAVE_MALLOC_USABLE_SIZE
#ifdef __FreeBSD__
#include <malloc_np.h>
#else
#include <malloc.h>
#endif // __FreeBSD__
#endif // HAVE_MALLOC_USABLE_SIZE


static char *pTempFileList = NULL, *pTempFileListEnd = NULL;
unsigned long cbTempFileList; // size of pointer

static volatile int fInterlockedRWLockInitFlag = 0;
static pthread_rwlock_t xInterlockedRWLock;

static void WBFreePointerHashes(void);
static void __add_to_temp_file_list(const char *szFile);


int bQuitFlag = FALSE;             // defined here, used globally

// within this file debug level is writable.  outside of this file, it's (technically) read-only
WB_UINT64 iWBDebugLevel = 0; // default is no debug except errors, all subsystems

// application name (from argv[0])
static char szAppName[PATH_MAX * 2]="";



//                                                                          //
//     ___         _  _        _                _   _____        _  _       //
//    |_ _| _ __  (_)| |_     / \    _ __    __| | | ____|__  __(_)| |_     //
//     | | | '_ \ | || __|   / _ \  | '_ \  / _` | |  _|  \ \/ /| || __|    //
//     | | | | | || || |_   / ___ \ | | | || (_| | | |___  >  < | || |_     //
//    |___||_| |_||_| \__| /_/   \_\|_| |_| \__,_| |_____|/_/\_\|_| \__|    //
//                                                                          //
//                                                                          //

#if !defined(DOXYGEN) && defined(_MSC_VER)
//#pragma comment(linker, "/alternatename:_main=___main__")
//int __main__(int argc, char *argv0[], char *envp0[])
int __declspec(selectany) main(int argc, char *argv0[], char *envp0[])
#else // _MSC_VER
int main(int argc, char *argv0[], char *envp0[]) __attribute__((weak)) __attribute__((section("text_main")))
#endif // _MSC_VER
{
int iRval;
char **argv = argv0; // re-define as char ** so I can re-allocate it as needed
char **envp = envp0;

  WBPlatformOnInit();

  if(!WBParseStandardArguments(&argc, &argv, &envp))
  {
    iRval = WBMain(argc, argv, envp);

    if(envp && envp != envp0) // was envp re-allocated by the toolkit?
    {
      WBFree(envp); // use 'WBFree' to free memory allocated by the toolkit
    }
    if(argv && argv != argv0) // was argv re-allocated by the toolkit?
    {
      WBFree(argv);
    }
  }
  else
  {
    WBUsage();
    iRval = 1;
  }

  WBPlatformOnExit();
  return iRval;
}

#if !defined(DOXYGEN) && defined(_MSC_VER)
//#pragma comment(linker, "/alternatename:_WBMain=___WBMain__")
//int __WBMain__(int argc, char *argv0[], char *envp0[])
int __declspec(selectany) __WBMain__(int argc, char *argv0[], char *envp0[])
#else // _MSC_VER
int WBMain(int argc, char *argv0[], char *envp0[]) __attribute__((weak)) __attribute__((section("text_wbmain")))
#endif // _MSC_VER
{
  fputs("You need to define 'WBMain' in your code\n", stderr);
  return 1;
}

#if !defined(DOXYGEN) && defined(_MSC_VER)
//#pragma comment(linker, "/alternatename:_WBUsage=___WBUsage__")
//void __WBUsage__(void)
void __declspec(selectany) WBUsage(void)
#else // _MSC_VER
void WBUsage(void) __attribute__((weak)) __attribute__((section("text_wbusage")))
#endif // _MSC_VER
{
  WBToolkitUsage(); // default just does this
}


void WBPlatformOnInit(void)
{
char *pEnv;
int iType;

  // NOTE:  main thread needs to do this before spawning any threads.

  if(!fInterlockedRWLockInitFlag)
  {
    pthread_rwlock_init(&xInterlockedRWLock, NULL);
  }

  iType = LC_ALL;
  pEnv = getenv("LC_ALL"); // check this one first

  if(!pEnv || !*pEnv)
  {
    pEnv = getenv("LC_CTYPE"); // then this one

    if(pEnv && *pEnv)
    {
      iType = LC_CTYPE; // only adjust LC_CTYPE if I found THIS but no others...
    }
    else
    {
      pEnv = getenv("LANG"); // overall language setting
    }
  }

  if(pEnv && *pEnv)
  {
    if(!setlocale(iType, pEnv)) // should pick the correct one when I do this
    {
      WB_ERROR_PRINT("ERROR:  %s - cannot set locale \"%s\"\n", __FUNCTION__, pEnv);

      goto default_locale;
    }
  }
  else
  {
default_locale:
    setlocale(LC_ALL, ""); // should pick OS default when I do this
  }
}

void WBPlatformOnExit(void)
{
char *p1;


  if(pTempFileList) // delete temporary file list
  {
    for(p1 = pTempFileList; *p1; p1 += strlen(p1) + 1)
    {
      unlink(p1); // delete all of the temp files, ignoring errors
    }

    WBFree(pTempFileList);
  }

  WBFreePointerHashes(); // delete pointer hashes

  // lastly, free up the RWLOCK that I created for RW-locking 'Interlocked' things

  if(fInterlockedRWLockInitFlag)
  {
    pthread_rwlock_destroy(&xInterlockedRWLock);
    fInterlockedRWLockInitFlag = 0; // by convention, in case I re-init [unlikely]
  }

#ifndef NO_DEBUG // I only do this for builds that have DEBUG capability

  // FINALLY, if I've done any debug profiling, dump the profile data

  WBDumpProfileData(); // this dumps any profile data out to stderr

#endif // NO_DEBUG
}

// NOTE: when this function is called first, the arguments will be parsed in order to obtain
// information needed by WBInit and WBInitDisplay.  Otherwise, default values are used by
// the WBInit and WBInitDisplay functions.

int WBParseStandardArguments(int *pargc, char ***pargv, char ***penvp)
{
int argc = *pargc;
char **argv = *pargv;
char **envp = *penvp;
char **p1;
char **argvNew = NULL;
int argcNew = 0;
int i1, i2;
int iDebugLevelSeen = 0;
int argc_orig = argc;
char **argv_orig = argv;

static const char * const aszCmdLineOptions[]=
{
  "help","help-all","debug","subsys","display","minimize","maximize","geometry","no-antialias","no-imagecache",
  NULL // marks end of list
};

static const uint8_t abCmdLineOptions[]= // NON-ZERO means that it expects a parameter
{
  0, 0, 1, 1, 1, 0, 0, 1, 0, 0,
  0
};

static const char * const aszDebugSubSys[]=
{
  "init","application","window","menu","event",
  "dialog","dialogctrl","frame","keyboard",
  "mouse","font","settings","selection",
  "pixmap","expose","editwindow","scrollbar",
  "drawtext","clipboard","textobject",
  NULL
};


enum
{
    option_help=0,
    option_help_all,
    option_debug,
    option_subsys,
    option_display,
    option_minimize,
    option_maximize,
    option_geometry,
    option_no_antialias,
    option_no_image_cache
};

  // grab the name of the program and cache it.  I'll need the path info.

  strncpy(szAppName, argv[0], sizeof(szAppName));
  szAppName[sizeof(szAppName) - 1] = 0; // make sure

  // search for DISPLAY environment variable, pre-assign to szStartupDisplayName
  p1 = envp;

  if(p1)
  {
    while(*p1)
    {
      if(!strncmp(*p1, "DISPLAY=", 8))
      {
        __internal_startup_display(*p1 + 8);
        break;  // I am done
      }

      p1++;
    }
  }
  else // with no environment pointers, use the 'getenv' C language function
  {
    char *p1a = getenv("DISPLAY");

    if(p1a)
    {
      __internal_startup_display(p1a);
    }
  }

  // parse arg list and make copy as needed

  while(argc > 1)
  {
    int argc0 = argc;  // value at start of loop iteration
    int iFlag = 0;

    if(argv[1][0] != '-' || !argv[1][1] || // end of arguments is a '-' by itself or something not starting with '-'
       (argv[1][1] == '-' && !argv[1][2])) // '--' by itself has the same effect
    {
      break;
    }

    if(argv[1][1] != '-') // double '-' is what I'm looking for
    {
      if(!argvNew) // aren't making copies yet
      {
        argv++; // keep looking but don't touch anything yet
        argc--;

        WB_DEBUG_PRINT(DebugLevel_Medium | DebugSubSystem_Init,
                       "%s.%d  skipping over argument '%s'\n", __FUNCTION__, __LINE__, argv[0]);
        continue;
      }

      WB_DEBUG_PRINT(DebugLevel_Medium | DebugSubSystem_Init,
                     "%s.%d unrecognized argument '%s'\n", __FUNCTION__, __LINE__, argv[1]);
    }
    else
    {
      // options here start with two '-' and are followed by
      // text=value or text [space] value

      for(i1=0; aszCmdLineOptions[i1]; i1++)
      {
        const char *szOpt = aszCmdLineOptions[i1];
        int iLen = strlen(szOpt);
        const char *szArg = argv[1] + 2;   // points past the '--'
        const char *szVal = szArg + iLen;  // end of the option string ('=' or '\0')

        if(!strncmp(szOpt, szArg, iLen) &&
           (*szVal == '=' || !*szVal))
        {
          if(!*szVal)
          {
            // I've come for an argument.  But not everything has an argument.  Some things
            // do, some things don't. So if I don't expect an argument, don't check for one
            // Otherwise, I need to increment argv and decrement argc and point to the arg

            if(abCmdLineOptions[i1] && argc > 2)
            {
              // skip over arg for the loop iteration
              argv++;
              argc--;
              szVal = argv[1];
            }
          }

          switch(i1)
          {
            case option_help:
              WBToolkitUsage();

help_exit: // go here if I displayed help and don't want a 'usage()'
              if(argvNew)
              {
                WBFree(argvNew);
              }

              return 1; // advise NOT to display 'usage()' but to definitely exit the application

            case option_help_all:
              WBToolkitUsage();
              WBDebugPrint("\n\n'Help All' not yet implemented\n\n");
              goto help_exit;

            case option_debug: // this takes immediate effect
              i2 = atoi(szVal);

              // max debugt level is 7, minimum is zero
              if(*szVal < '0' || *szVal > '7' || i2 < 0 || i2 > DebugLevel_MAXIMUM)
              {
                WBDebugPrint("Invalid debug level %s - must be between 0 and %d\n", szVal, DebugLevel_MAXIMUM);
                goto argument_error_exit;
              }

              iDebugLevelSeen = 1;
              iWBDebugLevel = (iWBDebugLevel & DebugSubSystem_MASK)
                            | (atoi(szVal) & DebugLevel_MASK);
              break;

            case option_subsys:
              if(!strcmp("help", szVal))
              {
                // --subsys=help   lists all of them on stderr

                WBDebugPrint("List of '--subsys' options:\n"
                             "    Subsystem Name           Bit Value  (hexadecimal)\n"
                             "    ----------------------- ----------- -------------\n");

                for(i2=0; aszDebugSubSys[i2]; i2++)
                {
                  WBDebugPrint("    %-24s%10ld    %08lxH\n", aszDebugSubSys[i2],
                               1L << (i2 + DebugSubSystem_BITSHIFT),
                               1L << (i2 + DebugSubSystem_BITSHIFT));
                }

                WBDebugPrint("  (special '--subsys' options)\n"
                             "    all                              0    00000000H\n"
                             "    restrict                2147483648    80000000H\n\n"
                             "Specify 'restrict' in addition to one or more subsystems in order\n"
                             "to ONLY display debug output for the specified subsystem(s)\n\n");

                goto help_exit;
              }
              else if(!strcmp("restrict", szVal))
              {
                iWBDebugLevel |= DebugSubSystem_RESTRICT; // means ONLY the subsys that I specify
              }
              else if(!strcmp("all", szVal))
              {
                iWBDebugLevel &= ~(DebugSubSystem_MASK | DebugSubSystem_RESTRICT); // "all"
              }
              else
              {
                for(i2=0; aszDebugSubSys[i2]; i2++)
                {
                  if(!strcasecmp(aszDebugSubSys[i2], szVal))
                  {
                    iWBDebugLevel |= 1L << (i2 + DebugSubSystem_BITSHIFT);
                    break;
                  }
                }
                if(!aszDebugSubSys[i2])
                {
                  i2 = atoi(szVal);
                  if(i2 > 0 && (i2 + DebugSubSystem_BITSHIFT) <= 32)
                  {
                    iWBDebugLevel |= 1L << (i2 + DebugSubSystem_BITSHIFT - 1);
                  }
                  else
                  {
                    WBDebugPrint("unrecognized subsystem %s\n", szVal);

                    goto argument_error_exit;
                  }
                }
              }

              if(!iDebugLevelSeen)
              {
                // assume EXCESSIVE debug level unless otherwise specified

                iWBDebugLevel = (iWBDebugLevel & DebugSubSystem_MASK)
                              | DebugLevel_Excessive;
              }

              break;

            case option_display:
              __internal_startup_display(szVal);
              break;

            case option_minimize:
              __internal_startup_minimize();
              break;
            case option_maximize:
              __internal_startup_maximize();
              break;
            case option_geometry:
              __internal_startup_geometry(szVal);
              break;

            case option_no_antialias:
              __internal_disable_antialias();
              break;

            case option_no_image_cache:
              __internal_disable_imagecache();
              break;

            default:
              WB_ERROR_PRINT("%s.%d - Internal error - unrecognized option: --%s\n",
                             __FUNCTION__, __LINE__, szArg);

argument_error_exit: // for argument errors go here - it displays usage()
              if(argvNew)
              {
                WBFree(argvNew);
              }

              return -1;
          }

          iFlag = 1;  // merely skip this entry (I found a match for one of those options)
          break;
        }
      }
    }

//loop_end:
    // at this point the argument may not have been recognized and so I must
    // copy it into the destination if it wasn't... as PRIOR to this there
    // should already be one or more unrecognized arguments

    if(!argvNew) // need to allocate copy
    {
      WB_DEBUG_PRINT(DebugLevel_Medium | DebugSubSystem_Init,
                     "%s.%d allocating argvNew at '%s'\n", __FUNCTION__, __LINE__, argv[1]);

      argvNew = WBAlloc(sizeof(*argvNew) * (argc + 2));

      if(!argvNew)
      {
        return -1;  // not enough memory
      }

      argcNew = 0;

      // copy original arguments, excluding this one
      i2 = argc_orig;  // the original 'argc' value

      while(i2 >= argc0) // I want to do this once on the first pass, etc.
      {
        WB_DEBUG_PRINT(DebugLevel_Medium | DebugSubSystem_Init,
                       "%s.%d copying argv at '%s'\n", __FUNCTION__, __LINE__, argv_orig[argcNew]);

        argvNew[argcNew] = argv_orig[argcNew];
        argcNew++;
        i2--;
      }
    }

    if(!iFlag) // iFlag means 'do not copy it'
    {
      argvNew[argcNew++] = argv[1];

      WB_DEBUG_PRINT(DebugLevel_Medium | DebugSubSystem_Init,
                     "%s.%d.  (2) copying argv at '%s'\n", __FUNCTION__, __LINE__, argv[1]);
    }

    argv++;
    argc--;
  }

  if(argvNew)
  {
    // copy the rest of the arguments

    while(argc > 1)
    {
      if(argv[1][0] == '-' && argv[1][1] == '-' && !argv[1][2]) // look for a '--'
      {
        // skip this one

        WB_DEBUG_PRINT(DebugLevel_Medium | DebugSubSystem_Init,
                       "%s.%d (3) skipping argv at '%s'\n", __FUNCTION__, __LINE__, argv[1]);
      }
      else
      {
        WB_DEBUG_PRINT(DebugLevel_Medium | DebugSubSystem_Init,
                       "%s.%d (3) copying argv at '%s'\n", __FUNCTION__, __LINE__, argv[1]);

        argvNew[argcNew++] = argv[1];
      }

      argv++;
      argc--;
    }

    *pargv = argvNew;
    *pargc = argcNew;
  }

  if((iWBDebugLevel & DebugLevel_MASK) > 0)
  {
    WBDebugPrint("DebugLevel set to %d\n", (int)(iWBDebugLevel & DebugLevel_MASK));
  }

  if((iWBDebugLevel & DebugSubSystem_MASK) != 0)
  {
//    WBDebugPrint("TEMPORARY:  iWBDebugLevel = %d (%08xH)\n", iWBDebugLevel, iWBDebugLevel);
    i2 = 0;
    for(i1=0; aszDebugSubSys[i1]; i1++)
    {
      if(iWBDebugLevel & (1L << (i1 + DebugSubSystem_BITSHIFT)))
      {
        if(!i2)
        {
          WBDebugPrint("Debug SubSystem: %s", aszDebugSubSys[i1]);
          i2 = 1;
        }
        else
        {
          WBDebugPrint(", %s", aszDebugSubSys[i1]);
        }
      }
    }

    for(; (i1 + DebugSubSystem_BITSHIFT) < 32; i1++)
    {
      if((iWBDebugLevel & (1L << (i1 + DebugSubSystem_BITSHIFT))) == DebugSubSystem_RESTRICT)
      {
        if(!i2)
        {
          WBDebugPrint("Debug SubSystem: RESTRICT");
          i2 = 1;
        }
        else
        {
          WBDebugPrint(", RESTRICT");
        }
      }
      else if(iWBDebugLevel & (1L << (i1 + DebugSubSystem_BITSHIFT)))
      {
        if(!i2)
        {
          WBDebugPrint("Debug SubSystem: %d", i1 + 1);
          i2 = 1;
        }
        else
        {
          WBDebugPrint(", %d", i1 + 1);
        }
      }
    }

    if(i2) // must print an additional LF
    {
      WBDebugPrint("\n");
    }
  }

  if(WBCheckDebugLevel(DebugLevel_Medium | DebugSubSystem_Init))
  {
    WBDebugPrint("Command line arguments passed to application:\n");

    for(i1=0; i1 < *pargc; i1++)
    {
      WBDebugPrint("  %4d    %s\n", i1, (*pargv)[i1]);
    }

    WBDebugPrint("\n");
  }

  return 0;
}

void WBToolkitUsage(void)
{
  fputs("X11 WorkBench Toolkit options (these should precede other options)\n"
        "    X11 STARTUP OPTIONS\n"
        "--help           Show the toolkit options\n"
        "--display xx     X11 display to use (default is DISPLAY env variable)\n"
        "--minimize       show minimized window on startup\n"
        "--maximize       show maximized window on startup\n"
        "--geometry geom  specify window geometry on startup\n"
        "                 geometry spec as per X specification (see X man page)\n"
        "                 typical value might be 800x600+100+50\n"
        "                 (default centers window with reasonable size)\n"
        "    DEBUG OPTIONS\n"
        "--debug n        debug level (default 0, errors only)\n"
        "                 1 = minimal, 7 is maximum debug level\n"
        "--subsys xx      subsystem to debug (implies --debug 7 if not specified)\n"
        "                 'xx' is a subsystem name or bit value (see window_helper.h)\n"
        "                 A bit value of 1 is equivalent to the lowest subsystem bit\n"
        "                 NOTE:  this option can be specified multiple times\n"
        "                 (You can specify '--subsys help' to get a list of subsystems)\n"
        "    SPECIAL OPTIONS\n"
        "--no-antialias   Disable anti-aliasing (may improve UI performance)\n"
        "--no-imagecache  Disable internal image cache for window paint/expose\n"
        "\n"
        " NOTE:  application options with separate parameters should appear after\n"
        "        any X11 Workbench Toolkit options, to avoid confusing the parser.\n"
        "\n", stderr);
}

const char *GetStartupAppName(void)
{
  return szAppName;
}



//                                                                          //
//                     ____         _                                       //
//                    |  _ \   ___ | |__   _   _   __ _                     //
//                    | | | | / _ \| '_ \ | | | | / _` |                    //
//                    | |_| ||  __/| |_) || |_| || (_| |                    //
//                    |____/  \___||_.__/  \__,_| \__, |                    //
//                                                |___/                     //
//                                                                          //

void WBSetDebugLevel(unsigned int iNew)  // pass level as argument, 0 for none, 1 for minimal, 2 for more, etc. up to 7
{
  iWBDebugLevel = iNew;
}

#if !defined(__GNUC__) && !defined(_MSVC_VER)
// querying debug level.  non-inline version
unsigned int WBGetDebugLevel(void) // debug_helper.h makes this inline when __GNUC__ or _MSVC_VER defined
{
  return iWBDebugLevel;
}

// checking debug level - non-inline version
int WBCheckDebugLevel(unsigned int dwLevel) // debug_helper.h makes this inline when __GNUC__ or _MSVC_VER defined
{
  if(WB_LIKELY((iWBDebugLevel & DebugLevel_MASK) < (dwLevel & DebugLevel_MASK)))
  {
    return 0;
  }

  if(!WB_UNLIKELY( WBGetDebugLevel() & DebugSubSystem_RESTRICT )) // RESTRICT not specified
  {
    if(!(dwLevel & DebugSubSystem_MASK) ) // no subsystem specified in debug output
    {
      return 1; // this is acceptable - since no subsystem specified, allow debug output if not 'RESTRICT'
    }
  }

  // at this point I have a debug subsystem 'RESTRICT' specified

  if(((dwLevel & DebugSubSystem_MASK) & (iWBDebugLevel & DebugSubSystem_MASK))
     != 0) // check to see that subsystem bits in 'dwLevel' match bits in 'iWBDebugLevel'
  {
    // at least one subsystem bit matches from 'dwLevel' and iWBDebugLevel
    return 1;
  }

  return 0;
}
#endif // !defined(__GNUC__) && !defined(_MSVC_VER)

void WBDebugPrint(const char *fmt, ...)
{
va_list va;

  va_start(va, fmt);

  vfprintf(stderr, fmt, va);
  fflush(stderr); // dump NOW before (possibly) crashing

  // TODO:  log file?

  va_end(va);
}

void WBDebugDump(const char *szTitle, void *pData, int cbData)
{
int i1, i2;
unsigned char *pX = (unsigned char *)pData;
static const int nCols = 16;

  WBDebugPrint("==========================================================================================\n"
               "%s\n", szTitle);

  for(i1=0; i1 < cbData; i1 += nCols, pX += nCols)
  {
    WBDebugPrint("%06x: ", i1); // assume less than 1Mb for now

    for(i2=0; i2 < nCols && (i1 + i2) < cbData; i2++)
    {
      WBDebugPrint("%02x ", pX[i2]);
    }

    for(; i2 < nCols; i2++)
    {
      WBDebugPrint("   ");
    }

    WBDebugPrint("|");

    for(i2=0; i2 < nCols && (i1 + i2) < cbData; i2++)
    {
      if(pX[i2] < ' ' || pX[i2] >= 0x80)
      {
        WBDebugPrint(" .");
      }
      else
      {
        WBDebugPrint(" %c", pX[i2]);
      }
    }

    WBDebugPrint("\n");
  }

  WBDebugPrint("==========================================================================================\n");
}

#ifndef NO_DEBUG

typedef struct __profile_info__
{
  const char *szFile;
  const char *szFunction;
  const char *szName;
  const char *szDesc;
#ifdef HAS_WB_UINT64_BUILTIN
  WB_INT64 nLine; // for better alignment, assuming 64-bit pointers
  WB_UINT64 nTime;
  WB_INT64 nCount;
  WB_INT64 nReserved; // for alignment
#else // HAS_WB_UINT64_BUILTIN
  WB_INT32 nLine;
  WB_UINT32 nTime;
  WB_INT32 nCount;
  WB_INT32 nReserved; // for alignment
#endif // HAS_WB_UINT64_BUILTIN
} PROFILE_INFO;

static PROFILE_INFO *paProfileInfo = NULL;
static int nProfileInfo = 0, nMaxProfileInfo = 0;

int WBRegisterProfileVar(const char *szFile, int nLine, const char *szFunction, const char *szName, const char *szDesc)
{
int iRval;

  if(WB_UNLIKELY(!paProfileInfo))
  {
    nMaxProfileInfo = 256;
    paProfileInfo = (PROFILE_INFO *)WBAlloc((nMaxProfileInfo + 1) * sizeof(*paProfileInfo));
    if(!paProfileInfo)
    {
      return -1; // an error
    }

    bzero(paProfileInfo, (nMaxProfileInfo + 1) * sizeof(*paProfileInfo)); // make sure
  }
  else if(WB_UNLIKELY((nProfileInfo + 1) >= nMaxProfileInfo))
  {
    void *pTemp;

    int nOldMaxProfileInfo = nMaxProfileInfo;

    nMaxProfileInfo = (nProfileInfo + 258) & 0xffffff00; // make it 256 bigger

    pTemp = WBReAlloc(paProfileInfo, (nMaxProfileInfo + 1) * sizeof(*paProfileInfo));

    if(WB_UNLIKELY(!pTemp))
    {
      nMaxProfileInfo = nOldMaxProfileInfo;
      return -1; // an error
    }

    paProfileInfo = (PROFILE_INFO *)pTemp; // now is permanent
    bzero(paProfileInfo + nOldMaxProfileInfo,
          (nMaxProfileInfo + 1 - nOldMaxProfileInfo) * sizeof(*paProfileInfo)); // the size of the new block
  }

  iRval = nProfileInfo++;

  paProfileInfo[iRval].szFile = szFile;
  paProfileInfo[iRval].szFunction = szFunction;
  paProfileInfo[iRval].szName = szName;
  paProfileInfo[iRval].szDesc = szDesc;
  paProfileInfo[iRval].nLine = nLine;

  paProfileInfo[iRval].nTime = 0;
  paProfileInfo[iRval].nCount = 0;

  return iRval;
}

void WBStartProfile(int nProfileID)
{
  if(WB_UNLIKELY(nProfileID < 0 || !paProfileInfo || nProfileID >= nMaxProfileInfo))
  {
    return; // bogus
  }

  if(paProfileInfo[nProfileID].nCount >= 0) // this detects 'out of order' invocation
  {
    paProfileInfo[nProfileID].nTime -= WBGetTimeIndex();
    paProfileInfo[nProfileID].nCount = -(paProfileInfo[nProfileID].nCount + 1);
  }
}

void WBStopProfile(int nProfileID)
{
  if(WB_UNLIKELY(nProfileID < 0 || !paProfileInfo || nProfileID >= nMaxProfileInfo))
  {
    return; // bogus
  }

  if(paProfileInfo[nProfileID].nCount < 0) // this detects 'out of order' invocation
  {
    paProfileInfo[nProfileID].nTime += WBGetTimeIndex();
    paProfileInfo[nProfileID].nCount = -(paProfileInfo[nProfileID].nCount);
  }
}

void WBDumpProfileData(void)
{
int i1, bNotYet = 1;

  if(!paProfileInfo)
  {
    return;
  }

  for(i1=0; i1 < nProfileInfo; i1++)
  {
    if(WB_UNLIKELY(paProfileInfo[i1].nCount == 0))
    {
      continue; // skip it
    }

    // in the unlikely event that i just bailed out in the middle of a profiled function
    if(WB_UNLIKELY(paProfileInfo[i1].nCount < 0)) // this detects I didn't call WBStopProfile() yet...
    {
      paProfileInfo[i1].nTime += WBGetTimeIndex();
      paProfileInfo[i1].nCount = -(paProfileInfo[i1].nCount);
    }

    if(WB_UNLIKELY(bNotYet))
    {
      WBDebugPrint("\n** PROFILE INFO **\n");
      bNotYet = 0;
    }

    WBDebugPrint("%s : %-8d %s\n    %s  %s\n"
#ifdef HAS_WB_UINT64_BUILTIN
                 "    nCount = %lld\n"
                 "    nTime = %llu microseconds\n"
#else // HAS_WB_UINT64_BUILTIN
                 "    nCount = %ld\n"
                 "    nTime = %lu microseconds\n"
#endif // HAS_WB_UINT64_BUILTIN
                 "    Average microseconds per count:  %0.1f\n\n",
                 paProfileInfo[i1].szFile,
                 (int)paProfileInfo[i1].nLine,
                 paProfileInfo[i1].szFunction,
                 paProfileInfo[i1].szName,
                 paProfileInfo[i1].szDesc,
                 paProfileInfo[i1].nCount,
                 paProfileInfo[i1].nTime,
                 (double)paProfileInfo[i1].nTime / (double)paProfileInfo[i1].nCount);
  }

  WBFree(paProfileInfo);
  paProfileInfo = NULL; // by convention
  nProfileInfo = 0;
  nMaxProfileInfo = 0; // these too
}

#endif // NO_DEBUG


//                                                                          //
//      ____               _                     _   _  _    _  _           //
//     / ___|  _   _  ___ | |_  ___  _ __ ___   | | | || |_ (_)| | ___      //
//     \___ \ | | | |/ __|| __|/ _ \| '_ ` _ \  | | | || __|| || |/ __|     //
//      ___) || |_| |\__ \| |_|  __/| | | | | | | |_| || |_ | || |\__ \     //
//     |____/  \__, ||___/ \__|\___||_| |_| |_|  \___/  \__||_||_||___/     //
//             |___/                                                        //
//                                                                          //

#if defined(HAS_WB_UINT64_BUILTIN) || defined(__DOXYGEN__)
WB_UINT64 WBGetTimeIndex(void)
#else // !defined(HAS_WB_UINT64_BUILTIN) && !defined(__DOXYGEN__)
WB_UINT32 WBGetTimeIndex(void)
#endif // defined(HAS_WB_UINT64_BUILTIN) || defined(__DOXYGEN__)
{
struct timeval tv;

  gettimeofday(&tv, NULL);

#ifdef HAS_WB_UINT64_BUILTIN /* meaning that the WB_UINT64 data type is a 'built-in' */

  return (WB_UINT64)tv.tv_sec * (WB_UINT64)1000000
         + (WB_UINT64)tv.tv_usec;

#else // WB_UINT64 is a structure typedef; just return a 32-bit value for now
  {
    double d1 = tv.tv_sec * 1000000.0;
    d1 += tv.tv_usec;

    return (WB_UINT32)floor(fmod(d1, (double)0xffffffff));
    // TODO:  use floor + frac to convert to two WB_UINT32's (for now I just return the lower half)
    // TODO:  maybe do my own long long library in this VERY UNLIKELY case?
  }
#endif // WB_UINT64
}

void WBDelay(uint32_t uiDelay)  // approximate delay for specified period (in microseconds).  may be interruptible
{
#ifdef HAVE_NANOSLEEP
struct timespec tsp;

  if(WB_UNLIKELY(uiDelay >= 1000000L))
  {
    tsp.tv_sec = uiDelay / 1000000L;
    uiDelay = uiDelay % 1000000L; // number of microseconds converted to nanoseconds
  }
  else
  {
    tsp.tv_sec = 0; // it's assumed that this method is slightly faster
  }

  tsp.tv_sec = 0;
  tsp.tv_nsec = uiDelay * 1000;  // wait for .1 msec

  nanosleep(&tsp, NULL);
#else  // HAVE_NANOSLEEP

  usleep(uiDelay);  // 100 microsecs - a POSIX alternative to 'nanosleep'

#endif // HAVE_NANOSLEEP
}

int WBCPUCount(void)
{
// determine # of CPUs to get the default # of jobs during compile
//    FreeBSD:  sysctl vars:  kern.smp.cpus hw.ncpu  (both have the correct count, even in a VM)
//    Linux:  /proc/cpuinfo - filter on 'processor:', one line per active core
//                            (in a VM, only the assigned cores show up, so count them)
int iCPU = 0;

#if defined(__FreeBSD__)
// TODO:  a config option to test for 'sysctlbyname' and the sys/sysctl.h file?
unsigned long cb;

  cb = sizeof(iCPU);
  iCPU = 0;
  if(sysctlbyname("hw.ncpu", &iCPU, &cb, NULL, 0)) // could also use MIBs CTL_HW and HW_NCPU
  {
//    WB_ERROR_PRINT("ERROR - %s - hw.ncpu, errno=%d  iCPU=%d  cb=%ld\n", __FUNCTION__, errno, iCPU, cb);
    cb = sizeof(iCPU);
    iCPU = 0;

    if(sysctlbyname("kern.smp.cpus", &iCPU, &cb, NULL, 0)) // could also use MIBs CTL_HW and HW_NCPU
    {
//      WB_ERROR_PRINT("ERROR - %s - kernel.smp.cpus, errno=%d  iCPU=%d  cb=%ld\n", __FUNCTION__, errno, iCPU, cb);
      return 0;
    }
  }

//  WB_ERROR_PRINT("TEMPORARY:  %s - iCPU=%d\n", __FUNCTION__, iCPU);

  return iCPU;

#elif defined(linux)

FILE *pF;
char tbuf[256];
char *p1, *p2;

  pF = fopen("/proc/cpuinfo", "r");
  if(pF)
  {
    while(fgets(tbuf, sizeof(tbuf), pF))
    {
      // read each line, then scan for 'processor' and cound 'em up
      // NOTE:  if there's a better way, I'd like to see it...

      p1 = tbuf;
      while(*p1 && *p1 <= ' ')
      {
        p1++; // skip leadin white space
      }

      p2 = p1 + strlen(p1);
      while(p2 > p1 && *(p2 - 1) <= ' ')
      {
        *(--p2) = 0; // trim trailing white space
      }

      if(!strncmp(p1, "processor", 9) &&  // TODO:  check it's unique?
         p1[9] && p1[9] <= ' ') // typically is followed by a tab then ':'
      {
        iCPU++; // count them!
      }
    }

    fclose(pF);
  }

#elif defined(WIN32)
  iCPU == 0; // just fail (for now)
#else
  iCPU == 0; // just fail
#endif // all of that

  return iCPU;
}




//                                                                          //
//                __  __     _     _      _      ___    ____                //
//               |  \/  |   / \   | |    | |    / _ \  / ___|               //
//               | |\/| |  / _ \  | |    | |   | | | || |                   //
//               | |  | | / ___ \ | |___ | |___| |_| || |___                //
//               |_|  |_|/_/   \_\|_____||_____|\___/  \____|               //
//                                                                          //
//                                                                          //

// ********************
// MEMORY SUB-ALLOCATOR
// ********************

// NOTES TO SELF (design notes)
// a) allocate Xk blocks of memory for suballocator blocks of a specific size
// b) the first 'page' of the memory block is an array of indices (double-link list)
// c) the remainder of the block is an ordered set of memory blocks of a fixed size
// d) as more blocks are added, they are added to a linked list associated with the size
// e) blocks "more than Xk" will be malloc'd and added to the 'malloc' list.
// f) malloc'd blocks will have a double-link list and a header with extra info
// This way an allocated address will auto-indicate which memory block it belongs to

static const char szWBAllocTag[]="WB_M";
#define WB_ALLOC_TAG (*((const unsigned int *)szWBAllocTag)) /*< tag indicating it's a __malloc_header__ **/

#define PMALLOC_FLAG (&mallocFlagMalloc) /*< when pPrev and pNext point to THIS, it's a "malloc'd" pointer **/

struct __malloc_header__
{
  struct __malloc_header__ *pPrev, *pNext;  
  unsigned int iTag;                        
  unsigned int cbSize;                      
};

static struct __malloc_header__ mallocFlagMalloc; // pointers to THIS indicate "I am a

//static struct __malloc_header__ *pMallocList = NULL, *pMallocListEnd = NULL;
// TODO:  when I go to implement this, uncomment the above line

// TODO:  sync object for pMallocList etc.

void *WBAlloc(int nSize)
{
unsigned char *pRval;
struct __malloc_header__ *pMH;
unsigned int nAllocSize, nNewSize, nLimit;


  if(nSize <= 0)
  {
    return NULL;
  }

  // TODO:  implement allocation of smaller memory blocks as 'power of 2' blocks.
  //

  nAllocSize = nSize + sizeof(*pMH);
  // nAllocSize will be converted to the next higher power of 2

  nLimit = nAllocSize + (nAllocSize >> 1);

  for(nNewSize=64; nNewSize < nLimit; nNewSize <<= 1)
  { } // NOTE:  64 bytes is the smallest allocation unit

//  if(nNewSize < 4096) TODO:  internally sub-allocated blocks
//  {
//    TODO:  maintain lists of pre-allocated blocks of memory, allocating new memory as needed
//           (this memory will need to be re-used intelligently so trash mashing can work properly
//  }

  // for larger blocks, I use 'malloc'

  pRval = (unsigned char *)malloc(nNewSize); // for now - later, use sub-allocation stuff

  if(pRval)
  {
#ifdef HAVE_MALLOC_USABLE_SIZE
    void *pActual = pRval;
#endif // HAVE_MALLOC_USABLE_SIZE

    pMH = (struct __malloc_header__ *)pRval;

    pRval += sizeof(*pMH);

    pMH->pPrev = PMALLOC_FLAG; // this indicates it was 'malloc'd
    pMH->pNext = PMALLOC_FLAG; // this indicates it was 'malloc'd
    pMH->iTag = WB_ALLOC_TAG;

#ifdef HAVE_MALLOC_USABLE_SIZE
    nLimit = malloc_usable_size(pActual); // the ACTUAL SIZE of the memory block
    if(nLimit > nNewSize)
    {
      nNewSize = nLimit;
    }
#endif // HAVE_MALLOC_USABLE_SIZE
    pMH->cbSize = nNewSize - sizeof(*pMH);

  }

  return pRval;
}

int WBAllocUsableSize(void *pBuf)
{
struct __malloc_header__ *pMH;


  if(!pBuf)
  {
    return -1; // an error
  }

  // validate pointer
  // TODO:  check against linked list of 'allocated' blocks first

  pMH = ((struct __malloc_header__ *)pBuf) - 1;

  if(pMH->iTag == WB_ALLOC_TAG)
  {
    return pMH->cbSize;
  }

  return -1; // not valid (error)
}

void WBFree(void *pBuf)
{
struct __malloc_header__ *pMH;

  if(!pBuf)
  {
    return;
  }

  // validate pointer
  // TODO:  check against linked list of 'allocated' blocks first

  pMH = ((struct __malloc_header__ *)pBuf) - 1;

  if(pMH->iTag == WB_ALLOC_TAG)
  {
    if(pMH->pPrev == PMALLOC_FLAG &&
       pMH->pNext == PMALLOC_FLAG)
    {
      // assign header values that invalidate re-freeing the same memory

      pMH->iTag = 0; // make sure it's no longer valid (so I don't try to re-free)
      pMH->pPrev = NULL; // same with these values
      pMH->pNext = NULL;
      pMH->cbSize = 0;

      free(pMH);
    }
    else
    {
      // TODO:  make sure it's not "already free" somehow since re-freeing free memory is *BAD*

      WB_ERROR_PRINT("TODO:  %s 'pre-alloc' unimplemented - NOT freeing memory %p\n", __FUNCTION__, pBuf);
    }
  }
  else
  {
    WB_ERROR_PRINT("ERROR:  %s NOT freeing (invalid) memory %p\n", __FUNCTION__, pBuf);
  }
}

void * WBReAlloc(void *pBuf, int nNewSize)
{
struct __malloc_header__ *pMH;
unsigned char *pRval = NULL;
unsigned int nAllocSize, nNewNewSize, nLimit;


  if(!pBuf || nNewSize <= 0)
  {
    return NULL;
  }

  // validate pointer
  // TODO:  check against linked list of 'allocated' blocks first

  pMH = ((struct __malloc_header__ *)pBuf) - 1;

  if(pMH->iTag == WB_ALLOC_TAG)
  {
    // the whole point of this is to minimize the actual need to re-allocate the
    // memory block by maintaining a LARGER block than is actually needed when
    // allocated or re-allocated.  Gradually increasing size is pretty much assumed.

    if(pMH->cbSize >= nNewSize)
    {
      return pBuf; // no change (same pointer) since it's large enough already
    }

    // TODO:  implement re-allocation of smaller memory blocks as 'power of 2' blocks.
    //

    nAllocSize = nNewSize + sizeof(*pMH);
    // nAllocSize will be converted to the next higher power of 2

    nLimit = nAllocSize + (nAllocSize >> 1);
    for(nNewNewSize=64; nNewNewSize < nLimit; nNewNewSize <<= 1) { } // NOTE:  64 bytes is the smallest allocation unit

    if(pMH->pPrev != PMALLOC_FLAG &&
       pMH->pNext != PMALLOC_FLAG)
    {
      if(nNewNewSize >= 4096) // TODO:  internally sub-allocated blocks
      {
        // it WAS an internally sub-alloced block.  NOW it is a MALLOC block.

        pRval = WBAlloc(nNewNewSize); // just allocate it with 'WBAlloc' and let 'WBAlloc' do the work
        if(!pRval)
        {
          return NULL; // not enough memory
        }

        memcpy(pRval, pBuf, pMH->cbSize); // copy the old data, but not the stuff in the header.
        WBFree(pBuf); // free 'pBuf' now that it's not needed

        return pRval; // return the new pointer (old is no longer valid, new one is 'malloc'ed version).
      }
      else
      {
        //TODO:  maintain lists of pre-allocated blocks of memory, allocating new memory as needed
        //       (this memory will need to be re-used intelligently so trash mashing can work properly

        WB_ERROR_PRINT("TODO:  %s - 'pre-alloc' is NOT implemented.  Pointer %p NOT re-allocated\n", __FUNCTION__, pBuf);
        return NULL;
      }
    }

    pRval = realloc(pMH, nNewNewSize); // for now...
    if(pRval)
    {
#ifdef HAVE_MALLOC_USABLE_SIZE
    void *pActual = pRval;
#endif // HAVE_MALLOC_USABLE_SIZE

      pMH = (struct __malloc_header__ *)pRval;
      pRval += sizeof(*pMH);

#ifdef HAVE_MALLOC_USABLE_SIZE
      nLimit = malloc_usable_size(pActual); // the ACTUAL SIZE of the memory block
      if(nLimit > nNewSize)
      {
        nNewSize = nLimit;
      }
#endif // HAVE_MALLOC_USABLE_SIZE
      pMH->cbSize = nNewNewSize - sizeof(*pMH);
    }
  }
  else
  {
    WB_ERROR_PRINT("ERROR - %s NOT re-allocating memory %p\n", __FUNCTION__, pBuf);
  }

  return pRval;
}

void WBSubAllocTrashMasher(void)
{
  // do nothing (for now)
  // later, walk memory list to see if any blocks are completely unused, and free them.
  // in debug mode, maybe there's a way to validate memory blocks?
}


//                                                                          //
//                  ____   _          _                                     //
//                 / ___| | |_  _ __ (_) _ __    __ _  ___                  //
//                 \___ \ | __|| '__|| || '_ \  / _` |/ __|                 //
//                  ___) || |_ | |   | || | | || (_| |\__ \                 //
//                 |____/  \__||_|   |_||_| |_| \__, ||___/                 //
//                                              |___/                       //
//                                                                          //


// ************************
// generic string utilities
// ************************

char *WBCopyString(const char *pSrc)
{
char *pDest;
int iLen;

  if(!pSrc || !*pSrc)
  {
    pDest = WBAlloc(2);

    if(pDest)
    {
      *pDest = 0;
    }
  }
  else
  {
    iLen = strlen(pSrc);

    pDest = WBAlloc(iLen + 1);

    if(pDest)
    {
      memcpy(pDest, pSrc, iLen);
      pDest[iLen] = 0;
    }
  }

  return pDest;
}

char *WBCopyStringN(const char *pSrc, unsigned int nMaxChars)
{
char *pDest;
int iLen;
const char *p1;

  if(!pSrc || !*pSrc)
  {
    pDest = WBAlloc(2);

    if(pDest)
    {
      *pDest = 0;
    }
  }
  else
  {
    for(p1 = pSrc, iLen = 0; iLen < nMaxChars && *p1; p1++, iLen++)
    { } // determine length of 'pStr' to copy

    pDest = WBAlloc(iLen + 1);

    if(pDest)
    {
      memcpy(pDest, pSrc, iLen);
      pDest[iLen] = 0;
    }
  }

  return pDest;
}


void WBCatString(char **ppDest, const char *pSrc)  // concatenate onto WBAlloc'd string
{
int iLen, iLen2;
int iMaxLen;
char *p1, *p2;

  if(!ppDest || !pSrc || !*pSrc)
  {
    return;
  }

  if(*ppDest)
  {
    p1 = p2 = *ppDest;

    iMaxLen = WBAllocUsableSize(p1);

    if(iMaxLen <= 0) // an error
    {
      return;
    }

    while(*p2
          && (p2 - p1) < iMaxLen
         )
    {
      p2++;
    }

    iLen2 = strlen(pSrc);
    iLen = iLen2 + (p2 - p1);

    if((iLen + 1) > iMaxLen)
    {
      *ppDest = WBReAlloc(p1, iLen + 1);
      if(!*ppDest)
      {
        *ppDest = p1;
        return;  // not enough memory
      }

      p2 = (p2 - p1) + *ppDest;  // re-position end of string
    }

    memcpy(p2, pSrc, iLen2);
    p2[iLen2] = 0;  // make sure last byte is zero
  }
  else
  {
    *ppDest = WBCopyString(pSrc);
  }
}

void WBCatStringN(char **ppDest, const char *pSrc, unsigned int nMaxChars)
{
int iLen, iLen2;
int iMaxLen;
char *p1, *p2;
const char *p3;


  if(!ppDest || !pSrc || !*pSrc)
  {
    return;
  }

  if(*ppDest)
  {
    p1 = p2 = *ppDest;

    iMaxLen = WBAllocUsableSize(p1);

    if(iMaxLen <= 0)
    {
      return;
    }


    while(*p2
          && (p2 - p1) < iMaxLen
         )
    {
      p2++;
    }

    for(iLen2=0, p3 = pSrc; iLen2 < nMaxChars && *p3; p3++, iLen2++)
    { }  // determine what the length of pSrc is up to a zero byte or 'nMaxChars', whichever is first

    iLen = iLen2 + (p2 - p1);

    if((iLen + 1) > iMaxLen)
    {
      *ppDest = WBReAlloc(p1, iLen + 1);
      if(!*ppDest)
      {
        *ppDest = p1; // restore the old pointer value
        return;  // not enough memory
      }

      p2 = (p2 - p1) + *ppDest;  // re-position end of string
    }

    memcpy(p2, pSrc, iLen2);
    p2[iLen2] = 0;  // make sure last byte is zero
  }
  else
  {
    *ppDest = WBCopyStringN(pSrc, nMaxChars);
  }
}

void WBDeQuoteString(char *pString)
{
char *p1, *pDest;

  p1 = pDest = pString;

  while(*p1)
  {
    if(*p1 == '"' || *p1 == '\'')
    {
      char c1 = *(p1++);

      while(*p1 &&
            (*p1 != c1 || p1[1] == c1))
      {
        if(*p1 == c1)
        {
          p1++;
        }

        *(pDest++) = *(p1++);
      }

      if(*p1 == c1)
      {
        p1++;
      }
    }
    else
    {
      if(pDest != p1)
      {
        *pDest = *p1;
      }

      pDest++;
      p1++;
    }
  }

  *pDest = 0; // make sure
}

static char __amp_char(char **ppSpot)
{
char *pS = *ppSpot;

  if(!memcmp(pS, "&amp;", 5))
  {
    *ppSpot += 5;
    return '&';
  }
  else if(!memcmp(pS, "&lt;", 4))
  {
    *ppSpot += 4;
    return '<';
  }
  else if(!memcmp(pS, "&gt;", 4))
  {
    *ppSpot += 4;
    return '>';
  }

  return 0;
}

void WBNormalizeXMLString(char *pString)
{
char *p1, *pDest;
char c1, c2;


  // not only de-quoting, but converting '&amp;' '&lt;' '&gt;' to '&' '<' and '>'

  p1 = pDest = pString;

  while(*p1)
  {
    if(*p1 == '"' || *p1 == '\'')
    {
      c1 = *(p1++);

      while(*p1 &&
            (*p1 != c1 || p1[1] == c1))
      {
        if(*p1 == c1)
        {
          p1++;
        }
        else if(*p1 == '&') // substitute
        {
          c2 = __amp_char(&p1);

          if(c2)
          {
            *(pDest++) = c2;
            continue;
          }

          // if it's not recognized, just process it as normal chars
        }

        *(pDest++) = *(p1++);
      }

      if(*p1 == c1)
      {
        p1++;
      }
    }
    else if(*p1 == '&') // substitute
    {
      c2 = __amp_char(&p1);

      if(!c2)
      {
        goto normal_char; // just process it as normal chars
      }

      *(pDest++) = c2;
    }
    else
    {
normal_char:

      if(pDest != p1)
      {
        *pDest = *p1;
      }

      pDest++;
      p1++;
    }
  }

  *pDest = 0; // make sure
}

int WBStringLineCount(const char *pSrc, unsigned int nMaxChars)
{
int iRval = 1;
const char *p1;

  if(!pSrc || (!nMaxChars && !*pSrc))
  {
    return 0;
  }

  if(!nMaxChars)
  {
    nMaxChars = strlen(pSrc);
  }

  do
  {
    p1 = WBStringNextLine(pSrc, &nMaxChars);
    if(p1 && nMaxChars) // another line remains
    {
      iRval++;
    }

    pSrc = p1;

  } while(pSrc && nMaxChars);

  return iRval;
}

const char *WBStringNextLine(const char *pSrc, unsigned int *pnMaxChars)
{
int nMaxChars;

  if(!pSrc)
  {
    if(pnMaxChars)
    {
      *pnMaxChars = 0;
    }

    return NULL;
  }

  if(pnMaxChars)
  {
    nMaxChars = *pnMaxChars;
  }
  else if(!*pSrc)
  {
    return NULL; // end of string (no more)
  }
  else
  {
    nMaxChars = strlen(pSrc);
  }

  // TODO:  handle MBCS differently? (for now, no special handling)

  while(nMaxChars > 0)
  {
    if(*pSrc == '\r')
    {
      pSrc++;
      nMaxChars--;

      if(nMaxChars > 0 && *pSrc == '\n')
      {
        pSrc++;
        nMaxChars--;
      }

      break;
    }
    else if(*pSrc == '\n')
    {
      pSrc++;
      nMaxChars--;

      if(nMaxChars > 0 && *pSrc == '\r')
      {
        pSrc++;
        nMaxChars--;
      }

      break;
    }
    else if(*pSrc == '\f' || // form feed is like a newline
            *pSrc == '\v')   // vertical tab (similar, for now)
    {
      pSrc++;
      nMaxChars--;

      break;
    }
// TODO:  check for UTF-8 paragraph and line separators?
//        http://www.unicodemap.org/details/0x2028/index.html  (line separator - alternate LF?)
//        http://www.unicodemap.org/details/0x202A/index.html  (paragraph separator - alternate to CTRL+L ?)
//
    else if(!*pSrc) // TODO:  test for unicode?  normally we just assume UTF-8 is compatible with ASCII
    {
      nMaxChars = 0;
      break;
    }

    pSrc++;
    nMaxChars--;
  }

  if(pnMaxChars)
  {
    *pnMaxChars = nMaxChars;
  }

  return pSrc;
}




//                                                                                 //
//   ____         _         _                _   _              _                  //
//  |  _ \  ___  (_) _ __  | |_  ___  _ __  | | | |  __ _  ___ | |__    ___  ___   //
//  | |_) |/ _ \ | || '_ \ | __|/ _ \| '__| | |_| | / _` |/ __|| '_ \  / _ \/ __|  //
//  |  __/| (_) || || | | || |_|  __/| |    |  _  || (_| |\__ \| | | ||  __/\__ \  //
//  |_|    \___/ |_||_| |_| \__|\___||_|    |_| |_| \__,_||___/|_| |_| \___||___/  //
//                                                                                 //
//                                                                                 //

typedef struct __pointer_hash__
{
  WB_UINT32 uiHash;     // 32-bit pointer hash value, must be zero for 'free' entry
  void *pValue;         // NULL if unused entry, else the pointer value
  WB_UINT32 dwTick;     // millis count when I last created/referenced this hash
  WB_UINT32 dwRefCount; // reference count (deleted on '0')
} POINTER_HASH;

static POINTER_HASH *pPointerHashes = NULL; // WBAlloc'd array
static int nPointerHash = 0, nMaxPointerHash = 0; // for now, simple array

static WB_UINT32 uiPointerHashSpinlock = 0;

static void WBFreePointerHashes(void)
{
  if(pPointerHashes)
  {
    WBFree(pPointerHashes);
    pPointerHashes = NULL;
  }

  nPointerHash = 0;
  nMaxPointerHash = 0;

  uiPointerHashSpinlock = 0;
}

WB_UINT32 WBCreatePointerHash(void *pPointer)
{
int i1, iFreeIndex;
WB_UINT32 uiRval = 0;
WB_UINT32 dwTick = (WB_UINT32)(WBGetTimeIndex() >> 10); // fast 'millis', micros / 1024


#warning TODO:  prevent hash-jamming attacks from external processes posting tainted events

  // TODO:  consider keeping a list of already-used hashes that time out over a longer
  //        period of time.  This would prevent "hash jamming" from easily working, from
  //        a malicious process posting X11 messages to a window that's known to accept
  //        events with a hashed pointer in them.  Event sniffing could reveal a previously
  //        used hash that should not be re-used under any circumstance.  Hash re-use could
  //        then potentially be detected.

  // TODO:  consider a validation data type associated with a particular hash, which the
  //        event-receiving function could use to validate the type of data being hashed,
  //        in the case that hash-jamming is being used, to at least prevent "the wrong data"
  //        from being accessed by the event receiver, or specifically a page fault from
  //        exceeding the bounds of "the wrong data".

  if(!pPointer)
  {
    return 0; // not valid, just return zero
  }

  while(WBInterlockedExchange(&uiPointerHashSpinlock, 1))
  {
    WBDelay(100);
  }

  if(!pPointerHashes)
  {
    nMaxPointerHash = 512;   // initial size (make it a '#define' ?)
    pPointerHashes = (POINTER_HASH *)WBAlloc(nMaxPointerHash * sizeof(*pPointerHashes));

    if(!pPointerHashes)
    {
      goto return_point;
    }

    nPointerHash = 0;
  }
  else if(nPointerHash >= nMaxPointerHash)
  {
    void *pTemp = WBReAlloc(pPointerHashes, (nMaxPointerHash + 256) * sizeof(*pPointerHashes));

    if(!pTemp)
    {
      goto return_point;
    }

    pPointerHashes = (POINTER_HASH *)pTemp; // new, re-alloc'd pointer
    nMaxPointerHash += 256;

//    WB_ERROR_PRINT("TEMPORARY:  %s - new # of hashes %d\n", __FUNCTION__, nMaxPointerHash);
  }

  // first, check for a match, and the first 'free' index
  for(i1=0, iFreeIndex = -1; i1 < nPointerHash; i1++)
  {
    if(pPointerHashes[i1].pValue == pPointer)
    {
      if(uiRval) // more than one?
      {
        WB_ERROR_PRINT("ERROR:  %s - matching 'pPointer' %p for multiple hash entries\n", __FUNCTION__, pPointer);
      }
      else // NOTE:  if this entry WAS too old, I'll still re-use it and reset the tick
      {
        uiRval = pPointerHashes[i1].uiHash;
        pPointerHashes[i1].dwTick = dwTick; // new timestamp
        pPointerHashes[i1].dwRefCount++; // increase ref count

        // NOTE:  I will only use this one.  but I'll check the rest for timeout by continuing
      }
    }
    else if(!pPointerHashes[i1].pValue &&
            !pPointerHashes[i1].uiHash) // a free entry
    {
      if(iFreeIndex < 0)               // no free index found (yet)
      {
        iFreeIndex = i1; // first free entry found
      }
    }
    else if((dwTick - pPointerHashes[i1].dwTick) > WB_SECURE_HASH_TIMEOUT) // auto cleanup part
    {
      // checking for timeout, and erasing things if timed out

//      WB_ERROR_PRINT("TEMPORARY:  %s - deleting 'aged' entry, timeout = %u\n", __FUNCTION__,
//                     (dwTick - pPointerHashes[i1].dwTick));
//      WB_ERROR_PRINT("   %2d : %08xH %10u %4u %p\n",
//                     i1, pPointerHashes[i1].uiHash, pPointerHashes[i1].dwTick,
//                     pPointerHashes[i1].dwRefCount, pPointerHashes[i1].pValue);

      // too old - erase it, freeing up the location

      pPointerHashes[i1].uiHash = 0; // also needed to mark it 'free'
      pPointerHashes[i1].dwTick = 0;
      pPointerHashes[i1].pValue = NULL; // thus marking it 'free'
      pPointerHashes[i1].dwRefCount = 0; // regardless of ref count, remove it

      if(iFreeIndex < 0) // no free index yet?  remember it
      {
        iFreeIndex = i1;
      }
    }
  }

  if(uiRval) // found one??
  {
    goto return_point;
  }


  // at this point, did NOT find a match, so I need to create it

  if(iFreeIndex < 0) // not re-using an entry?
  {
    iFreeIndex = nPointerHash++; // increment total count, use last entry
  }

  pPointerHashes[iFreeIndex].pValue = pPointer;
  pPointerHashes[iFreeIndex].dwTick = dwTick;
  pPointerHashes[iFreeIndex].dwRefCount = 1;

  // see if there's a 'crash' between two identical hashes
  // it's not likely, but it IS possible.  So test for it.

  while(1) /* we assume it will bust out eventually */
  {
    uiRval = ((WB_UINT32)((WB_UINT64)pPointer) ^ dwTick) & 0xffffffff;
    // NOTE:  this should, in theory, work within a very short time

    if(uiRval) // can't allow a zero (this should be RARE, if ever at all)
    {
      for(i1=0; i1 < nPointerHash; i1++)
      {
        if(pPointerHashes[i1].uiHash == uiRval)
        {
          break;
        }
      }

      if(i1 >= nPointerHash) // no matching entry found
      {
        break;
      }
    }

    dwTick -= 113; // decrement it by a prime number so I can test for it
                   // being there again, but with a different hash value
  }

  pPointerHashes[iFreeIndex].uiHash = uiRval; // save this value where the free index resides

//  WB_ERROR_PRINT("TEMOPRARY:  %s - adding hash %u for %p at %d\n", __FUNCTION__, uiRval, pPointer, iFreeIndex);


return_point:

  WBInterlockedExchange(&uiPointerHashSpinlock, 0);

//  if(!uiRval)
//  {
//    WB_ERROR_PRINT("TEMPORARY:  %s - did NOT create hash for pointer %p\n", __FUNCTION__, pPointer);
//  }

  return uiRval;
}

void WBDestroyPointerHash(WB_UINT32 uiHash)
{
int i1;
WB_UINT32 dwTick = (WB_UINT32)(WBGetTimeIndex() >> 10); // fast 'millis', micros / 1024


  if(!uiHash)
  {
    return; // not valid, just return
  }

  while(WBInterlockedExchange(&uiPointerHashSpinlock, 1))
  {
    WBDelay(100);
  }

  for(i1=0; i1 < nPointerHash; i1++)
  {
    if(!pPointerHashes[i1].pValue &&
       !pPointerHashes[i1].uiHash) // a free entry
    {
      continue;
    }

    // check timeouts first, THEN destroy via decremented ref count

    if((dwTick - pPointerHashes[i1].dwTick) > WB_SECURE_HASH_TIMEOUT) // check for aging while I'm at it
    {
//      WB_ERROR_PRINT("TEMPORARY:  %s - deleting 'aged' entry, timeout = %u\n", __FUNCTION__,
//                     (dwTick - pPointerHashes[i1].dwTick));
//      WB_ERROR_PRINT("   %2d : %08xH %10u %4u %p\n",
//                     i1, pPointerHashes[i1].uiHash, pPointerHashes[i1].dwTick,
//                     pPointerHashes[i1].dwRefCount, pPointerHashes[i1].pValue);

      // erase it, freeing up the location
erase_it:

      pPointerHashes[i1].uiHash = 0; // this zero, together with 'pValue == NULL' means it's "free"
      pPointerHashes[i1].dwTick = 0;
      pPointerHashes[i1].pValue = NULL; // thus marking it 'free'
      pPointerHashes[i1].dwRefCount = 0; // regardless of ref count, remove it
    }
    else if(pPointerHashes[i1].uiHash == uiHash)
    {
//      WB_ERROR_PRINT("TEMPORARY:  %s - ref count prior to decrement = %d for %p (%08xH)\n", __FUNCTION__,
//                     pPointerHashes[i1].dwRefCount, pPointerHashes[i1].pValue,
//                     pPointerHashes[i1].uiHash);

      if(pPointerHashes[i1].dwRefCount)
      {
        pPointerHashes[i1].dwRefCount --;
      }

      if(!(pPointerHashes[i1].dwRefCount))
      {
//        WB_ERROR_PRINT("TEMPORARY:  %s - deleting matching entry\n", __FUNCTION__);
//        WB_ERROR_PRINT("   %2d : %08xH %10u %4u %p\n",
//                       i1, pPointerHashes[i1].uiHash, pPointerHashes[i1].dwTick,
//                       pPointerHashes[i1].dwRefCount, pPointerHashes[i1].pValue);

        goto erase_it;
      }
    }
  }

  WBInterlockedExchange(&uiPointerHashSpinlock, 0);
}

void WBDestroyPointerHashPtr(void *pPointer)
{
int i1;
WB_UINT32 dwTick = (WB_UINT32)(WBGetTimeIndex() >> 10); // fast 'millis', micros / 1024


  if(!pPointer)
  {
    return; // not valid, just return
  }

  while(WBInterlockedExchange(&uiPointerHashSpinlock, 1))
  {
    WBDelay(100);
  }

  for(i1=0; i1 < nPointerHash; i1++)
  {
    if(!pPointerHashes[i1].uiHash && !pPointerHashes[i1].pValue)
    {
      continue; // free entry, ignore it
    }

    if((dwTick - pPointerHashes[i1].dwTick) > WB_SECURE_HASH_TIMEOUT) // check for aging while I'm at it
    {
//      WB_ERROR_PRINT("TEMPORARY:  %s - deleting 'aged' entry, timeout = %u\n", __FUNCTION__,
//                     (dwTick - pPointerHashes[i1].dwTick));
//      WB_ERROR_PRINT("   %2d : %08xH %10u %4u %p\n",
//                     i1, pPointerHashes[i1].uiHash, pPointerHashes[i1].dwTick,
//                     pPointerHashes[i1].dwRefCount, pPointerHashes[i1].pValue);

      // erase it, freeing up the location (hash will be zero)

erase_it:
      pPointerHashes[i1].uiHash = 0; // this zero, together with 'pValue == NULL' means it's "free"
      pPointerHashes[i1].dwTick = 0;
      pPointerHashes[i1].pValue = NULL; // thus marking it 'free'
      pPointerHashes[i1].dwRefCount = 0; // regardless of ref count, remove it

    }
    else if(pPointerHashes[i1].pValue == pPointer) // always free it
    {
//      WB_ERROR_PRINT("TEMPORARY:  %s - deleting matching entry\n", __FUNCTION__);
//      WB_ERROR_PRINT("   %2d : %08xH %10u %4u %p\n",
//                     i1, pPointerHashes[i1].uiHash, pPointerHashes[i1].dwTick,
//                     pPointerHashes[i1].dwRefCount, pPointerHashes[i1].pValue);

      goto erase_it; // regardless of ref count, remove it (buh-bye)
    }
  }

  WBInterlockedExchange(&uiPointerHashSpinlock, 0);
}

void * WBGetPointerFromHash(WB_UINT32 uiHash)
{
int i1;
void *pRval = NULL;


  if(!uiHash)
  {
    return NULL; // not valid, just return NULL
  }

  while(WBInterlockedExchange(&uiPointerHashSpinlock, 1))
  {
    WBDelay(100);
  }

  for(i1=0; i1 < nPointerHash; i1++)
  {
    if(!pPointerHashes[i1].pValue || // for now just ignore these
       pPointerHashes[i1].uiHash != uiHash)
    {
      continue; // this treats NULL pointers as a 'mismatch'
    }

    // TODO:  check for timeouts?

    pRval = pPointerHashes[i1].pValue;
    goto exit_point;
  }


exit_point:

  WBInterlockedExchange(&uiPointerHashSpinlock, 0);

//  if(!pRval)
//  {
//    WB_ERROR_PRINT("TEMPORARY:  %s - did NOT find pointer for hash %u (%08xH)\n", __FUNCTION__, uiHash, uiHash);
//
//    for(i1=0; i1 < nPointerHash; i1++)
//    {
//      WB_ERROR_PRINT("   %2d : %08xH %10u %4u %p\n",
//                     i1, pPointerHashes[i1].uiHash, pPointerHashes[i1].dwTick,
//                     pPointerHashes[i1].dwRefCount, pPointerHashes[i1].pValue);
//    }
//
//    WB_ERROR_PRINT("---------------------------------------------------------------------\n\n");
//  }

  return pRval; // NULL if not found
}



//                                                                          //
//                        _    _                                            //
//                       / \  | |_  ___   _ __ ___   ___                    //
//                      / _ \ | __|/ _ \ | '_ ` _ \ / __|                   //
//                     / ___ \| |_| (_) || | | | | |\__ \                   //
//                    /_/   \_\\__|\___/ |_| |_| |_||___/                   //
//                                                                          //
//                                                                          //

//---------------------------------
// INTERNAL ATOM 'HELPER' UTILITIES
//---------------------------------

// the X11 server maintains a global list of atoms based on unique strings.  These are
// useful for inter-application communication, but can rapidly become inefficient when applications
// create large numbers of unique atoms names for their own custom purposes (like the X11 workbench).
// To combat this obvious problem, these next two functions will create application-unique atoms
// when a global atom is not available.  Global atoms are NEVER removed.  Once there, they are there
// until the X11 server is shut down.  For that reason, these functions are really necessary.  It should
// help minimize the resource impact of an X11 workbench toolkit application.

// For more information, see xorg-server source
//   specifically:  Atom MakeAtom(const char *string, unsigned len, Bool makeit)
//   this function is located in dix/atom.c .  It allocates atoms SEQUENTIALLY, beginning with XA_LAST_PREDEFINED+1
//   because the atoms are assigned SEQUENTIALLY, it is possible to pick a "very very big number" as the minimum
//   internal atom's starting point, i.e. WB_INTERNAL_ATOM_MIN_VAL (which is currently FF000000H) which would allow
//   for ~16 million internally-defined atoms.

static volatile WB_UINT32 lInternalAtomSpinner = 0L;
static char **ppInternalAtoms = NULL;  // actual atom value starts with WB_INTERNAL_ATOM_MIN_VAL and is index within this array
static char *pszAtomNames = NULL;
static unsigned int cbAtomNames = 0, cbMaxAtomNames = 0;
static unsigned int nInternalAtoms = 0, nMaxInternalAtoms = 0;

#define INITIAL_INTERNAL_ATOM_SIZE 4096
#define INITIAL_INTERNAL_ATOM_STRING_SIZE 262144

Atom WBGetAtom(Display *pDisplay, const char *szAtomName)
{
Atom aRval;
//char *p1;
void *pTemp;
int iLen;


  if(!szAtomName || !*szAtomName)
  {
    WB_ERROR_PRINT("ERROR:  %s - bad 'szAtomName'\n", __FUNCTION__);

    return None;  // bad parameter
  }

  if(!pDisplay)
  {
    pDisplay = WBGetDefaultDisplay();

    if(!pDisplay)
    {
      WB_ERROR_PRINT("ERROR - %s - no display!\n", __FUNCTION__);

      return None;
    }
  }

  aRval = WBLookupAtom(pDisplay, szAtomName);

  if(aRval != None)
  {
    return aRval;
  }

  // allocate an internal atom

  aRval = None;

  while(WBInterlockedExchange(&lInternalAtomSpinner, 1)) // THIS MUST BE SPIN-LOCKED
  {
    WBDelay(100); // by convention just do THIS
  }

  if(!ppInternalAtoms)
  {
    ppInternalAtoms = (char **)WBAlloc(INITIAL_INTERNAL_ATOM_SIZE);

    if(!ppInternalAtoms)
    {
      WB_ERROR_PRINT("ERROR:  %s - no memory\n", __FUNCTION__);

      goto exit_point;
    }

    nMaxInternalAtoms = INITIAL_INTERNAL_ATOM_SIZE;
    nInternalAtoms = 0; // make sure
  }
  else if((nInternalAtoms + 1) >= nMaxInternalAtoms)
  {
    pTemp = WBReAlloc(ppInternalAtoms, nMaxInternalAtoms + INITIAL_INTERNAL_ATOM_SIZE);
    if(!pTemp)
    {
      WB_ERROR_PRINT("ERROR:  %s - no memory\n", __FUNCTION__);

      goto exit_point;
    }

    ppInternalAtoms = (char **)pTemp;
    nMaxInternalAtoms += INITIAL_INTERNAL_ATOM_SIZE;
  }

  iLen = strlen(szAtomName) + 1; // include the '0' byte at the end

  // now for the names buffer

  if(!pszAtomNames)
  {
    pszAtomNames = WBAlloc(INITIAL_INTERNAL_ATOM_STRING_SIZE);
    if(!pszAtomNames)
    {
      WB_ERROR_PRINT("ERROR:  %s - no memory\n", __FUNCTION__);

      goto exit_point;
    }

    cbMaxAtomNames = INITIAL_INTERNAL_ATOM_STRING_SIZE;
    cbAtomNames = 0; // make sure
  }
  else if((cbAtomNames + iLen + 1) >= cbMaxAtomNames) // not enough room?
  {
    pTemp = WBReAlloc(pszAtomNames, cbMaxAtomNames + INITIAL_INTERNAL_ATOM_STRING_SIZE);
    if(!pTemp)
    {
      WB_ERROR_PRINT("ERROR:  %s - no memory\n", __FUNCTION__);

      goto exit_point;
    }

    pszAtomNames = (char *)pTemp;
    cbMaxAtomNames += INITIAL_INTERNAL_ATOM_STRING_SIZE;
  }

  aRval = (Atom)(nInternalAtoms + WB_INTERNAL_ATOM_MIN_VAL);

  ppInternalAtoms[nInternalAtoms++] = pszAtomNames + cbAtomNames;

  memcpy(pszAtomNames + cbAtomNames, szAtomName, iLen);

  cbAtomNames += iLen;
  pszAtomNames[cbAtomNames] = 0; // by convention


exit_point:

  WBInterlockedExchange(&lInternalAtomSpinner, 0);  // I'm done with it now

  if(aRval == None)
  {
    WB_ERROR_PRINT("ERROR:  %s - could not allocate new atom %u for %s\n", __FUNCTION__, (unsigned int)aRval, szAtomName);
  }
//  else
//  {
//    WB_ERROR_PRINT("TEMPORARY:  %s - allocating new atom %u for %s\n", __FUNCTION__, (unsigned int)aRval, szAtomName);
//  }

  return aRval;
//  aRval = XInternAtom(pDisplay, szAtomName, False); // temporarily, just do this
}

Atom WBLookupAtom(Display *pDisplay, const char *szAtomName)
{
Atom aRval;
unsigned int i1;


  if(!szAtomName || !*szAtomName)
  {
    WB_ERROR_PRINT("ERROR:  %s - bad 'szAtomName'\n", __FUNCTION__);

    return None;  // bad parameter
  }

  if(!pDisplay)
  {
    pDisplay = WBGetDefaultDisplay();
  }


  // look up internal atoms FIRST...

  aRval = None;

  while(WBInterlockedExchange(&lInternalAtomSpinner, 1)) // THIS MUST BE SPIN-LOCKED
  {
    WBDelay(100); // by convention just do THIS
  }

  if(ppInternalAtoms && pszAtomNames && nInternalAtoms > 0)
  {
    // TODO: use some kind of hashing algorithm?  for now, if the list is short enough,
    //       this actually replicates what the X Server does with its own atoms.

    for(i1=0; i1 < nInternalAtoms; i1++)
    {
      if(!strcmp(szAtomName, ppInternalAtoms[i1]))
      {
        aRval = (Atom)(i1 + WB_INTERNAL_ATOM_MIN_VAL);
        break;
      }
    }
  }

  WBInterlockedExchange(&lInternalAtomSpinner, 0);  // I'm done with it now

  if(aRval != None)
  {
//    WB_ERROR_PRINT("TEMPORARY:  %s - found atom %u for %s\n", __FUNCTION__, (unsigned int)aRval, szAtomName);

    return aRval;
  }

  aRval = XInternAtom(pDisplay, szAtomName, True);

  // TODO:  anything else?

  return aRval; // regardless
}

char *WBGetAtomName(Display *pDisplay, Atom aAtom)
{
char *pRval, *pTemp;
unsigned int nAtom;


  if(aAtom == None)
  {
    // NOTE:  this can happen under normal circumstances, so don't make it an error
    //        (especially true for dialog controls without IDs assigned, like static text)

    WB_WARN_PRINT("ERROR:  %s - passed 'None' for aAtom\n", __FUNCTION__);

    return NULL;
  }
  else if((unsigned int)aAtom >= (unsigned int)(WB_INTERNAL_ATOM_MIN_VAL + nInternalAtoms))
  {
    WB_ERROR_PRINT("ERROR:  %s - bad (internal) Atom:  %u (%08xH)\n", __FUNCTION__, (unsigned int)aAtom, (unsigned int)aAtom);

    return NULL;  // bad parameter
  }

  if(!pDisplay)
  {
    pDisplay = WBGetDefaultDisplay();

    if(!pDisplay)
    {
      WB_ERROR_PRINT("ERROR - %s - no display!\n", __FUNCTION__);
      return NULL;
    }
  }

  if((unsigned int)aAtom < WB_INTERNAL_ATOM_MIN_VAL)
  {
    WBSupressErrorOutput();

    pTemp = XGetAtomName(pDisplay, aAtom);

    WBAllowErrorOutput();

    if(pTemp)
    {
      pRval = WBCopyString(pTemp);
      XFree(pTemp);

      return pRval;
    }

    WB_DEBUG_PRINT(DebugLevel_Light,
                   "INFO:  %s - unknown Atom:  %u (%08xH)\n",
                   __FUNCTION__, (unsigned int)aAtom, (unsigned int)aAtom);

    return NULL;
  }

  pRval = NULL;

  while(WBInterlockedExchange(&lInternalAtomSpinner, 1)) // THIS MUST BE SPIN-LOCKED
  {
    WBDelay(100); // by convention just do THIS
  }

  if(ppInternalAtoms && pszAtomNames && nInternalAtoms > 0)
  {
    nAtom = (unsigned int)aAtom - WB_INTERNAL_ATOM_MIN_VAL;

    if(nAtom < nInternalAtoms)
    {
      pRval = WBCopyString(ppInternalAtoms[nAtom]);
    }
  }

  WBInterlockedExchange(&lInternalAtomSpinner, 0);  // I'm done with it now

  if(!pRval)
  {
    WB_DEBUG_PRINT(DebugLevel_Light,
                   "INFO:  %s - atom index %u (%u) not found, %u atoms stored\n", __FUNCTION__,
                   (unsigned int)aAtom, (unsigned int)(aAtom - WB_INTERNAL_ATOM_MIN_VAL),
                   nInternalAtoms);
  }
//  else
//  {
//    WB_ERROR_PRINT("TEMPORARY:  %s - found %s for Atom %u\n", __FUNCTION__, pRval, (unsigned int)aAtom);
//  }

  return pRval;
}




//                                                                          //
//                                           _                              //
//                   __ _  ___   ___   _ __ | |_       _ __                 //
//                  / _` |/ __| / _ \ | '__|| __|     | '__|                //
//                 | (_| |\__ \| (_) || |   | |_      | |                   //
//                  \__, ||___/ \___/ |_|    \__|_____|_|                   //
//                     |_|                      |_____|                     //
//                                                                          //

// ========================================================
// Dealing with a lack of or improperly supported qsort_r()
// ========================================================

#if (!defined(QSORT_R_BSD) && !defined(QSORT_R_GNUC)) || defined(__DOXYGEN__)

struct my_qsort_data
{
  void *pData;  // pointer to elements
  int cbData;   // size of elements
  void *pThunk; // data to pass to each 'compare' call
  int (*compare)(void *, const void *, const void *); // compare function
  void *pSW, *pBR;
};

static void MyQuickSort2(struct my_qsort_data *pData, int iLow, int iHigh);

// define exactly like BSD version, but with base types
// TODO:  multi-thread version?  would need to determine optimum threshold for threading

void my_qsort_r(void *base, int nmemb, int size, void *thunk,
                int (*compar)(void *, const void *, const void *))
{
struct my_qsort_data sData;
unsigned char buf[32], buf2[32];


  if(nmemb <= 1)
  {
    return;  // no need to sort 1 item
  }

  sData.pData = base;
  sData.cbData = size;
  sData.pThunk = thunk;
  sData.compare = compar;

  if(sData.cbData <= sizeof(buf))
  {
    sData.pBR = buf;
    sData.pSW = buf2;
  }
  else
  {
    sData.pBR = WBAlloc(sData.cbData * 2);
    sData.pSW = (unsigned char *)sData.pBR + sData.cbData;
  }

  MyQuickSort2(&sData, 0, nmemb - 1);

  if(sData.cbData > sizeof(buf))
  {
    WBFree(sData.pBR);
  }
}

static __inline__ void *ElementFromIndex(struct my_qsort_data *pData, int iElement)
{
  return ((unsigned char *)pData->pData) + pData->cbData * iElement;
}

static int DoCompareI(struct my_qsort_data *pData, int iLeft, int iRight)
{
  void *p1 = ElementFromIndex(pData, iLeft);
  void *p2 = ElementFromIndex(pData, iRight);

  return pData->compare(pData->pThunk, p1, p2);
}

static int DoCompareP(struct my_qsort_data *pData, int iLeft, void *pRight)
{
  void *p1 = ElementFromIndex(pData, iLeft);

  return pData->compare(pData->pThunk, p1, pRight);
}

static void DoSwapData(struct my_qsort_data *pData, int iLeft, int iRight)
{
  void *p1 = ElementFromIndex(pData, iLeft);
  void *p2 = ElementFromIndex(pData, iRight);

  // TODO:  make this faster?
  memcpy(pData->pSW, p1, pData->cbData);
  memcpy(p1, p2, pData->cbData);
  memcpy(p2, pData->pSW, pData->cbData);
}

void MyQuickSort2(struct my_qsort_data *pData, int iLow, int iHigh )
{
int iUp, iDown, iBreak;
void *pBreak;
unsigned char buf[32], buf2[32]; // if smaller than 32 bytes, use THIS for temp object storage


  if( iLow < iHigh )                 // do not sort 1 element block
  {
    iBreak = (iLow + iHigh) / 2;
    pBreak = ElementFromIndex(pData, iBreak); // initial pivot point

    if( (iHigh - iLow) > 5 )       // 5 or more elements?
    {
      // do a 'median of 3' optimization when practical
      // this ensures a better pivot point, limiting the
      // effect of an already sorted or nearly sorted
      // array on performance.  Pivot points should be
      // as close to the median value as practical for
      // the current range of data points.  Otherwise,
      // a series of bad pivot points could degenerate
      // the 'quicksort' into a 'slowsort', and possibly
      // cause stack overflows on large data sets.

      if(DoCompareI(pData, iLow, iHigh) <= 0)
      {
        if(DoCompareP(pData, iLow, pBreak) < 0)
        {
          if(DoCompareP(pData, iHigh, pBreak) < 0)
          {
             pBreak = ElementFromIndex(pData, iHigh);
          }
        }
        else
        {
          pBreak = ElementFromIndex(pData, iLow);
        }
      }
      else
      {
        if(DoCompareP(pData, iHigh, pBreak) < 0)
        {
          if(DoCompareP(pData, iLow, pBreak) < 0)
          {
             pBreak = ElementFromIndex(pData, iLow);
          }
        }
        else
        {
          pBreak = ElementFromIndex(pData, iHigh);
        }
      }
    }

    memcpy(pData->pBR, pBreak, pData->cbData); // make copy of it before swapping anything
    pBreak = pData->pBR; // and now point to the buffer (faster this way)

    iUp = iLow;                  // initialize indices
    iDown = iHigh;

    do
    {
      // Move in from both sides towards the pivot point.

      // note:  it may be possible to thread THESE two loops
      //        though it's likely not to help a whole lot

      while( iUp < iHigh)
      {
        if(DoCompareP(pData, iUp, pBreak) < 0)
        {
          iUp++;
        }
        else
        {
          break;
        }
      }

      while(iDown > iLow)
      {
        if(DoCompareP(pData, iDown, pBreak) > 0)
        {
          iDown--;
        }
        else
        {
          break;
        }
      }


      // if low/high boundaries have not crossed, swap current
      // 'boundary' values so that the 'iUp' pointer points
      // to a value less than or equal to the pivot point,
      // and the 'iDown' value points to a value greater than
      // or equal to the pivot point, and continue.

      if( iUp <= iDown )
      {
        if(iUp != iDown)
        {
          DoSwapData(pData, iUp, iDown);
        }

        iUp++;
        iDown--;
      }

    } while ( iUp <= iDown );

    // the recursive part... [NOTE if I ever want to thread this, I can make work units here]

    if(iLow < iDown )  // everything to the left of the pivot point
    {
      MyQuickSort2(pData, iLow, iDown );
    }
    if(iUp < iHigh)    // everything to the right of the pivot point
    {
      MyQuickSort2(pData, iUp, iHigh );
    }
  }
}

#endif // !defined(QSORT_R_BSD) && !defined(QSORT_R_GNUC)


#if !defined(HAVE_XPM) || defined(__DOXYGEN__)

// SUBSTITUTE CODE FOR MISSING (or unwanted) libXpm //

// parse an XPM, and generate data that I can THEN create a bitmap from
//
// The XPM will have 4 numbers at the start (in ASCII): WIDTH HEIGHT nColors chars_per_color
// 'nColors' is the size of the color table (one line each)
// 'chars_per_color' is the # of characters that represent a color
// following this is the bitmap data itself.
// To create a transparency mask look for a color called "None" which is the background color
// for the transparency mask.  The mask will be a monochrome bitmap with '0' for transparency,
// and '1' for everything else.
//
// mono bitmap format will be 1 bit per pixel, 16-bit MSB
//
// This function is generally PREFERABLE to the libXpm version as it's a LOT faster
// Additionally, it can be made 'MS Windows Compatible' so that XPM resources can be
// used within WIN32 applications.  Should support MSVC, gcc, and llvm compilers
//
// checking for MSVC:  use '#ifdef _MSC_VER' or similar

#define MAX_XPM_COLOR_CHAR_SIZE 4

typedef struct _MY_XPM_COLOR_
{
  char c[MAX_XPM_COLOR_CHAR_SIZE]; // up to MAX_XPM_COLOR_CHAR_SIZE chars that represent a color (use 8 instead?)
  XColor clrColor; // actual color (32-bit)
} MY_XPM_COLOR;


static int MyXPMColorCompare(const void *p1, const void *p2)
{
  // always 1st 4 characters only

  return memcmp(p1, p2, MAX_XPM_COLOR_CHAR_SIZE);
}

static char * MyXPMToData(const char *pXPM[], int *piW, int *piH, char **ppTransparency)
{
MY_XPM_COLOR *pClr, *pC;
int i1, i2, i3, iW, iH;
int nColors, nCharsPerColor;
char cNone[MAX_XPM_COLOR_CHAR_SIZE]={0};
const char *pX, *pY, *pZ;
const char **ppX;
Colormap colormap;
WB_UINT32 *pRval, *pR;
unsigned char *pT;
char tbuf[256];


  // ------------------
  // parse the XPM file
  // ------------------

  if(pXPM)
  {
    ppX = pXPM; // first line is always 4 numbers
  }
  else
  {
    ppX = NULL;
  }

  if(ppX)
  {
    pX = *(ppX++);
  }
  else
  {
    pX = NULL;
  }

  if(!pX)
  {
    WB_ERROR_PRINT("%s - unexpected parameter, pXPM=%p, ppX=%p, pX=%p\n", __FUNCTION__, pXPM, ppX, pX);
    return NULL;
  }

  // use a macro to grab 4 integers from text

#define NEXT_INT(iW,pX,pY,pZ){int iLen; NEXT_WORD(pX,pY,pZ); \
                              iLen=pZ - pY > sizeof(tbuf) - 1 ? sizeof(tbuf) - 1 : pZ - pY; \
                              if(iLen>0){memcpy(tbuf,pY,iLen);} tbuf[iLen]=0; iW=atoi(tbuf);}
  NEXT_INT(iW,pX,pY,pZ);
  NEXT_INT(iH,pX,pY,pZ);
  NEXT_INT(nColors,pX,pY,pZ);
  NEXT_INT(nCharsPerColor,pX,pY,pZ);

#undef NEXT_INT

  if(*pX || !iW || !iH || !nColors || !nCharsPerColor || nCharsPerColor > sizeof(pClr[0].c))
  {
    WB_ERROR_PRINT("%s fail, iW=%d iH=%d nColors=%d nCharsPerColor=%d\n",
                   __FUNCTION__, iW, iH, nColors, nCharsPerColor);
    return NULL;
  }

  colormap = WBDefaultColormap(WBGetDefaultDisplay());

  pClr = WBAlloc(nColors * sizeof(MY_XPM_COLOR));

  // ------------------------------------------------------------------------------
  // parse the colors - 1-4 chacters, then white space, then the color as '#nnnnnn'
  // ------------------------------------------------------------------------------

  for(i1=0; i1 < nColors; i1++)
  {
    pY = pX = *(ppX++);

    if(!pX)
    {
      WBFree(pClr);

      WB_ERROR_PRINT("%s NULL pX unexpected, i1=%d\n", __FUNCTION__, i1);
      return NULL;
    }

    bzero(pClr[i1].c, sizeof(pClr[i1].c));

    for(i2=0; i2 < nCharsPerColor; i2++)
    {
      pClr[i1].c[i2] = *(pX++);
    }

    while(*pX && *pX <= ' ')
    {
      pX++; // next char should be a 'c'
    }

    // next character is 'c' for color
    if(*pX != 'c' || pX[1] > ' ' || (pX[2] != '#' && strncmp(pX + 2,"None",4)))
    {
      WB_ERROR_PRINT("%s fail 1, pX=\"%s\" pY=\"%s\" %d %c %d\n", __FUNCTION__, pX, pY, pX[1], pX[2], strncmp(pX + 2,"None",4));
      WBFree(pClr);

      return NULL;
    }

    pX += 2;

    if(!strncmp(pX,"None",4))
    {
      memcpy(cNone, pClr[i1].c, sizeof(pClr[i1].c));
      bzero(&(pClr[i1].clrColor), sizeof(XColor));

      pX += 4;
    }
    else if(*pX == '#')
    {
      memcpy(tbuf, pX, 7);
      tbuf[7] = 0;
      XParseColor(WBGetDefaultDisplay(), colormap, tbuf, &(pClr[i1].clrColor));
      pX += 7;
    }
    else
    {
      WB_ERROR_PRINT("%s fail 2, pX=\"%s\"\n", __FUNCTION__, pX);
      WBFree(pClr);
      return NULL;
    }

    if(*pX)
    {
      WB_ERROR_PRINT("%s fail 3, pX=\"%s\"\n", __FUNCTION__, pX);
      WBFree(pClr);
      return NULL;
    }
  }

  // first usage of 'pRval'
  pRval = WBAlloc(iH * iW * 4); // pixel array, always 32-bit-wide values; B is first byte, G is 2nd byte, R is 3rd byte, 4th byte is zero

  if(!pRval)
  {
    WBFree(pClr);
    WB_ERROR_PRINT("%s fail, not enough memory for pRval, size=%d\n", __FUNCTION__, iH * iW * 4);
    return NULL;
  }

  if(ppTransparency && cNone[0]) // there is a 'None'
  {
    i3 = (iW + 7) / 8; // total number of bytes needed per row [padded]
    pT = WBAlloc(iH * i3 + 2);
    if(!pT)
    {
      WBFree(pRval);
      WBFree(pClr);
      WB_ERROR_PRINT("%s fail, not enough memory for pT, size=%d\n", __FUNCTION__, (iH * iW) / 8 + 2);
      return NULL;
    }

    bzero(pT, iH * i3 + 2); // make sure
  }
  else
  {
    pT = NULL;
  }

  qsort(pClr, nColors, sizeof(*pClr), MyXPMColorCompare);

  // at this point 'pX' points to the actual RBG color data.  I shall now create
  // Image binary data in XYPixmap format, 32-bits per pixel with 32-bit padding, based on the default display

  for(i2=0, pR=pRval; i2 < iH; i2++)
  {
    pX = *(ppX++);
    if(!pX)
    {
      WBFree(pRval);
      WBFree(pClr);
      WB_ERROR_PRINT("%s NULL pX unexpected, i2=%d\n", __FUNCTION__, i2);
      return NULL;
    }

    pY = pX;

    for(i1=0; i1 < iW; i1++)
    {
      bzero(tbuf, sizeof(pClr[0].c));

      // read in 'n' characters
      for(i3=0; i3 < nCharsPerColor; i3++)
      {
        if(!*pX)
        {
          WBFree(pClr);
          WB_ERROR_PRINT("%s premature end of string, %ld bytes\n", __FUNCTION__, (long)(pX - pY));
          return NULL;
        }

        tbuf[i3] = *(pX++);
      }

      pC = (MY_XPM_COLOR *)bsearch(tbuf, pClr, nColors, sizeof(*pClr), MyXPMColorCompare);

      if(!pC || memcmp(tbuf, pC->c, sizeof(pC->c)))
      {
        WBFree(pClr);
        WB_ERROR_PRINT("%s fail, did not locate color %-4.4s\n", __FUNCTION__, tbuf);
        return NULL;
      }

      // pixel color order is B, then G, then R so that R == MSB and B == LSB
      // this being 'low endian' might actually matter with the byte order.
      // TODO:  do I verify this using the 'Visual' structure info?  Should I get
      //        the default visual for the default Display+Screen and verify?

      ((unsigned char *)pR)[0] = pC->clrColor.blue >> 8;
      ((unsigned char *)pR)[1] = pC->clrColor.green >> 8;
      ((unsigned char *)pR)[2] = pC->clrColor.red >> 8;   // these are 16-bit values, so I want 8-bits out of them
      ((unsigned char *)pR)[3] = 0;

      pR++;

      if(pT) // bitmap for transparency
      {
        register unsigned int uiBit;
        register unsigned char *pRow;

        // NOTE:  in some test code that was written for VMS, the byte order seems to be
        //        BACKWARDS in a 16-bittedness way.  It may be that the machine in question
        //        used a 16-bit word with byte-order determined by an internal function,
        //        which could cause a 'swap' of each consecutive pair of bytes.  I am going
        //        to IGNORE THAT for the moment and (by experimentation) determine how I'm
        //        supposed to order the bits.
        // TODO:  figure out a system-independent way of doing this that works every time
        //        even if I have to create an image and manipulate pixels individually

        // width in bytes must be a multiple of 8 bits
        i3 = (iW + 7) / 8; // total number of bytes needed per row [padded]

        pRow = pT + i3 * i2; // 'pR' points to the row
        i3 = iW - 1 - i1;
        uiBit = 1 << (i3 & 7);

        if(!memcmp(tbuf, cNone, sizeof(cNone)))
        {
          pRow[i3 / 8] &= ~uiBit; // bit is clear
        }
        else
        {
          pRow[i3 / 8] |= uiBit; // bit is set
        }
      }
    }
  }

  WBFree(pClr);
  pClr = NULL;

  if(ppTransparency)
  {
    *ppTransparency = (char *)pT;
  }

  if(piW)
  {
    *piW = iW;
  }

  if(piH)
  {
    *piH = iH;
  }

  return (char *)pRval;
}


// function body - TODO:  move to pixmap_helper.c instead?
int MyLoadPixmapFromData(Display *pDisplay, Window wID, char *aData[],
                         Pixmap *pPixmap, Pixmap *pMask, XPM_ATTRIBUTES *pAttr)
{
int iW, iH;
char *pTrans = NULL; // transparency data
char *pB;
Pixmap pxImage, pxMask;
int iRval = 0;


  if(pAttr)
  {
    bzero(pAttr, sizeof(XPM_ATTRIBUTES));
  }

  pB = MyXPMToData((const char **)aData, &iW, &iH, &pTrans);

  if(!pB)
  {
    WB_ERROR_PRINT("%s - MyXPMToData failed\n", __FUNCTION__);

    if(pPixmap)
    {
      *pPixmap = None;
    }
    if(pMask)
    {
      *pMask = None;
    }

    return -1;
  }

  if(pTrans && pMask) // there is transparency information - I'll need a transparency mask
  {
    pxMask = XCreatePixmapFromBitmapData(pDisplay, wID, pTrans, iW, iH,
                                         1,//BlackPixel(pDisplay, DefaultScreen(pDisplay)), mask 'allow' foreground = 1
                                         0,//WhitePixel(pDisplay, DefaultScreen(pDisplay)), transparent background = 0
                                         1); // depth of one, always
    WBFree(pTrans);

    if(!pxMask)
    {
      iRval = -2; // sort of error, but do the rest anyway
    }
  }
  else
  {
    pxMask = None; // no mask
  }

  if(pPixmap)
  {
    pxImage = XCreatePixmap(pDisplay, wID, iW, iH, DefaultDepth(pDisplay, DefaultScreen(pDisplay)));

    if(!pxImage)
    {
      WB_ERROR_PRINT("%s - XCreatePixmap failed\n", __FUNCTION__);

      if(pxMask)
      {
        XFreePixmap(pDisplay, pxMask);
        pxMask = None;
      }

      iRval = -1;
    }
    else
    {
      // create an image from the pB data
      XImage *pImage = XCreateImage(pDisplay, DefaultVisual(pDisplay, DefaultScreen(pDisplay)),
                                    DefaultDepth(pDisplay, DefaultScreen(pDisplay)),
                                    ZPixmap,
                                    0,
                                    pB,
                                    iW, iH, 32, iW * 4);

      if(!pImage)
      {
        WB_ERROR_PRINT("%s - XCreateImage failed\n", __FUNCTION__);

        if(pxMask)
        {
          XFreePixmap(pDisplay, pxMask);
          pxMask = None;
        }

        XFreePixmap(pDisplay, pxImage);
        pxImage = None;

        iRval = -1;
      }
      else
      {
        GC gc;
        XGCValues gcv;

        gcv.foreground = BlackPixel(pDisplay, DefaultScreen(pDisplay));
        gcv.background = WhitePixel(pDisplay, DefaultScreen(pDisplay));

        gc = XCreateGC(pDisplay, wID, (GCForeground | GCBackground), &gcv);

        if(gc == None)
        {
          WB_ERROR_PRINT("%s - XCreateGC failed\n", __FUNCTION__);

          if(pxMask)
          {
            XFreePixmap(pDisplay, pxMask);
            pxMask = None;
          }

          XFreePixmap(pDisplay, pxImage);
          pxImage = None;

          iRval = -1;
        }
        else
        {
          // I will need to create a GC
          // TODO:  use WBXPutImage instead?  For now, no.
          XPutImage(pDisplay, pxImage, gc, pImage, 0, 0, 0, 0, iW, iH); // and now I have a copy of it

          if(WB_LIKELY(pImage->data == pB)) // data pointer matches my allocated data 'pB'
          {
            pImage->data = NULL; // MUST do this before calling XDestroyImage - I free pB later
          }

          XFreeGC(pDisplay, gc);
        }

        // TODO:  use WBXDestroyImage instead?  For now, no.
        XDestroyImage(pImage);
      }
    }
  }

  WBFree(pB); // assume it wasn't realloc'd before

  if(pPixmap)
  {
    *pPixmap = pxImage;
  }

  if(pMask)
  {
    *pMask = pxMask;
  }

  if(pAttr)
  {
    pAttr->width = iW;
    pAttr->height = iH;
    pAttr->depth = DefaultDepth(pDisplay, DefaultScreen(pDisplay));
  }

  return iRval;
}







// some code may have been adapted from libXpm source - SEE ORIGINAL COPYRIGHT NOTICE BELOW
// I actually DID re-write it from scratch, after studying their code _AND_ doing a bunch of
// online research for standard X11 documentation, but just in case here's their copyright

/********************** libXpm ORIGINAL SOURCE COPYRIGHT **************************/
/*
 * Copyright (C) 1989-95 GROUPE BULL
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * GROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
 * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * Except as contained in this notice, the name of GROUPE BULL shall not be
 * used in advertising or otherwise to promote the sale, use or other dealings
 * in this Software without prior written authorization from GROUPE BULL.
 */



#endif // !defined(HAVE_XPM)




//                                                                                                               //
//   ____         _    _                              _   _____                         _____  _  _              //
//  |  _ \  __ _ | |_ | |__   ___    __ _  _ __    __| | |_   _|___  _ __ ___   _ __   |  ___|(_)| |  ___  ___   //
//  | |_) |/ _` || __|| '_ \ / __|  / _` || '_ \  / _` |   | | / _ \| '_ ` _ \ | '_ \  | |_   | || | / _ \/ __|  //
//  |  __/| (_| || |_ | | | |\__ \ | (_| || | | || (_| |   | ||  __/| | | | | || |_) | |  _|  | || ||  __/\__ \  //
//  |_|    \__,_| \__||_| |_||___/  \__,_||_| |_| \__,_|   |_| \___||_| |_| |_|| .__/  |_|    |_||_| \___||___/  //
//                                                                             |_|                               //
//                                                                                                               //


// NOTE:  this does NOT canonicalize the path, so '~' and whatnot need
//        to be handled separately
int WBMkDir(const char *szFileName, int flags)
{
int iRval;

  if(!szFileName || !*szFileName)
  {
    return -1; // always an error to create a 'blank' directory
  }

#ifdef WIN32
#error not yet implemented
#else // WIN32

  if(szFileName[0] == '/' && !szFileName[1])
  {
    return 0; // always succeed if attempting to create the root dir
  }

  iRval = mkdir(szFileName, flags); // attempt it
  if(iRval && errno == ENOENT) // need to recursively create it
  {
    char *p1, *p2;
    // remove one element of the path, and recursively attempt to make THAT one

    p1 = WBCopyString(szFileName);
    if(p1)
    {
      p2 = p1 + strlen(p1) - 1;
      if(*p2 == '/') // already?
      {
        p2--;
      }
      while(p2 > p1 && *p2 != '/')
      {
        p2--;
      }

      if(p2 > p1)
      {
        *p2 = 0;
        iRval = WBMkDir(p1, flags);

        if(!iRval) // I was able to create things 'above this'
        {
          iRval = mkdir(szFileName, flags);
        }
      }

      WBFree(p1);
    }
  }
#endif // WIN32

  return iRval;
}

char * WBSearchPath(const char *szFileName)
{
char *pRval = NULL;
const char *p1, *pCur, *pPath;
char *p2;

  if(0 > WBStat(szFileName, NULL)) // file does not exist?
  {
    if(*szFileName == '/') // absolute path
    {
no_stat:
      WB_ERROR_PRINT("%s - File does not exist: \"%s\"\n", __FUNCTION__, szFileName);
      return NULL;
    }

    // check PATH environment variable, and locate first match

    pRval = WBAlloc(2 * PATH_MAX + strlen(szFileName));

    if(pRval)
    {
      pPath = getenv("PATH"); // not malloc'd, but should not modify
      if(pPath)
      {
        pCur = pPath;

        while(*pCur)
        {
          *pRval = 0; // reset

          p1 = pCur;
          while(*p1 && *p1 != ':')
          {
            p1++;
          }

          if((p1 - pCur) + 2 < 2 * PATH_MAX) // only if not a buffer overrun
          {
            // build path name
            memcpy(pRval, pCur, p1 - pCur);

            if(pRval[(p1 - pCur) - 1] != '/')
            {
              pRval[(p1 - pCur)] = '/';
              strcpy(pRval + (p1 - pCur) + 1, szFileName);
            }
            else
            {
              strcpy(pRval + (p1 - pCur), szFileName);
            }

//            fprintf(stderr, "TEMPORARY:  trying \"%s\"\n", pRval);

            if(!WBStat(pRval, NULL))
            {
              return pRval; // FOUND!
            }
          }

          if(*p1)
          {
            p1++;
          }

          pCur = p1;
        }
      }

      pPath = pCur = p1 = NULL; // make sure I NULL them out (prevent pointer re-use)

      // if I get here I should check ONE MORE TIME at the location of X11workbench in case
      // it was installed into a non-standard path someplace and I need one of its utilities

      p2 = WBCopyString(GetStartupAppName());
      if(p2)
      {
        if(*p2 && strlen(p2) < 2 * PATH_MAX) // so I don't overflow
        {
          p1 = strrchr(p2, '/'); // find the last '/'
          if(p1)
          {
            p2[p1 - p2 + 1] = 0; // terminate with 0 byte (p1 is const)
          }
          else
          {
            WBFree(p2);
            p2 = NULL;
          }
        }
        else
        {
          WBFree(p2);
          p2 = NULL;
        }
      }

      p1 = NULL; // prevents pointer re-use

      if(p2)
      {
        strcpy(pRval, p2);         // the path for X11workbench's install directory
        strcat(pRval, szFileName); // use path of X11workbench executable with szFileName
      }
      else // could not find, nor get path info
      {
        WBFree(pRval);
        pRval = NULL;
      }
    }

    if(!pRval || 0 > WBStat(pRval, NULL))
    {
      if(pRval)
      {
        WBFree(pRval);
      }

      goto no_stat;
    }
  }
  else
  {
    pRval = WBCopyString(szFileName); // file exists, so return as-is
  }

  return pRval;
}


char * WBTempFile0(const char *szExt)
{
char *pRval = NULL;
const char *szDir = NULL;
int i1;
WB_FILE_HANDLE h1;
union
{
  WB_UINT64 ullTime;
  unsigned short sA[4];
} uX;
static const char szH[16]="0123456789ABCDEF";


#ifdef WIN32
  // TODO:  the windows code, which uses the TEMP and TMP environment variables as well as the registry
#error windows version not implemented
#else // !WIN32

  // On POSIX systems, first use /var/tmp and if not available, use /tmp

  szDir = "/var/tmp";

  if(0 > WBStat(szDir, NULL))
  {
    szDir = "/tmp";
    if(0 > WBStat(szDir, NULL))
    {
      return NULL; // unable to 'stat' the temp file directory
    }
  }

#endif // !WIN32

  for(i1=0; i1 < 256; i1++) // don't try forever
  {
    pRval = WBCopyString(szDir);

    if(pRval)
    {
#ifdef WIN32
      WBCatString(&pRval, "\\wbtk0000");
#else // !WIN32
      WBCatString(&pRval, "/wbtk0000");
#endif // !WIN32
    }


    uX.ullTime = WBGetTimeIndex();
    uX.sA[0] ^= uX.sA[1];
    uX.sA[0] ^= uX.sA[2];
    uX.sA[0] ^= uX.sA[3];

    if(pRval)
    {
      char *pX = pRval + strlen(pRval) - 4; // point to first '0'

      pX[0] = szH[(uX.sA[0] >> 12) & 0xf];
      pX[1] = szH[(uX.sA[0] >> 8) & 0xf];
      pX[2] = szH[(uX.sA[0] >> 4) & 0xf];
      pX[3] = szH[uX.sA[0] & 0xf];

      if(szExt && *szExt)
      {
        if(*szExt != '.')
        {
          WBCatString(&pRval, ".");
        }
        if(pRval)
        {
          WBCatString(&pRval, szExt);
        }
      }
    }

    if(pRval)
    {
#ifdef WIN32
#error windows code not written yet
#else // !WIN32
      h1 = open(pRval, O_CREAT | O_EXCL | O_RDWR, 0644); // create file, using '644' permissions, fail if exists

      if(h1 < 0) // error
      {
        WBFree(pRval);
        pRval = NULL;

        if(errno == EEXIST)
        {
          WBDelay(499);
          continue; // try again with a different name
        }

        if(errno == ENOTDIR || errno == ENOENT || errno == EACCES ||
           errno == EPERM || errno == EROFS || errno == EMFILE || errno == ENFILE)
        {
          // these errors are fatal, so I exit now
          break;
        }
      }
      else
      {
        close(h1);

        // add this file to the existing list of temp files to be destroyed
        // on exit from the program.

        break; // file name is valid and ready for use
      }
#endif // !WIN32
    }
  }

  return pRval;
}

char * WBTempFile(const char *szExt)
{
char *pRval = WBTempFile0(szExt);

  if(pRval)
  {
    __add_to_temp_file_list(pRval);
  }

  return pRval;
}

static void __add_to_temp_file_list(const char *szFile)
{
int i1 = strlen(szFile);
char *pTemp;

  // TODO:  thread-safe?

  if(!pTempFileList)
  {
    cbTempFileList = PATH_MAX * 256;
    pTempFileList = WBAlloc(cbTempFileList);

    if(!pTempFileList)
    {
      return;
    }

    pTempFileListEnd = pTempFileList;
  }
  else if((pTempFileListEnd - pTempFileList) + i1 + 2 >= cbTempFileList)
  {
    pTemp = WBReAlloc(pTempFileList, cbTempFileList + (128 * PATH_MAX));
    if(!pTemp)
    {
      return;
    }

    cbTempFileList += 128 * PATH_MAX; // using a 'while' loop sanity checks this against i1

    if((pTempFileListEnd - pTempFileList) + i1 + 2 >= cbTempFileList) // sanity check
    {
      return; // don't bother re-allocating, this is probably NOT sane
    }
  }

  memcpy(pTempFileListEnd, szFile, i1);
  pTempFileListEnd += i1;

  *(pTempFileListEnd++) = 0;
  *pTempFileListEnd = 0; // always end with 2 0-bytes, point to 2nd one
}


//                                                                                                                       //
//   _____        _                             _      _                   _  _              _    _                      //
//  | ____|__  __| |_  ___  _ __  _ __    __ _ | |    / \    _ __   _ __  | |(_)  ___  __ _ | |_ (_)  ___   _ __   ___   //
//  |  _|  \ \/ /| __|/ _ \| '__|| '_ \  / _` || |   / _ \  | '_ \ | '_ \ | || | / __|/ _` || __|| | / _ \ | '_ \ / __|  //
//  | |___  >  < | |_|  __/| |   | | | || (_| || |  / ___ \ | |_) || |_) || || || (__| (_| || |_ | || (_) || | | |\__ \  //
//  |_____|/_/\_\ \__|\___||_|   |_| |_| \__,_||_| /_/   \_\| .__/ | .__/ |_||_| \___|\__,_| \__||_| \___/ |_| |_||___/  //
//                                                          |_|    |_|                                                   //
//                                                                                                                       //
//                          _                _   ____                                                                    //
//                         / \    _ __    __| | |  _ \  _ __  ___    ___  ___  ___  ___   ___  ___                       //
//                        / _ \  | '_ \  / _` | | |_) || '__|/ _ \  / __|/ _ \/ __|/ __| / _ \/ __|                      //
//                       / ___ \ | | | || (_| | |  __/ | |  | (_) || (__|  __/\__ \\__ \|  __/\__ \                      //
//                      /_/   \_\|_| |_| \__,_| |_|    |_|   \___/  \___|\___||___/|___/ \___||___/                      //
//                                                                                                                       //

// EXTERNAL APPLICATION EXECUTION

WB_PROCESS_ID WBRunAsyncPipeV(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr,
                              const char *szAppName, va_list va)
{
const char *pArg;//, *pPath;
char *pCur, *p1, *pAppName = NULL;
char **argv;
int i1, nItems, cbItems;
va_list va2;
WB_PROCESS_ID hRval;
WB_FILE_HANDLE hIn, hOut, hErr;


  // NOTE:  to avoid zombies, must assign SIGCHLD to 'SIG_IGN' or process them correctly
  //        (this is done in 'WBInit')

  hIn = hOut = hErr = WB_INVALID_FILE_HANDLE; // by convention (WIN32 needs this anyway)

  // FIRST, locate 'szAppName'

  pAppName = WBSearchPath(szAppName);

//  WB_ERROR_PRINT("TEMPORARY: %s - AppName \"%s\"\n", __FUNCTION__, pAppName);
//
// DEBUG-ONLY code - TODO enable with debug level verbosity > ???
//  {
//    va_copy(va2, va);
//    nItems = 1;
//    while(1)
//    {
//      pArg = va_arg(va2, const char *);
//      if(!pArg)
//      {
//        break;
//      }
//
//      WB_ERROR_PRINT("TEMPORARY: %s -      Arg %d -\"%s\"\n", __FUNCTION__, nItems, pArg);
//      nItems++;
//    }
//  }

  if(hStdIn == WB_INVALID_FILE_HANDLE) // re-dir to/from /dev/null
  {
#ifndef WIN32
    hIn = open("/dev/null", O_RDONLY, 0);
#else // WIN32
    SECURITY_DESCRIPTOR *pSD = (SECURITY_DESCRIPTOR *)WBAlloc(SECURITY_DESCRIPTOR_MIN_LENGTH);

    if(pSD)
    {
      InitializeSecurityDescriptor(pSD,SECURITY_DESCRIPTOR_REVISION);
      pSD->bInheritHandle = TRUE; // what a pain

      hIn = CreateFile("NUL", GENERIC_READ, FILE_SHARE_READ | FILE_SHARE_WRITE,
                       pSD, OPEN_EXISTING, NULL, NULL);
      WBFree(pSD);
    }
#endif // WIN32
  }
  else
  {
#ifndef WIN32
    hIn = dup(hStdIn);
#else // WIN32
    if(!DuplicateHandle(GetCurrentProcess(), hStdIn,
                        GetCurrentProcess(), &hIn, GENERIC_READ,
                        TRUE, 0))
    {
      hIn = WB_INVALID_FILE_HANDLE;
    }
#endif // WIN32
  }

  if(hStdOut == WB_INVALID_FILE_HANDLE) // re-dir to/from /dev/null
  {
#ifndef WIN32
    hOut = open("/dev/null", O_WRONLY, 0);
#else // WIN32
    SECURITY_DESCRIPTOR *pSD = (SECURITY_DESCRIPTOR *)WBAlloc(SECURITY_DESCRIPTOR_MIN_LENGTH);

    if(pSD)
    {
      InitializeSecurityDescriptor(pSD,SECURITY_DESCRIPTOR_REVISION);
      pSD->bInheritHandle = TRUE; // what a pain

      hOut = CreateFile("NUL", GENERIC_WRITE, FILE_SHARE_READ | FILE_SHARE_WRITE,
                        pSD, OPEN_EXISTING, NULL, NULL);

      // ALTERNATE:  use 'SetHandleInformation(hOut, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT)'

      WBFree(pSD);
    }
#endif // WIN32
  }
  else
  {
#ifndef WIN32
    hOut = dup(hStdOut);
#else // WIN32
    if(!DuplicateHandle(GetCurrentProcess(), hStdOut,
                        GetCurrentProcess(), &hOut, GENERIC_WRITE,
                        TRUE, 0))
    {
      hOut = WB_INVALID_FILE_HANDLE;
    }
#endif // WIN32
  }

  if(hStdErr == WB_INVALID_FILE_HANDLE) // re-dir to/from /dev/null
  {
#ifndef WIN32
    hErr = open("/dev/null", O_WRONLY, 0);
#else // WIN32
    SECURITY_DESCRIPTOR *pSD = (SECURITY_DESCRIPTOR *)WBAlloc(SECURITY_DESCRIPTOR_MIN_LENGTH);

    if(pSD)
    {
      InitializeSecurityDescriptor(pSD,SECURITY_DESCRIPTOR_REVISION);
      pSD->bInheritHandle = TRUE; // what a pain

      hErr = CreateFile("NUL", GENERIC_WRITE, FILE_SHARE_READ | FILE_SHARE_WRITE,
                        pSD, OPEN_EXISTING, NULL, NULL);
      WBFree(pSD);
    }
#endif // WIN32
  }
  else
  {
#ifndef WIN32
    hErr = dup(hStdErr);
#else // WIN32
    if(!DuplicateHandle(GetCurrentProcess(), hStdErr,
                        GetCurrentProcess(), &hErr, GENERIC_WRITE,
                        TRUE, 0))
    {
      hErr = WB_INVALID_FILE_HANDLE;
    }
#endif // WIN32
  }

  // if file handle duplication fails, exit now with an error

  if(hIn == WB_INVALID_FILE_HANDLE ||
     hOut == WB_INVALID_FILE_HANDLE ||
     hErr == WB_INVALID_FILE_HANDLE)
  {
//    WB_ERROR_PRINT("TEMPORARY:  %s hIn=%d hOut=%d hErr=%d\n", __FUNCTION__, hIn, hOut, hErr);

    if(hIn != WB_INVALID_FILE_HANDLE)
    {
      close(hIn);
    }
    if(hOut != WB_INVALID_FILE_HANDLE)
    {
      close(hOut);
    }
    if(hErr != WB_INVALID_FILE_HANDLE)
    {
      close(hErr);
    }

    if(pAppName != szAppName)
    {
      WBFree(pAppName);
    }

    return WB_INVALID_FILE_HANDLE;
  }

  // count arguments, determine memory requirement

  nItems = 0;
  cbItems = 2 * sizeof(char *) + strlen(szAppName) + 1;
  va_copy(va2, va);

  while(1)
  {
    pArg = va_arg(va2, const char *);
    if(!pArg)
    {
      break;
    }

    cbItems += strlen(pArg) + 1 + sizeof(char *);
    nItems++;
  }

  argv = (char **)WBAlloc(64 + cbItems);
  if(!argv)
  {
    close(hIn);
    close(hOut);
    close(hErr);

    if(pAppName != szAppName)
    {
      WBFree(pAppName);
    }

//    WB_ERROR_PRINT("TEMPORARY:  %s HERE I AM (1)\n", __FUNCTION__);
    return WB_INVALID_FILE_HANDLE;
  }

  pCur = (char *)(argv + nItems + 2); // enough room for argument pointers

  p1 = strrchr(szAppName, '/');
  if(p1)
  {
    strcpy(pCur, p1 + 1); // just the name
  }
  else
  {
    strcpy(pCur, szAppName);
  }

  argv[0] = pCur;
  pCur += strlen(pCur) + 1;

  for(i1=1; i1 <= nItems; i1++)
  {
    pArg = va_arg(va, const char *);

    strcpy(pCur, pArg);
    argv[i1] = pCur;
    pCur += strlen(pCur) + 1;
  }

  argv[nItems + 1] = NULL;

#ifndef WIN32

  // now that I have a valid 'argv' I can spawn the process.
  // I will return the PID so that the caller can wait on it

  hRval = vfork();

  if(!hRval) // the 'forked' process
  {
    // vfork jumps here FIRST and temporarily suspends the calling thread
    // it also does NOT make a copy of memory so I must treat it as 'read only'

    if(dup2(hIn, 0) != -1 && dup2(hOut, 1) != -1 && dup2(hErr, 2) != -1) // stdin, stdout, stderr
    {
      static const char szMsg[]="ERROR: 'execve()' failure\n";
      extern char **environ; // this is what the man page says to do (it's part of libc)

      // TODO:  customize environment?

      signal(SIGHUP, SIG_IGN); // ignore 'HUP' signal before 'setsid' call ['daemon()' does this]
      setsid(); // so that I am my own process group (NOTE doing this might make it impossible to get the exit status... must verify everywhere)
      signal(SIGHUP, SIG_DFL); // restore default handling of 'HUP' ['daemon()' does this]

      execve(pAppName, argv, environ); // NOTE:  execute clears all existing signal handlers back to 'default' but retains 'ignored' signals

      write(2, szMsg, sizeof(szMsg) - 1); // stderr is still 'the old one' at this point
      fsync(2);

      // TODO:  if execve fails, should I forcibly close the duplicated handles??
//      close(0);
//      close(1);
//      close(2);
    }
    else
    {
      static const char szMsg[]="ERROR: 'dup2()' failure\n";
      write(2, szMsg, sizeof(szMsg) - 1); // stderr is still 'the old one' at this point
    }

    close(hIn); // explicitly close these if I get here
    close(hOut);
    close(hErr);

    _exit(-1); // should never get here, but this must be done if execve fails
  }
//  else if(hRval < 0)
//  {
//    WB_ERROR_PRINT("TEMPORARY:  %s HERE I AM (2) errno=%d\n", __FUNCTION__, errno);
//  }


#else

#error TODO write the WIN32 code for this using ShellExecuteEx or CreateProcess (example below from Setup Gizmo)
#error and pay SPECIFIC ATTENTION to getting the handle re-direction right for the stdin/stdout/stderr so that piping works
#error and don`t forget the registry entries that ShellExecute uses for the PATH (then again...)

// SEE http://msdn.microsoft.com/en-us/library/windows/desktop/ms682499%28v=vs.85%29.aspx
// for creating a child process with re-directed stdin/stdout/stderr

//DWORD RunApplication(LPCSTR szCmdLine, LPCSTR szExecDir,
//                     LPCSTR szAppName, LPCSTR szWindowTitle /* = NULL */)
//{
//  STARTUPINFO si;
//  PROCESS_INFORMATION pi;
//  CString csTemp;
//
//  CString csExecDir = szExecDir;
//
//  if(!csExecDir.GetLength())
//    csExecDir = PathFromCommandLine(szCmdLine);
//
//  memset(&si, 0, sizeof(si));
//  si.cb = sizeof(si);
//
//  si.lpTitle = (LPTSTR)szWindowTitle;
//  si.wShowWindow = SW_SHOWNA;  // show but do not activate it!
//  si.dwFlags = STARTF_USESHOWWINDOW | STARTF_USEPOSITION;
//
//  memset(&pi, 0, sizeof(pi));
//
//  DWORD dwRval = 0;  // non-zero return is an error
//
//
//  UINT uiFlags = CREATE_NEW_PROCESS_GROUP | CREATE_DEFAULT_ERROR_MODE;
//
//  if(GetVersion() & 0x80000000)  // WIN '9x
//  {
//    uiFlags |= CREATE_NEW_CONSOLE;
//  }
//  else
//  {
//    uiFlags |= CREATE_SEPARATE_WOW_VDM;
//  }
//
// NOTE:  assign si.hStdError, si.hStdInput, si.hStdOutput and si.dwFlags |= STARTF_USESTDHANDLES
//        in the STARTUPINFO structure in order to re-direct I/O.  Also the 'inherit' flag must
//        be TRUE (not FALSE as in the example below) for this to work
//
// TODO:  determine correct environment using 'ShellExecute' registry parameters
//
//  if(!CreateProcess(NULL, (LPSTR)szCmdLine, NULL, NULL, FALSE,
//                    uiFlags | NORMAL_PRIORITY_CLASS,
//                    NULL, szExecDir, &si, &pi))
//  {
//    if(pi.hThread)
//      CloseHandle(pi.hThread);
//
//    if(pi.hProcess)
//      CloseHandle(pi.hProcess);
//
//    DWORD dwErr = GetLastError();
//    csTemp.Format(" - error %08xH (%d)", dwErr, dwErr);
//
//    AfxMessageBox("Unable to start "
//                  + (CString)szAppName
//                  + csTemp);
//
//    dwRval = 0xffffffff;
//  }
//  else
//  {
//    // TODO:  do I check an 'abandon me' flag and loop?
//    // TODO:  do I check for a 'WM_QUIT' message?
//
//    while(1)
//    {
//      DWORD dwWait = ::WaitForSingleObject(pi.hProcess, 500);  // 1/2 sec wait
//
//      if(dwWait == WAIT_OBJECT_0)
//        break;
//
//      if(dwWait != WAIT_TIMEOUT)
//      {
//        AfxMessageBox("Process wait failed on " + (CString)szAppName);
//
//        dwRval = 0xffffffff;
//        break;
//      }
//
//      Sleep(50);
//
//      MSG msg;
//      PeekMessage(&msg, NULL, 0, 0, PM_NOREMOVE);  // help 16 bit apps maybe?
//    }
//
//    DWORD dwExit = 0;
//    if(!dwRval && !GetExitCodeProcess(pi.hProcess, &dwExit))
//    {
//      dwRval = 0xffffffff;
//
//      dwExit= GetLastError();
//      csTemp.Format("%ld (%08xH)", dwExit, dwExit);
//
//      AfxMessageBox("Unable to get return code from "
//                    + (CString)szAppName
//                    + ", error code " + csTemp);
//    }
//    else if(dwExit != 0)
//    {
//      CString cs1;
//      cs1.Format("%d", dwExit);
//
//      AfxMessageBox("'" + (CString)szAppName + "' exits with error code " + cs1,
//                    MB_OK | MB_ICONHAND | MB_SETFOREGROUND);
//
//      dwRval = dwExit;
//    }
//  }
//
//  if(pi.hThread)
//    CloseHandle(pi.hThread);
//
//  if(pi.hProcess)
//    CloseHandle(pi.hProcess);
//
//  Sleep(500);  // this helps Win98 systems "not hang"
//
//  return(dwRval);
//}
//
// ** SECONDARY EXAMPLE USING ShellExecuteEx() **
//
//  SHELLEXECUTEINFO sei;
//  memset(&sei, 0, sizeof(sei));
//  sei.cbSize = sizeof(sei);
//  sei.fMask = SEE_MASK_FLAG_NO_UI |  SEE_MASK_NOCLOSEPROCESS;
//  sei.lpFile = csEXE;
//  sei.lpParameters = csParm;
//  sei.nShow = SW_SHOWMAXIMIZED;
//
//  if(!ShellExecuteEx(&sei))
//  {
//    AfxMessageBox("Unable to execute 'MAKECAB' command",
//                  MB_OK | MB_ICONHAND | MB_SETFOREGROUND);
//    return(FALSE);  // failed
//  }
//  else
//  {
//    // wait for process to complete
//    wait.Restore();  // just in case
//
//    WaitForSingleObject(sei.hProcess, INFINITE);
//
//    DWORD dwExitCode;
//    if(!GetExitCodeProcess(sei.hProcess, &dwExitCode))
//    {
//      AfxMessageBox("WARNING:  cannot get exit code from 'MAKECAB'",
//                    MB_OK | MB_ICONHAND | MB_SETFOREGROUND);
//      bWasExeError = TRUE;
//    }
//    else if(dwExitCode == STILL_ACTIVE)
//    {
//      AfxMessageBox("WARNING:  'MAKECAB' process did not terminate",
//                    MB_OK | MB_ICONHAND | MB_SETFOREGROUND);
//      bWasExeError = TRUE;
//    }
//    else if(dwExitCode)
//    {
//      CString cs1;
//      cs1.Format("%d", dwExitCode);
//
//      AfxMessageBox("'MAKECAB' exits with error code " + cs1,
//                    MB_OK | MB_ICONHAND | MB_SETFOREGROUND);
//      bWasExeError = TRUE;
//    }
//  }

#endif // WIN32

  // once I've forked, I don't have to worry about copied memory or shared memory
  // and it's safe to free the allocated 'argv' array.

  WBFree(argv);
  close(hIn);
  close(hOut);
  close(hErr);

  if(pAppName != szAppName)
  {
    WBFree(pAppName);
  }


  return hRval;
}


WB_PROCESS_ID WBRunAsync(const char *szAppName, ...)
{
WB_PROCESS_ID idRval;
va_list va;

  va_start(va, szAppName);

  idRval = WBRunAsyncPipeV(WB_INVALID_FILE_HANDLE, WB_INVALID_FILE_HANDLE,
                           WB_INVALID_FILE_HANDLE, szAppName, va);

  va_end(va);

  if(idRval == WB_INVALID_FILE_HANDLE)
  {
    WB_ERROR_PRINT("Unable to run '%s'\n", szAppName);
  }
//  else
//  {
//    WB_ERROR_PRINT("Running '%s' - pid=%d\n", szAppName, idRval);
//  }

  return idRval;
}

WB_PROCESS_ID WBRunAsyncPipe(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr,
                             const char *szAppName, ...)
{
WB_PROCESS_ID idRval;
va_list va;

  va_start(va, szAppName);

  idRval = WBRunAsyncPipeV(hStdIn, hStdOut, hStdErr, szAppName, va);

  va_end(va);

  return idRval;
}


#define WBRUNRESULT_BUFFER_MINSIZE 65536
#define WBRUNRESULT_BYTES_TO_READ 256

static char * WBRunResultInternal(WB_FILE_HANDLE hStdIn, const char *szAppName, va_list va)
{
WB_PROCESS_ID idRval;
WB_FILE_HANDLE hP[2]; // [0] is read end, [1] is write end
char *p1, *p2, *pRval;
int i1, i2, iStat, iRunning;
unsigned int cbBuf;


  cbBuf = WBRUNRESULT_BUFFER_MINSIZE;
  pRval = WBAlloc(cbBuf);

  if(!pRval)
  {
//    WB_ERROR_PRINT("TEMPORARY:  %s HERE I AM (1) WBAlloc fail %d\n", __FUNCTION__, cbBuf);
    return NULL;
  }

  // use WBRunAsyncPipeV to create a process, with all stdout piped to a char * buffer capture
  // stdin and stderr still piped to/from /dev/null

  // create an anonymous pipe.  pH[0] is the INPUT pipe, pH[1] is the OUTPUT pipe
  // this is important in windows.  for POSIX it doesn't really matter which one you use,
  // but by convention [0] will be input, [1] will be output

  hP[0] = hP[1] = WB_INVALID_FILE_HANDLE;

#ifdef WIN32 /* the WINDOWS way */
  if(!CreatePipe(&(pH[0]), &(pH[1]), NULL, 0))
#else // !WIN32 (everybody else)
  if(0 > pipe(hP))
#endif // WIN32
  {
    WBFree(pRval);
//    WB_ERROR_PRINT("TEMPORARY:  %s HERE I AM (2)\n", __FUNCTION__);
    return NULL;
  }


  idRval = WBRunAsyncPipeV(hStdIn, hP[1], // the 'write' end is passed as stdout
                           WB_INVALID_FILE_HANDLE, szAppName, va);

  if(idRval == WB_INVALID_FILE_HANDLE)
  {
//    WB_ERROR_PRINT("TEMPORARY:  %s failed to run \"%s\" errno=%d\n", __FUNCTION__, szAppName, errno);

    close(hP[0]);
    close(hP[1]);

    return NULL;
  }

  close(hP[1]); // by convention, this will 'widow' the read end of the pipe once the process is done with it

  fcntl(hP[0], F_SETFL, O_NONBLOCK); // set non-blocking I/O

  // so long as the process is alive, read data from the pipe and stuff it into the output buffer
  // (the buffer will need to be reallocated periodically if it fills up)

  p1 = pRval;
  *p1 = 0;       // always do this
  iRunning = 1;  // iRunning will be used as a flag to indicate the process exited.

  while(1)
  {
    i2 = WBRUNRESULT_BYTES_TO_READ; // number of bytes to read at one time
    if((p1 - pRval) + i2 >= cbBuf) // enough room for it?
    {
      i2 = cbBuf - (p1 - pRval);
      if(i2 < WBRUNRESULT_BYTES_TO_READ / 8) // time to re-allocate
      {
        p2 = WBReAlloc(pRval, cbBuf + WBRUNRESULT_BUFFER_MINSIZE / 2);
        if(!p2)
        {
          WBFree(pRval);
          pRval = NULL;

//          WB_ERROR_PRINT("TEMPORARY:  %s HERE I AM (4)\n", __FUNCTION__);
          break;
        }

        cbBuf += WBRUNRESULT_BUFFER_MINSIZE / 2;
        p1 = p2 + (p1 - pRval);
        pRval = p2;
        i2 = WBRUNRESULT_BYTES_TO_READ;
      }
    }

    // if no data available I'll return immediately

    i1 = read(hP[0], p1, i2);

    if(i1 <= 0)
    {
      if(!iRunning)
      {
        if(i1 == 0)
        {
          break; // end of file, process ended, bail out now
        }
//        else // this could be caused by the process forking, and the program failing to run
//        {
//          // TODO:  allow a few retries, then bail??
//
//          break; // for now, bail out on this as well.  should still get "all of it" in the output
//        }
      }

      if(errno == EAGAIN)
      {
        WBDelay(500); // wait 1/2 msec
      }
      else
      {
        break; // an error of some kind, so bail out [pipe closed?]
      }
    }
    else
    {
      p1 += i1; // point past the # of bytes I just read in
      *p1 = 0; // by convention [to make sure the string is ALWAYS terminated with a 0-byte]
    }

    if(iRunning) // only if "still running"
    {
#ifdef WIN32 /* the windows way */
      DWORD dwExitCode;

      if(::WaitForSingleObject(idRval, 5) != WAIT_TIMEOUT)
      {
        if(!GetExitCodeProcess(hProcess, &dwExitCode) ||
           dwExitCode != STILL_ACTIVE)
        {
          iRunning = 0; // my flag that it's not running

          Sleep(5);
          break;
        }
        else // if(dwExitCode == STILL_ACTIVE)
        {
          Sleep(1); // lose time slice, continue loop
        }
      }
#else // !WIN32 (everybody else)
      // for waitpid(), if WNOHANG is specified and there are no stopped, continued or exited children, 0 is returned

      if(waitpid(idRval, &iStat, WNOHANG) && // note this might return non-zero for stopped or continued processes
         WIFEXITED(iStat))                   // so test if process exits also.
      {
        iRunning = 0; // my flag that it's not running
        WBDelay(5000); // wait for a bit to make sure the I/O completes
      }
      else
      {
        WBDelay(500); // so I don't 'spin'
      }
#endif // WIN32
    }
  }

  // always kill the process at this point (in case there was an error)

  kill(idRval, SIGKILL); // not so nice way but oh well
  WBDelay(5000); // wait 5msec

  close(hP[0]); // done with the pipe - close it now

//  WB_ERROR_PRINT("TEMPORARY:  %s HERE I AM (4) pRval=%p *pRval=%c\n", __FUNCTION__, pRval, (char)(pRval ? *pRval : 0));

  return pRval;
}

int WBGetProcessState(WB_PROCESS_ID idProcess, WB_INT32 *pExitCode)
{
#ifdef WIN32 /* the windows way */
  DWORD dwExitCode;

  if(::WaitForSingleObject(idRval, 5) != WAIT_TIMEOUT)
  {
    if(!GetExitCodeProcess(hProcess, &dwExitCode) ||
       dwExitCode != STILL_ACTIVE)
    {
      if(pExitCode)
      {
        *pExitCode = (WB_INT32)dwExitCode;
      }

      return 0; //
    }
  }

  return 1; // still running
#else // !WIN32 (everybody else)
  int iStat, iRval;

  // for waitpid(), if WNOHANG is specified and there are no stopped, continued or exited children, 0 is returned

  iStat = 0;

  iRval = waitpid(idProcess, &iStat, WNOHANG); // note this might return non-zero for stopped or continued processes

  if(iRval > 0 && (iRval == (int)idProcess || (int)idProcess == -1 || (int)idProcess == 0))
  {
    if(WIFEXITED(iStat))                   // test if process exits also.
    {
      if(pExitCode)
      {
        *pExitCode = (WB_INT32)WEXITSTATUS(iStat);
      }

      return 0; // not running
    }

    return 1; // still running
  }

  if(iRval > 0)
  {
    WB_ERROR_PRINT("ERROR:  %s - waitpid returns %d, but does not match %d\n",
                   __FUNCTION__, iRval, (int)idProcess);
  }

  return -1; // error
#endif // WIN32
}

char *WBRunResult(const char *szAppName, ...)
{
char *pRval;
va_list va;


  va_start(va, szAppName);

  pRval = WBRunResultInternal(WB_INVALID_FILE_HANDLE, szAppName, va);

  va_end(va);

  return pRval;
}



char *WBRunResultWithInput(const char *szStdInBuf, const char *szAppName, ...)
{
char *pRval, *pTemp = NULL;
va_list va;
WB_FILE_HANDLE hIn = WB_INVALID_FILE_HANDLE;


  va_start(va, szAppName);

  if(szStdInBuf && *szStdInBuf)
  {
#ifdef WIN32
    DWORD dw1;
#endif // WIN32
    unsigned int nLen = strlen(szStdInBuf);

    pTemp = WBTempFile0(".tmp");

    if(!pTemp)
    {
//      WB_ERROR_PRINT("TEMPORARY:  %s HERE I AM (1)\n", __FUNCTION__);

      va_end(va);
      return NULL;
    }

#ifdef WIN32
    hIn = CreateFile(pTemp, GENERIC_READ | GENERIC_WRITE, FILE_SHARE_READ | FILE_SHARE_WRITE,
                     NULL, OPEN_EXISTING, NULL, NULL);

    if(hIn == WB_INVALID_FILE_HANDLE)
#else // WIN32
    hIn = open(pTemp, O_RDWR, 0);

    if(hIn < 0)
#endif // WIN32
    {
bad_file:
#ifdef WIN32
      DeleteFile(pTemp);
#else // WIN32
      unlink(pTemp);
#endif // WIN32
      WBFree(pTemp);

//      WB_ERROR_PRINT("TEMPORARY:  %s HERE I AM (2)\n", __FUNCTION__);

      va_end(va);
      return NULL;
    }

#ifdef WIN32
    if(!WriteFile(hIn, szStdInBuf, nLen, &dw1, NULL)
       || dw1 != nLen)
    {
      CloseHandle(hIn);
      goto bad_file;
    }

    SetFilePointer(hIn, 0, NULL, FILE_BEGIN); // rewind file
#else // WIN32
    if(write(hIn, szStdInBuf, nLen) != nLen)
    {
      close(hIn);
      goto bad_file;
    }

    lseek(hIn, 0, SEEK_SET); // rewind file
#endif // WIN32

//    WB_ERROR_PRINT("TEMPORARY:  %s HERE I AM (3) temp file \"%s\"\n", __FUNCTION__, pTemp);
  }

  pRval = WBRunResultInternal(hIn, szAppName, va);

  va_end(va);

  if(pTemp)
  {
#ifdef WIN32
    CloseHandle(hIn);
    DeleteFile(pTemp);
#else // WIN32
    close(hIn);
    unlink(pTemp);
#endif // WIN32

    WBFree(pTemp);
  }

  return pRval;
}


//                                                                                      //
//   ____   _                            _   _      _  _                                //
//  / ___| | |__    __ _  _ __  ___   __| | | |    (_)| |__   _ __  __ _  _ __  _   _   //
//  \___ \ | '_ \  / _` || '__|/ _ \ / _` | | |    | || '_ \ | '__|/ _` || '__|| | | |  //
//   ___) || | | || (_| || |  |  __/| (_| | | |___ | || |_) || |  | (_| || |   | |_| |  //
//  |____/ |_| |_| \__,_||_|   \___| \__,_| |_____||_||_.__/ |_|   \__,_||_|    \__, |  //
//                                                                              |___/   //
//                                                                                      //

#ifdef WIN32

WB_MODULE WBLoadLibrary(const char * szModuleName)
{
  return((WB_MODULE)LoadLibrary(szModuleName));
}

void WBFreeLibrary(WB_MODULE hModule)
{
  FreeLibrary(hModule);
}

WB_PROCADDRESS WBGetProcAddress(WB_MODULE hModule, const char *szProcName)
{
  return((WB_PROCADDRESS)GetProcAddress(hModule, szProcName));
}

void * WBGetDataAddress(WB_MODULE hModule, const char *szDataName)
{
  return((void *)GetProcAddress(hModule, szDataName));
}

#else  // POSIX

WB_MODULE WBLoadLibrary(const char * szModuleName)
{
  return((WB_MODULE)dlopen(szModuleName, RTLD_LAZY | RTLD_LOCAL));
}

void WBFreeLibrary(WB_MODULE hModule)
{
  dlclose(hModule);
}

WB_PROCADDRESS WBGetProcAddress(WB_MODULE hModule, const char *szProcName)
{
// freebsd has the 'dlfunc' API, which is basically 'dlsym' cast to a function pointer
#ifdef __FreeBSD__
  return((WB_PROCADDRESS)dlfunc(hModule, szProcName));
#else // other POSIX systems - TODO, check for 'dlfunc' instead of the OS
  return((WB_PROCADDRESS)dlsym(hModule, szProcName));
#endif // 'dlfunc' check
}

void * WBGetDataAddress(WB_MODULE hModule, const char *szDataName)
{
  return((void *)dlsym(hModule, szDataName));
}


#endif // POSIX, WIN32

//                                                                                          //
//   _____  _                            _   ____                                     _     //
//  |_   _|| |__   _ __  ___   __ _   __| | / ___|  _   _  _ __   _ __    ___   _ __ | |_   //
//    | |  | '_ \ | '__|/ _ \ / _` | / _` | \___ \ | | | || '_ \ | '_ \  / _ \ | '__|| __|  //
//    | |  | | | || |  |  __/| (_| || (_| |  ___) || |_| || |_) || |_) || (_) || |   | |_   //
//    |_|  |_| |_||_|   \___| \__,_| \__,_| |____/  \__,_|| .__/ | .__/  \___/ |_|    \__|  //
//                                                        |_|    |_|                        //
//                                                                                          //



WB_THREAD_KEY WBThreadAllocLocal(void)
{
WB_THREAD_KEY keyRval;
#ifdef WIN32
#else  // WIN23
  if(!pthread_key_create(&keyRval, NULL))
  {
    return keyRval;
  }

  return (WB_THREAD_KEY)INVALID_HANDLE_VALUE;
#endif // WIN32
}

void WBThreadFreeLocal(WB_THREAD_KEY keyVal)
{
#ifdef WIN32
#else  // WIN23
  pthread_key_delete(keyVal); // TODO:  check return?
#endif // WIN32
}

void * WBThreadGetLocal(WB_THREAD_KEY keyVal)
{
#ifdef WIN32
#else  // WIN23
  return pthread_getspecific(keyVal);
#endif // WIN32
}

void WBThreadSetLocal(WB_THREAD_KEY keyVal, void *pValue)
{
#ifdef WIN32
#else  // WIN23
  pthread_setspecific(keyVal, pValue);
#endif // WIN32
}

WB_THREAD WBThreadGetCurrent(void)
{
#ifdef WIN32
#else  // WIN23
  return pthread_self();
#endif // WIN32
}


#if 0 /* this code reserved for future use - implement it or remove it */

#ifdef WIN32

// special WIN32 version of it

#else // WIN32

// call my own thread proc that calls the user thread proc
// which lets me set some stuff up.  this will require a locked
// set of buffers for that purpose.  This sets them up.

WB_THREAD_PARM
{
  WB_THREAD_PARM *pNext;

  void *(*function)(void *);
  void *pParam;
};


volatile unsigned int dwThreadParmSpinLock = 0; // spinlock on THIS using WBInterlockedExchange

WB_THREAD_PARM aTP[16] =
{
  { &(aTP[1]), NULL, 0 }, // this initializer creates a 'chain'
  { &(aTP[2]), NULL, 0 },
  { &(aTP[3]), NULL, 0 },
  { &(aTP[4]), NULL, 0 },
  { &(aTP[5]), NULL, 0 },
  { &(aTP[6]), NULL, 0 },
  { &(aTP[7]), NULL, 0 },
  { &(aTP[8]), NULL, 0 },
  { &(aTP[9]), NULL, 0 },
  { &(aTP[19]), NULL, 0 },
  { &(aTP[11]), NULL, 0 },
  { &(aTP[12]), NULL, 0 },
  { &(aTP[13]), NULL, 0 },
  { &(aTP[14]), NULL, 0 },
  { &(aTP[15]), NULL, 0 },
  { NULL, NULL, 0 }
};

WB_THREAD_PARM *pTPHead = &(aTP[0]); // the head of the 'free' list

static void *WBInternalThreadProc(void *pParam)
{
void *pRval = NULL;
WB_THREAD_PARM *pParm = (WB_THREAD_PARM *)pParam;
void *(*function2)(void *);
void *pParam2;


  if(!pParam)
  {
    return NULL;
  }

  function2 = pParm->function;
  pParam2 = pParm->pParam;

  // do a spinlock, rather than owning a global mutex
  while(WBInterlockedExchange(&dwThreadParmSpinLock, 1))
  {
    WBDelay(100);
  }

  // spin lock ok, mess with aTP

  pParm->pNext = pTPHead; // place this entry at the beginning of the free list
  pTPHead = pParm;

  WBInterlockedExchange(&dwThreadParmSpinLock, 0); // un-spin-lock

  if(function2)
  {
    signal(SIGTSTP,SIG_IGN); // thread ignores the signal

    pRval = function2(pParam2);
  }

  return pRval;
}

#endif // 0

#endif // !WIN32



WB_THREAD WBThreadCreate(void *(*function)(void *), void *pParam)
{
#ifdef WIN32
#else  // WIN23
  WB_THREAD thrdRval = (WB_THREAD)INVALID_HANDLE_VALUE;

  // TODO:  call my own thread startup proc, passing a struct that contains
  //        'function' and 'pParam' as the param.  use a linked list of
  //        pre-allocated buffers for that.
  // see possible implementation, above

  if(!pthread_create(&thrdRval, NULL, function, pParam))
  {
    return thrdRval;
  }

  return (WB_THREAD)INVALID_HANDLE_VALUE;
#endif // WIN32
}

void *WBThreadWait(WB_THREAD hThread)        // closes hThread, returns exit code, waits for thread to terminate (blocks)
{
#ifdef WIN32
#else  // WIN23
void *pRval = NULL;

  if(pthread_join(hThread, &pRval))
  {
    // TODO:  error return??
    pRval = (void *)-1;
  }

  return pRval;
#endif // WIN32
}

int WBThreadRunning(WB_THREAD hThread)        // >0 if thread is running, <0 error - use 'pthread_kill(thread,0)' which returns ESRCH if terminated i.e. 'PS_DEAD'
{
#ifdef WIN32
  DWORD dwRval = WaitForSingleObject(hThread, 0);
  if(dwRval == WAIT_OBJECT_0) // still running?
  {
    return 0; // nope the thread terminated
  }
  else if(dwRval == WAIT_TIMEOUT)
  {
    return 1; // still running
  }
  else
  {
    return -1; // an error
  }
#else  // WIN23
  int iR = pthread_kill(hThread,0);

  if(!iR)
  {
    return 1; // no signal sent, handle is valid (and did not exit)
  }

  if(iR == ESRCH)
  {
    return 0; // for now, allow this to indicate 'done'
  }

  return -1;
#endif // WIN32
}

void WBThreadExit(void *pRval)
{
#ifdef WIN32
#else  // WIN23
  pthread_exit(pRval);
#endif // WIN32
}

void WBThreadClose(WB_THREAD hThread)
{
#ifdef WIN32
  CloseHandle(hThread);
#else  // WIN23
  pthread_detach(hThread);
#endif // WIN32
}



//                                                                                                                               //
//    ____                   _  _  _    _                         _                _   __  __         _                          //
//   / ___| ___   _ __    __| |(_)| |_ (_)  ___   _ __   ___     / \    _ __    __| | |  \/  | _   _ | |_  ___ __  __ ___  ___   //
//  | |    / _ \ | '_ \  / _` || || __|| | / _ \ | '_ \ / __|   / _ \  | '_ \  / _` | | |\/| || | | || __|/ _ \\ \/ // _ \/ __|  //
//  | |___| (_) || | | || (_| || || |_ | || (_) || | | |\__ \  / ___ \ | | | || (_| | | |  | || |_| || |_|  __/ >  <|  __/\__ \  //
//   \____|\___/ |_| |_| \__,_||_| \__||_| \___/ |_| |_||___/ /_/   \_\|_| |_| \__,_| |_|  |_| \__,_| \__|\___|/_/\_\\___||___/  //
//                                                                                                                               //
//                                                                                                                               //

int WBCondCreate(WB_COND *pCond)
{
int iRval = -1;

  if(pCond)
  {
#ifdef WIN32
    // because of problems under Windows, this will be defined as 'unsigned int'
    // and I'll use the increment/decrement interlock functions and wait loops to
    // monitor the signaling.

    *pCond = 0;

    iRval = 0; // success!
#else  // WIN23
//    pthread_condattr_t attr;
//    iRval = pthread_condattr_init(&attr);
//
//    if(!iRval)
//    {
//      pthread_condattr_setclock(&attr, CLOCK_REALTIME); // *MUST* use *THIS* one
//      pthread_condattr_setpshared(&attr, PTHREAD_PROCESS_PRIVATE);
//
//      iRval = pthread_cond_init(pCond, &attr);
//
//      pthread_condattr_destroy(&attr);
//    }

    // note:  Implementing with 'interlock' in POSIX as well

    *pCond = 0;

    iRval = 0; // success!
#endif // WIN32
  }

  return iRval;
}

int WBMutexCreate(WB_MUTEX *pMtx)
{
  if(pMtx)
  {
#ifdef WIN32
#else  // WIN23
    if(!pthread_mutex_init(pMtx, NULL))
    {
      return 0;
    }
#endif // WIN32
  }

  return -1;
}


void WBCondFree(WB_COND *pCond)
{
#ifdef WIN32
//  CloseHandle(*pCond);
  if(pCond)
  {
    *pCond = 1; // forces a waiting thread to signal (though only one will probably do it)
  }
#else  // WIN23
  if(pCond)
  {
//    pthread_cond_destroy(pCond);

    // because of problems under Windows, this will be defined as 'unsigned int'
    // and I'll use the increment/decrement interlock functions and wait loops to
    // monitor the signaling.

    *pCond = 1; // forces a waiting thread to signal (though only one will probably do it)
  }
#endif // WIN32
}

void WBMutexFree(WB_MUTEX *pMtx)
{
#ifdef WIN32
  CloseHandle(*pMtx);
#else  // WIN23
  pthread_mutex_destroy(pMtx);
#endif // WIN32
}

int WBMutexLock(WB_MUTEX *pMtx, int nTimeout)
{
int iRval;
#ifdef WIN32
#else  // WIN23
WB_UINT64 ullTime = WBGetTimeIndex(); // current time index in microseconds
WB_UINT64 ullTemp;

  if(nTimeout < 0)
  {
    iRval = pthread_mutex_lock(pMtx);

    return iRval ? -1 : 0; // either an error, or success [but never a timeout]
  }

  while(1)
  {
    iRval = pthread_mutex_trylock(pMtx);

    if(!iRval)
    {
      return 0;
    }
    else if(iRval != EBUSY)
    {
      return -1; // an error
    }

    ullTemp = WBGetTimeIndex(); // TODO:  use clock_gettime instead?

    if((ullTemp - ullTime) > nTimeout)
    {
      return 1; // timed out
    }

    WBDelay(83 + (ullTemp / 13) % 37); // sleep a 'sort of' random wait time
  }
#endif // WIN32

  return -1; // should never get here
}

int WBMutexUnlock(WB_MUTEX *pMtx)
{
#ifdef WIN32
#else  // WIN23
  return pthread_mutex_unlock(pMtx);
#endif // WIN32
}


int WBCondSignal(WB_COND *pCond)
{
//#ifdef WIN32
//#else  // WIN23
//  return pthread_cond_signal(pCond);

  if(pCond)
  {
    WBInterlockedExchange(pCond, 1); // assign to 1 [this is my trigger]
    return 0;
  }
//#endif // WIN32

  return -1;
}

int WBCondWait(WB_COND *pCond, int nTimeout)
{
int iRval = -1;
//#ifdef WIN32
//#else  // WIN23
//WB_MUTEX xMtx;
//
//  if(WBMutexCreate(&xMtx)) // needed by call to pthread_cond_timedwait
//  {
//    return -1; // wait fail
//  }
//
//  WBMutexLock(&xMtx, 0); // should lock immediately as I just created it
//
//  iRval = WBCondWaitMutex(pCond, &xMtx, nTimeout);
//
//  WBMutexUnlock(&xMtx);
//  WBMutexFree(&xMtx);
//
//  return iRval;

  if(!pCond)
  {
    WB_ERROR_PRINT("TEMPORARY: %s - returns -1 (NULL pCond)\n", __FUNCTION__);

    return -1;
  }

  if(nTimeout >= 0)
  {
    struct timespec ts, tsNow;

    clock_gettime(CLOCK_REALTIME, &ts);

    ts.tv_sec += nTimeout / 1000000;
    ts.tv_nsec += (nTimeout % 1000000) * 1000L;

    if(ts.tv_nsec > 1000000000L)
    {
      ts.tv_sec++;
      ts.tv_nsec -= 1000000000L;
    }

    iRval = 0;

    while(!WBInterlockedExchange(pCond, 0)) // if return is zero, it wasn't 'signaled'
    {
      clock_gettime(CLOCK_REALTIME, &tsNow);

      if(tsNow.tv_sec > ts.tv_sec ||
         (tsNow.tv_sec == ts.tv_sec &&
          tsNow.tv_nsec > ts.tv_nsec))
      {
        iRval = ETIMEDOUT; // timeout error
        break;
      }

      WBDelay(37 + tsNow.tv_nsec % 29); // a slightly random ~0.05 msec delay
    }
  }
  else
  {
    while(!WBInterlockedExchange(pCond, 0)) // if return is zero, it wasn't 'signaled'
    {
      WBDelay(100); // for now, it's the same time period (TODO:  adjust like above?)
    }
  }

//#endif // WIN32

  return iRval;
}

int WBCondWaitMutex(WB_COND *pCond, WB_MUTEX *pMtx, int nTimeout)
{
int iRval = -1;
#ifdef WIN32
#else  // WIN23

//  WB_ERROR_PRINT("TEMPORARY: %s - here I am\n", __FUNCTION__);

  if(!pCond || !pMtx)
  {
    WB_ERROR_PRINT("ERROR: %s - returns -1 (NULL pCond)\n", __FUNCTION__);

    return -1;
  }

//  if(nTimeout >= 0)
//  {
//    struct timespec ts;
//
//    clock_gettime(CLOCK_REALTIME, &ts);
//
//    ts.tv_sec += nTimeout / 1000000;
//    ts.tv_nsec += (nTimeout % 1000000) * 1000L;
//
//    if(ts.tv_nsec > 1000000000L)
//    {
//      ts.tv_sec++;
//      ts.tv_nsec -= 1000000000L;
//    }
//
//    iRval = pthread_cond_timedwait(pCond, pMtx, &ts);
//  }
//  else
//  {
//    iRval = pthread_cond_wait(pCond, pMtx);  // 'infinite wait' version
//  }
//
//  if(iRval)
//  {
//    // make sure mutex is owned - some indication is that on timeout that
//    // pthread_cond_timedwait may NOT re-own the mutex!  or same on error...?
//
//    WBMutexUnlock(pMtx); // in case it IS locked
//    WBMutexLock(pMtx, -1); // then re-lock it again [bug workaround]
//
//    if(nTimeout >= 0 && iRval == ETIMEDOUT) // timeout
//    {
//      return 1; // indicate 'timeout' but not error
//    }
//    else
//    {
//      return -1;
//    }
//  }

  WBMutexUnlock(pMtx);

  iRval = WBCondWait(pCond, nTimeout);

  WBMutexLock(pMtx, -1); // this is a safe way of replicating the behavior [wait infinitely on mutex]

#endif // WIN32

  return iRval;
}


unsigned int WBInterlockedDecrement(volatile unsigned int *pValue)
{
#ifdef WIN32
  return InterlockedDecrement(pValue);
#else // !WIN32
unsigned int iRval;

  pthread_rwlock_wrlock(&xInterlockedRWLock);

  (*pValue)++;
  iRval = *pValue;

  pthread_rwlock_unlock(&xInterlockedRWLock);

  return iRval;
#endif // WIN32
}

unsigned int WBInterlockedIncrement(volatile unsigned int *pValue)
{
#ifdef WIN32
  return InterlockedIncrement(pValue);
#else // !WIN32
unsigned int iRval;

  pthread_rwlock_wrlock(&xInterlockedRWLock);

  (*pValue)++;
  iRval = *pValue;

  pthread_rwlock_unlock(&xInterlockedRWLock);

  return iRval;
#endif // WIN32
}

unsigned int WBInterlockedExchange(volatile unsigned int *pValue, unsigned int nNewVal)
{
#ifdef WIN32
  return InterlockedExchange(pValue, nNewVal); // pretty sure this is right...
#else // !WIN32
unsigned int iRval;

  pthread_rwlock_wrlock(&xInterlockedRWLock);

  iRval = *pValue;
  *pValue = nNewVal;

  pthread_rwlock_unlock(&xInterlockedRWLock);

  return iRval;
}

unsigned int WBInterlockedRead(volatile unsigned int *pValue)
{
#ifdef WIN32
  return *pValue; // for now; later, there might be a better way
#else // !WIN32
unsigned int iRval;

  pthread_rwlock_rdlock(&xInterlockedRWLock); // this only does a read lock

  iRval = *pValue;

  pthread_rwlock_unlock(&xInterlockedRWLock);

  return iRval;
#endif // WIN32
}




//   ____  ____  ___ _   _ _____ ___ _   _  ____    //
//  |  _ \|  _ \|_ _| \ | |_   _|_ _| \ | |/ ___|   //
//  | |_) | |_) || ||  \| | | |  | ||  \| | |  _    //
//  |  __/|  _ < | || |\  | | |  | || |\  | |_| |   //
//  |_|   |_| \_\___|_| \_| |_| |___|_| \_|\____|   //
//                                                  //

int WBPrintPostScriptFile(const char *szPrinterName, const char *szFileName)
{
// use 'lpr-cups' if present; /usr/local/bin/lpr if present; then 'lpr'.
// search order will be /usr/local/bin /usr/local/sbin /usr/bin /usr/sbin /bin /sbin for 'lpr'
// prioritize this against the results using 'PATH'.  user might want something else...
// (examples might be a lack of 'sbin' in PATH, or specifying system before local)
// alternately COULD use 'which' output if 'which' is present.

// typical command line will be 'lpr -P"printer name" filename'

// TODO: postscript to binary-format conversion using 'ghostscript'

// TODO:  check for presence of cups, get printer caps, specify more information on 'lpr' command

// TODO:  use 'internet print protocol' to localhost:631/printers/printername


// for Win32, might need to write a simple postscript renderer onto a printer display surface...


  return -1; // error (for now)
}

char *WBGetPrinterList(void)
{
  // open 'printcap' and list the entries

  // TODO: check for presence of cups web interface, request printer list "somehow"
  //       from there, I can grab individual printers' capabilities once I have their names

  // TODO:  for Win32 generate the list via shell APIs

  // TODO:  a 'select printer' dialog box that's standardized for all platforms


  return NULL; // for now
}

#endif // WIN32,POSIX