X11workbench Toolkit  1.0
platform_helper.h
Go to the documentation of this file.
1 // _ _ __ _ _ _ //
3 // _ __ | | __ _ | |_ / _| ___ _ __ _ __ ___ | |__ ___ | | _ __ ___ _ __ | |__ //
4 // | '_ \ | | / _` || __|| |_ / _ \ | '__|| '_ ` _ \ | '_ \ / _ \| || '_ \ / _ \| '__|| '_ \ //
5 // | |_) || || (_| || |_ | _|| (_) || | | | | | | | | | | || __/| || |_) || __/| | _ | | | | //
6 // | .__/ |_| \__,_| \__||_| \___/ |_| |_| |_| |_|_____|_| |_| \___||_|| .__/ \___||_|(_)|_| |_| //
7 // |_| |_____| |_| //
8 // //
9 // Copyright (c) 2010-2017 by 'Big Bad Bombastic Bob' Frazier - all rights reserved. //
10 // You may use this file in any way you see fit provided that any copy or derived work //
11 // includes the above copyright notice. //
12 // //
13 // This header contains platform-specific definitions that rectify various issues. //
14 // It also contains a lot of the 'core' functionality for strings, startup, etc. //
15 // //
17 
18 /*****************************************************************************
19 
20  X11workbench - X11 programmer's 'work bench' application and toolkit
21  Copyright (c) 2010-2018 by Bob Frazier (aka 'Big Bad Bombastic Bob')
22  all rights reserved
23 
24  DISCLAIMER: The X11workbench application and toolkit software are supplied
25  'as-is', with no warranties, either implied or explicit.
26  Any claims to alleged functionality or features should be
27  considered 'preliminary', and might not function as advertised.
28 
29  BSD-like license:
30 
31  There is no restriction as to what you can do with this software, so long
32  as you include the above copyright notice and DISCLAIMER for any distributed
33  work that is equal to or derived from this one, along with this paragraph
34  that explains the terms of the license if the source is also being made
35  available. A "derived work" describes a work that uses a significant portion
36  of the source files or algorithms that are included with this one.
37  Specifically excluded from this are files that were generated by the software,
38  or anything that is included with the software that is part of another package
39  (such as files that were created or added during the 'configure' process).
40  Specifically included is the use of part or all of any of the X11 workbench
41  toolkit source or header files in your distributed application. If you do not
42  ship the source, the above copyright statement is still required to be placed
43  in a reasonably prominent place, such as documentation, splash screens, and/or
44  'about the application' dialog boxes.
45 
46  Use and distribution are in accordance with GPL, LGPL, and/or the above
47  BSD-like license. See COPYING and README files for more information.
48 
49 
50  Additional information at http://sourceforge.net/projects/X11workbench
51 
52 ******************************************************************************/
53 
64 #ifndef _PLATFORM_HELPER_H_INCLUDED_
65 #define _PLATFORM_HELPER_H_INCLUDED_
66 
67 #include <stdarg.h> /* stdarg to make sure I have va_list and other important stuff */
68 #include <stdint.h> /* for standard integer types like uint32_t */
69 
70 // X11 header files (TODO: use 'ifdef' blocks around this as needed for non-X platforms)
71 
72 #include <X11/Xlib.h>
73 #include <X11/Xutil.h>
74 #include <X11/Xmd.h> // for 'CARD32' and other things
75 #include <X11/Xatom.h> // for 'XA_CARDINAL' and other things
76 
77 
78 #if defined(__GNUC__) || defined(__DOXYGEN__)
79 
80 // ======================================================================================
81 // this section is used for doxygen documentation using the X11 definitions
82 // Additionally, 'clang' compilers also define '__GNUC__' and will use this section
83 
84 #include <pthread.h> /* make sure this is included for POSIX */
85 
86 #ifdef X11WORKBENCH_PROJECT_BUILD
87 
88 // Globally include the output of the configure script for GNUC compiles for "the project"
89 #include "X11workbenchToolkit_config.h" // the 'generated' version'
90 
91 #else // X11WORKBENCH_PROJECT_BUILD
92 
93 // This is for the installed version, a subset of the things defined by the configure output script.
94 // NOTE: this must be installed in the appropriate package directory along with platform_helper.h
95 #include "X11workbenchToolkit_install_config.h"
96 
97 #endif // X11WORKBENCH_PROJECT_BUILD
98 
99 // TESTING THE CONFIGURATION - TODO: for some, provide alternates?
100 // NOTE that for 'WIN32' defined, certain features won't be checked
101 
102 // basic checks - test them all up front, then individual errors if any of these
103 // are not defined in the appropriate header files
104 #if !defined( HAVE_ALARM ) || !defined( HAVE_CHOWN ) || \
105  !defined( HAVE_CLOCK_GETTIME ) || !defined( HAVE_DUP2 ) || !defined( HAVE_FORK ) || \
106  !defined( HAVE_FTRUNCATE ) || !defined( HAVE_GETCWD ) || !defined( HAVE_GETTIMEOFDAY ) || \
107  !defined( HAVE_MALLOC ) || !defined( HAVE_MBLEN ) || !defined( HAVE_MEMCHR ) || \
108  !defined( HAVE_MEMMOVE ) || !defined( HAVE_MEMSET ) || !defined( HAVE_MKDIR ) || \
109  !defined( HAVE_PRINTF ) || !defined( HAVE_REALLOC ) || \
110  !defined( HAVE_SELECT ) || !defined( HAVE_SETLOCALE ) || !defined( HAVE_STRCASECMP ) || \
111  !defined( HAVE_STRCHR ) || !defined( HAVE_STRNCASECMP ) || !defined( HAVE_STRRCHR ) || \
112  !defined( HAVE_STRSTR ) || !defined( HAVE__BOOL ) || \
113  ( !defined(WIN32) && ( !defined( LSTAT_FOLLOWS_SLASHED_SYMLINK ) || !defined( HAVE_VFORK ) || \
114  !defined( HAVE_WORKING_FORK ) || !defined( HAVE_WORKING_VFORK ) ))
115 // *************************************************************
116 #error
117 #error configure script feature check 1 fail
118 #error critical features missing
119 #error
120 // this next section spits out errors based on what's not defined.
121 #ifndef HAVE_ALARM
122 #error HAVE_ALARM is not defined
123 #endif // HAVE_ALARM
124 #ifndef HAVE_CHOWN
125 #error HAVE_CHOWN is not defined
126 #endif // HAVE_CHOWN
127 #ifndef HAVE_CLOCK_GETTIME
128 #error HAVE_CLOCK_GETTIME is not defined
129 #endif // HAVE_CLOCK_GETTIME
130 #ifndef HAVE_DUP2
131 #error HAVE_DUP2 is not defined
132 #endif // HAVE_DUP2
133 #ifndef HAVE_FORK
134 #error HAVE_FORK is not defined
135 #endif // HAVE_FORK
136 #ifndef HAVE_FTRUNCATE
137 #error HAVE_FTRUNCATE is not defined
138 #endif // HAVE_FTRUNCATE
139 #ifndef HAVE_GETCWD
140 #error HAVE_GETCWD is not defined
141 #endif // HAVE_GETCWD
142 #ifndef HAVE_GETTIMEOFDAY
143 #error HAVE_GETTIMEOFDAY is not defined
144 #endif // HAVE_GETTIMEOFDAY
145 #ifndef HAVE_MALLOC
146 #error HAVE_MALLOC is not defined
147 #endif // HAVE_MALLOC
148 #ifndef HAVE_MBLEN
149 #error HAVE_MBLEN is not defined
150 #endif // HAVE_MBLEN
151 #ifndef HAVE_MEMCHR
152 #error HAVE_MEMCHR is not defined
153 #endif // HAVE_MEMCHR
154 #ifndef HAVE_MEMMOVE
155 #error HAVE_MEMMOVE is not defined
156 #endif // HAVE_MEMMOVE
157 #ifndef HAVE_MEMSET
158 #error HAVE_MEMSET is not defined
159 #endif // HAVE_MEMSET
160 #ifndef HAVE_MKDIR
161 #error HAVE_MKDIR is not defined
162 #endif // HAVE_MKDIR
163 #ifndef HAVE_PRINTF
164 #error HAVE_PRINTF is not defined
165 #endif // HAVE_PRINTF
166 #ifndef HAVE_REALLOC
167 #error HAVE_REALLOC is not defined
168 #endif // HAVE_REALLOC
169 #ifndef HAVE_SELECT
170 #error HAVE_SELECT is not defined
171 #endif // HAVE_SELECT
172 #ifndef HAVE_SETLOCALE
173 #error HAVE_SETLOCALE is not defined
174 #endif // HAVE_SETLOCALE
175 #ifndef HAVE_STRCASECMP
176 #error HAVE_STRCASECMP is not defined
177 #endif // HAVE_STRCASECMP
178 #ifndef HAVE_STRCHR
179 #error HAVE_STRCHR is not defined
180 #endif // HAVE_STRCHR
181 #ifndef HAVE_STRNCASECMP
182 #error HAVE_STRNCASECMP is not defined
183 #endif // HAVE_STRNCASECMP
184 #ifndef HAVE_STRRCHR
185 #error HAVE_STRRCHR is not defined
186 #endif // HAVE_STRRCHR
187 #ifndef HAVE_STRSTR
188 #error HAVE_STRSTR is not defined
189 #endif // HAVE_STRSTR
190 #ifndef HAVE__BOOL
191 #error HAVE__BOOL is not defined
192 #endif // HAVE__BOOL
193 #ifndef LSTAT_FOLLOWS_SLASHED_SYMLINK
194 #error LSTAT_FOLLOWS_SLASHED_SYMLINK is not defined
195 #endif // LSTAT_FOLLOWS_SLASHED_SYMLINK
196 #ifndef HAVE_VFORK
197 #error HAVE_VFORK is not defined
198 #endif // HAVE_VFORK
199 #ifndef HAVE_WORKING_FORK
200 #error HAVE_WORKING_FORK is not defined
201 #endif // HAVE_WORKING_FORK
202 #ifndef HAVE_WORKING_VFORK
203 #error HAVE_WORKING_VFORK is not defined
204 #endif // HAVE_WORKING_VFORK
205 #error
206 // the end of that previous error section
207 // *************************************************************
208 #else
209 // -------------------------------------------------------------
210 #if !( HAVE_ALARM ) || !( HAVE_CHOWN ) || \
211  !( HAVE_CLOCK_GETTIME ) || !( HAVE_DUP2 ) || !( HAVE_FORK ) || \
212  !( HAVE_FTRUNCATE ) || !( HAVE_GETCWD ) || !( HAVE_GETTIMEOFDAY ) || \
213  !( HAVE_MALLOC ) || !( HAVE_MBLEN ) || !( HAVE_MEMCHR ) || \
214  !( HAVE_MEMMOVE ) || !( HAVE_MEMSET ) || !( HAVE_MKDIR ) || \
215  !( HAVE_PRINTF ) || !( HAVE_REALLOC ) || \
216  !( HAVE_SELECT ) || !( HAVE_SETLOCALE ) || !( HAVE_STRCASECMP ) || \
217  !( HAVE_STRCHR ) || !( HAVE_STRNCASECMP ) || !( HAVE_STRRCHR ) || \
218  !( HAVE_STRSTR ) || !( HAVE__BOOL ) || \
219  ( !defined(WIN32) && ( !( LSTAT_FOLLOWS_SLASHED_SYMLINK ) || !( HAVE_VFORK ) || \
220  !( HAVE_WORKING_FORK ) || !( HAVE_WORKING_VFORK ) ))
221 #error
222 #error configure script feature check 2 fail
223 #error critical features missing
224 #error
225 
226 // TODO: individual error messages for those things 'not defined'? It's a bit
227 // easier to see where something is defined as '0' rather than finding
228 // something that isn't there. For now, I won't add that section, but I
229 // might do it if it becomes necessary
230 
231 #endif // all that stuff defined as a zero
232 // -------------------------------------------------------------
233 #endif // all that prior stuff
234 
235 #ifndef HAVE_BZERO
236  #define HAVE_BZERO 0
237 #endif // !HAVE_BZERO
238 
239 #if !( HAVE_BZERO )
240 // swap this in for 'bzero' using memset - it was checked for earlier
241  #define bzero(X,Y) memset((X),0,(Y))
242 #endif
243 
244 
245 // DEBUG vs RELEASE code
246 
247 #ifdef DEBUG /* explicit DEBUG build */
248 #ifdef NO_DEBUG
249 #undef NO_DEBUG // only one may be defined
250 #endif // NO_DEBUG
251 #endif // DEBUG
252 
253 // NOTE: The debug code will be included when NO_DEBUG is *NOT* defined
254 
273 #define INVALID_HANDLE_VALUE ((int)-1)
274 
275 
280 //-------------------------------------------------
281 // branch optimization macros - gcc and clang only
282 //-------------------------------------------------
283 
284 #if defined(COMPILER_SUPPORTS_BUILTIN_EXPECT) || defined(__DOXYGEN__)
285 
295 #define WB_UNLIKELY(x) (__builtin_expect (!!(x), 0))
296 
305 #define WB_LIKELY(x) (__builtin_expect (!!(x), 1))
306 
307 #else // !COMPILER_SUPPORTS_BUILTIN_EXPECT
308 
309 #define WB_UNLIKELY(x) (x)
310 #define WB_LIKELY(x) (x)
311 
312 #endif // COMPILER_SUPPORTS_BUILTIN_EXPECT
313 
314 #if defined(COMPILER_SUPPORTS_UNUSED_ATTRIBUTE) || defined(__DOXYGEN__)
315 
327 #define WB_UNUSED __attribute__((unused))
328 
329 #else // !COMPILER_SUPPORTS_UNUSED_ATTRIBUTE
330 
331 #define WB_UNUSED
332 
333 #endif // COMPILER_SUPPORTS_UNUSED_ATTRIBUTE
334 
335 
354 #define WB_INTERNAL_ATOM_MIN_VAL 0x3f000000L
365 typedef int WB_INT32;
366 
372 typedef unsigned int WB_UINT32;
373 
374 
375 #if defined(HAVE_LONGLONG) || defined(__DOXYGEN__) /* 'configure' tests for 'long long' datatype valid in configure script */
376 
380 #define HAS_WB_UINT64_BUILTIN
381 
382 
388 typedef long long WB_INT64;
389 
395 typedef unsigned long long WB_UINT64;
396 
397 #else // !defined HAVE_LONGLONG, unlikely (this part won't show up in doxygen either)
398 
399 typedef struct __WB_INT64__ { WB_UINT32 dw2; WB_INT32 dw1; } WB_INT64; // note 'dw1' is a signed value
400 typedef struct __WB_UINT64__ { WB_UINT32 dw2; WB_UINT32 dw1; } WB_UINT64;
401 
402 #endif // _LONGLONG
403 
404 #ifdef __DOXYGEN__
405 
410 typedef unsigned long long WB_UINTPTR;
411 #else /* regular code uses this next part */
412 
413 #if !defined(__SIZEOF_POINTER__) // TODO find a better way to deal with pointer size if this isn't defined
414 #define __SIZEOF_POINTER__ 0
415 #endif
416 
417 #if defined(__LP64__) /* TODO see what WIN32 vs WIN64 does */
418 typedef WB_UINT64 WB_UINTPTR;
419 #elif __SIZEOF_POINTER__ == 4 /* 4-byte pointer */
420 typedef WB_UINT32 WB_UINTPTR;
421 #else // assume long pointer
422 typedef WB_UINT64 WB_UINTPTR;
423 #endif // __LP64__
424 #endif // __DOXYGEN__
425 
426 
430 #define WB_C99_INITIALIZERS /* allow C99-style initializers */
431 
437 typedef void * WB_MODULE;
438 
444 typedef pthread_t WB_THREAD;
445 
451 typedef void (* WB_PROCADDRESS)(void);
452 
458 typedef pthread_key_t WB_THREAD_KEY;
459 
465 typedef WB_UINT32 WB_COND; // defined as 'WB_UINT32' because of pthread_cond problems under Linux
466 //typedef pthread_cond_t WB_COND;
467 
473 typedef pthread_mutex_t WB_MUTEX;
474 
475 // TODO: sizeof(int) sizeof(long) - long is 64-bit for GNUC - MS compilers make it 32-bit
476 
477 #ifdef __DOXYGEN__
478 
484 #define __PACKED__ /* platform dependent; actual def must be a blank or doxygen barphs on it */
485 
486 #else // !__DOXYGEN__
487 
488 #define __PACKED__ __attribute__((__packed__))
489 
490 #endif // __DOXYGEN__
491 
492 // end of section for clang and gcc compilers (and also doxygen definitions)
493 // ======================================================================================
494 
495 #elif defined(_MSC_VER) /* Microsoft C/C++ compiler */
496 
497 // ======================================================================================
498 // this section is dedicated to Microsoft compilers, which do things a bit different...
499 
500 // TODO: add proper support for MS compiler
501 #if _MSC_VER > 1300
502 
503 // TODO: specify correct version in which C99 initializers are supported
504 // as of MSC for ".Net" 2010 it's _NOT_ supported (still!)
505 //#define WB_C99_INITIALIZERS
506 
507 #endif // _MSC_VER > xxxx
508 
509 #define WB_UNLIKELY(x) (x)
510 #define WB_LIKELY(x) (x)
511 
512 #ifndef __inline__
513 #define __inline__ inline /* this assumes 'inline' is supported (MSC should support this) */
514 #endif // __inline__
515 
516 typedef __int64 WB_INT64;
517 typedef unsigned __int64 WB_UINT64;
518 typedef int WB_INT32;
519 typedef unsigned int WB_UINT32;
520 
521 // assume MS Windows Win32 API
522 typedef HMODULE WB_MODULE ; /* module handle */
523 typedef HANDLE WB_THREAD; /* thread handle - thread IDs are still 'int' types */
524 typedef FARPROC WB_PROCADDRESS; // generic proc address returned from GetProcAddress()
525 
526 typedef DWORD WBTHREAD_KEY; // return from 'TlsAlloc()'
527 typedef HANDLE WB_COND; // equivalent to an event handle
528 typedef HANDLE WB_MUTEX; // equivalent to a mutex handle
529 
530 
531 // TODO: sizeof(int) sizeof(long) - long is 32-bit for MSC
532 
533 // TODO: compatibility definition file for winders
534 
535 #define __PACKED__ /* TODO: a definition for packing in MS-land */
536 
537 // end of section specific to Microsoft compilers
538 // ======================================================================================
539 
540 #else // !defined(_MSVC_VER) && !defined(__GNUC__)
541 
542 #error unknown and/or unsupported compiler
543 
544 #endif // __GNUC__
545 
546 
547 // put standard '#define's and typedefs here, the ones that apply to EVERYBODY
548 
553 #define WB_SECURE_HASH_TIMEOUT 60000
563 typedef char * WB_PSTR;
564 typedef const char * WB_PCSTR;
565 
566 
572 // //
574 // ____ _ _ _ _ ____ _ _ _ //
575 // / ___| | |_ __ _ _ __ | |_ _ _ _ __ / \ _ __ __| | / ___| | |__ _ _ | |_ __| | ___ __ __ _ __ //
576 // \___ \ | __|/ _` || '__|| __|| | | || '_ \ / _ \ | '_ \ / _` | \___ \ | '_ \ | | | || __|/ _` | / _ \\ \ /\ / /| '_ \ //
577 // ___) || |_| (_| || | | |_ | |_| || |_) | / ___ \ | | | || (_| | ___) || | | || |_| || |_| (_| || (_) |\ V V / | | | | //
578 // |____/ \__|\__,_||_| \__| \__,_|| .__/ /_/ \_\|_| |_| \__,_| |____/ |_| |_| \__,_| \__|\__,_| \___/ \_/\_/ |_| |_| //
579 // |_| //
580 // //
582 
599 extern int bQuitFlag;
600 
601 // these functions are internal-only, implemented in window_helper.c, but must be defined here
602 void __internal_startup_display(const char *szVal);
603 void __internal_startup_minimize(void);
604 void __internal_startup_maximize(void);
605 void __internal_startup_geometry(const char *szVal);
606 
607 
608 
609 // *******************************************
610 // STARTUP AND SHUTDOWN (must-call functions)
611 // *******************************************
612 
622 void WBPlatformOnInit(void);
623 
634 void WBPlatformOnExit(void);
635 
636 
666 int WBParseStandardArguments(int *pargc, char ***pargv, char ***penvp);
667 
673 void WBToolkitUsage(void);
674 
684 const char *GetStartupAppName(void);
685 
686 
687 
688 
690 // //
691 // ____ _ _ _ _ _ _ //
692 // / ___| _ _ ___ | |_ ___ _ __ ___ | | | || |_ (_)| | ___ //
693 // \___ \ | | | |/ __|| __|/ _ \| '_ ` _ \ | | | || __|| || |/ __| //
694 // ___) || |_| |\__ \| |_| __/| | | | | | | |_| || |_ | || |\__ \ //
695 // |____/ \__, ||___/ \__|\___||_| |_| |_| \___/ \__||_||_||___/ //
696 // |___/ //
697 // //
699 
700 
713 WB_UINT64 WBGetTimeIndex(void); // returns current 'time index' (in microseconds) which never wraps around
714  // NOTE: it is derived from the 'gettimeofday' call on BSD, Linux, etc.
715 
716 
731 void WBDelay(uint32_t uiDelay); // approximate delay for specified period (in microseconds). may be interruptible
732 
733 
747 int WBCPUCount(void);
748 
749 
750 
752 // //
753 // __ __ _ _ _ _ _ //
754 // | \/ | ___ _ __ ___ ___ _ __ _ _ / \ | || | ___ ___ __ _ | |_ (_) ___ _ __ //
755 // | |\/| | / _ \| '_ ` _ \ / _ \ | '__|| | | | / _ \ | || | / _ \ / __|/ _` || __|| | / _ \ | '_ \ //
756 // | | | || __/| | | | | || (_) || | | |_| | / ___ \ | || || (_) || (__| (_| || |_ | || (_) || | | | //
757 // |_| |_| \___||_| |_| |_| \___/ |_| \__, | /_/ \_\|_||_| \___/ \___|\__,_| \__||_| \___/ |_| |_| //
758 // |___/ //
759 // //
761 
762 
763 // memory allocation (with debug support)
764 
773 void *WBAlloc(int nSize);
774 
783 void WBFree(void *pBuf);
784 
802 int WBAllocUsableSize(void *pBuf);
803 
813 void * WBReAlloc(void *pBuf, int nNewSize);
814 
824 void WBSubAllocTrashMasher(void);
825 
826 
827 // BASIC STRING UTILITIES
828 
829 // simple but helpful string utilities
830 
843 char *WBCopyString(const char *pSrc);
844 
859 char *WBCopyStringN(const char *pSrc, unsigned int nMaxChars);
860 
876 void WBCatString(char **ppDest, const char *pSrc);
877 
895 void WBCatStringN(char **ppDest, const char *pSrc, unsigned int nMaxChars);
896 
908 void WBDeQuoteString(char *pszStr); // de-quote a string in place
909 
922 void WBNormalizeXMLString(char *pString);
923 
937 int WBStringLineCount(const char *pSrc, unsigned int nMaxChars);
938 
952 const char *WBStringNextLine(const char *pSrc, unsigned int *pnMaxChars);
953 
954 
955 #if 0
956 
957 // THIS IS ALL RESERVED FOR FUTURE USE
958 // MAY NOT BE NEEDED IF I USE _Xmbtowc _Xwctomb and _Xwctomb
959 // X11 defines them as mblen(), mbtowc(), and wctomb()
960 // The alternative is to do something similar on WIN32, once that is implemented in the toolkit
961 // with '#ifdef blocks all around it
962 
980 int WBIsMultiByte(const char *pszStr);
981 
982 
994 XChar2b * WBConvertMultiByteTo16(const char *pszStr);
995 
1006 char *WBConvertMultiByteFrom16(const XChar2b *pwzStr);
1007 #endif // 0
1008 
1009 
1011 // //
1012 // __ __ ____ __ __ _ _ _ //
1013 // \ \/ /| _ \ | \/ | | | (_)| |__ _ __ __ _ _ __ _ _ //
1014 // \ / | |_) || |\/| | | | | || '_ \ | '__|/ _` || '__|| | | | //
1015 // / \ | __/ | | | | | |___ | || |_) || | | (_| || | | |_| | //
1016 // /_/\_\|_| |_| |_| |_____||_||_.__/ |_| \__,_||_| \__, | //
1017 // |___/ //
1018 // //
1020 
1021 
1022 // XPM library (libXpm) and X11/xpm.h
1023 
1024 #if defined(X11WORKBENCH_TOOLKIT_HAVE_XPM) && !defined(__DOXYGEN__)
1025 
1026 // Doxygen doesn't need THIS part, it needs the other one.
1027 
1028 #include <X11/xpm.h>
1029 
1030 // no need for doxygen doc comments here, see '!defined(__DOXYGEN__)' above
1031 // these definitions are for when libXpm is being used
1032 #define XPM_ATTRIBUTES XpmAttributes
1033 #define XPM_CREATE_PIXMAP_FROM_DATA(A,B,C,D,E,F) XpmCreatePixmapFromData(A,B,C,D,E,F)
1034 #define XPM_FREE_ATTRIBUTES(pAttr) XpmFreeAttributes(pAttr)
1035 
1036 #else // !X11WORKBENCH_TOOLKIT_HAVE_XPM or __DOXYGEN__
1037 
1084 typedef struct _XPM_ATTRIBUTES_
1085 {
1086  // I only need certain information from MyLoadPixmapFromData(), so that's all I'm doing with this structure
1087 
1088  int width;
1089  int height;
1090  int depth;
1091 
1092 } XPM_ATTRIBUTES;
1093 
1094 
1123 int MyLoadPixmapFromData(Display *pDisplay, Window wID, char *aData[],
1124  Pixmap *pPixmap, Pixmap *pMask, XPM_ATTRIBUTES *pAttr);
1125 
1140 #define XPM_CREATE_PIXMAP_FROM_DATA(A,B,C,D,E,F) MyLoadPixmapFromData(A,B,C,D,E,F)
1141 
1153 #define XPM_FREE_ATTRIBUTES(pAttr) /* does nothing */
1154 
1155 
1156 #endif
1157 
1158 
1159 // some helpful macros that need to be universal without being in a different header
1160 
1170 #define NEXT_WORD(pX, pY, pZ) {while(*(pX) && *(pX) <= ' '){(pX)++;} (pY)=(pZ)=(pX); while(*(pX)>' '){(pX)++;} (pZ)=(pX);}
1171 
1172 
1173 
1174 
1175 
1176 #ifdef __cplusplus
1177 extern "C" {
1178 #endif // __cplusplus
1179 
1180 // common macros
1181 
1182 #ifndef FALSE
1183 #define FALSE 0
1184 #endif // FALSE
1185 #ifndef TRUE
1186 #define TRUE !0
1187 #endif // TRUE
1188 
1189 
1190 
1191 // HANDLING qsort_r CALLING CONVENTION DIFFERENCES
1192 //
1193 #if defined(QSORT_R_BSD) && !defined(__DOXYGEN__)
1194 
1195 // DECLARE_SORT_FUNCTION based on - int (*compar)(void *, const void *, const void *)
1196 // generates int fn_name(void *p0, const void *p1, const void *p2)
1197 #define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(void *p0, const void *p1, const void *p2)
1198 // void qsort_r(void *base, size_t nmemb, size_t size, void *thunk, int (*compar)(void *, const void *, const void *))
1199 #define QSORT_R(A,B,C,D,E) qsort_r((A),(B),(C),(D),(E))
1200 
1201 #elif defined(QSORT_R_GNUC) && !defined(__DOXYGEN__)
1202 
1203 // DECLARE_SORT_FUNCTION based on typedef int (*__compar_d_fn_t) (__const void *, __const void *, void *)
1204 // generates int fn_name(const void *p1, const void *p2, void *p0)
1205 #define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(const void *p1, const void *p2, void *p0)
1206 // extern void qsort_r (void *__base, size_t __nmemb, size_t __size, __compar_d_fn_t __compar, void *__arg)
1207 #define QSORT_R(A,B,C,D,E) qsort_r((A),(B),(C),(E),(D))
1208 
1209 #else
1210 
1211 // here is where I implement 'vectored' quicksort for OTHER PLATFORMS
1212 
1226 void my_qsort_r(void *base, int nmemb, int size, void *thunk,
1227  int (*compar)(void *, const void *, const void *));
1228 
1229 // the rest is exactly like the BSD version
1230 
1263 #define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(void *p0, const void *p1, const void *p2)
1264 
1265 
1279 #define QSORT_R(base,nmemb,size,thunk,compar) my_qsort_r((base),(nmemb),(size),(thunk),(compar))
1280 
1281 #endif
1282 
1283 
1285 // //
1286 // ___ _ _ //
1287 // |_ _| _ __ | |_ ___ _ __ _ __ __ _ | | //
1288 // | | | '_ \ | __|/ _ \| '__|| '_ \ / _` || | //
1289 // | | | | | || |_| __/| | | | | || (_| || | //
1290 // |___||_| |_| \__|\___||_| |_| |_| \__,_||_| //
1291 // //
1292 // //
1294 
1295 
1296 // *********************************
1297 // INTERNAL memory/security helpers
1298 // *********************************
1299 
1325 WB_UINT32 WBCreatePointerHash(void *pPointer);
1326 
1348 void WBDestroyPointerHash(WB_UINT32 uiHash);
1349 
1366 void WBDestroyPointerHashPtr(void *pPointer);
1367 
1386 void * WBGetPointerFromHash(WB_UINT32 uiHash);
1387 
1388 
1389 
1391 // //
1392 // _ _ //
1393 // / \ | |_ ___ _ __ ___ ___ //
1394 // / _ \ | __|/ _ \ | '_ ` _ \ / __| //
1395 // / ___ \| |_| (_) || | | | | |\__ \ //
1396 // /_/ \_\\__|\___/ |_| |_| |_||___/ //
1397 // //
1398 // //
1400 
1401 //-----------------------------------------
1402 // ATOM HELPERS (internally-defined atoms)
1403 //-----------------------------------------
1404 
1405 
1429 Atom WBGetAtom(Display *pDisplay, const char *szAtomName);
1430 
1458 Atom WBLookupAtom(Display *pDisplay, const char *szAtomName);
1459 
1480 char * WBGetAtomName(Display *pDisplay, Atom aAtom);
1481 
1482 
1483 
1484 
1486 // //
1487 // ____ _ _ _ _____ _____ _ _ //
1488 // | _ \ __ _ | |_ | |__ ___ __ _ _ __ __| | |_ _|___ _ __ ___ _ __ | ___|(_)| | ___ ___ //
1489 // | |_) |/ _` || __|| '_ \ / __| / _` || '_ \ / _` | | | / _ \| '_ ` _ \ | '_ \ | |_ | || | / _ \/ __| //
1490 // | __/| (_| || |_ | | | |\__ \ | (_| || | | || (_| | | || __/| | | | | || |_) | | _| | || || __/\__ \ //
1491 // |_| \__,_| \__||_| |_||___/ \__,_||_| |_| \__,_| |_| \___||_| |_| |_|| .__/ |_| |_||_| \___||___/ //
1492 // |_| //
1493 // //
1495 
1496 // *******************************************
1497 // FILE/APPLICATION SEARCH PATH AND TEMP FILES
1498 // *******************************************
1499 
1514 char * WBSearchPath(const char *szFileName);
1515 
1534 char * WBTempFile(const char *szExt);
1535 
1536 
1551 char * WBTempFile0(const char *szExt);
1552 
1553 
1554 
1556 // //
1557 // _____ _ _ _ _ _ _ _ //
1558 // | ____|__ __| |_ ___ _ __ _ __ __ _ | | / \ _ __ _ __ | |(_) ___ __ _ | |_ (_) ___ _ __ ___ //
1559 // | _| \ \/ /| __|/ _ \| '__|| '_ \ / _` || | / _ \ | '_ \ | '_ \ | || | / __|/ _` || __|| | / _ \ | '_ \ / __| //
1560 // | |___ > < | |_| __/| | | | | || (_| || | / ___ \ | |_) || |_) || || || (__| (_| || |_ | || (_) || | | |\__ \ //
1561 // |_____|/_/\_\ \__|\___||_| |_| |_| \__,_||_| /_/ \_\| .__/ | .__/ |_||_| \___|\__,_| \__||_| \___/ |_| |_||___/ //
1562 // |_| |_| //
1563 // //
1564 // _ _ ____ //
1565 // / \ _ __ __| | | _ \ _ __ ___ ___ ___ ___ ___ ___ ___ //
1566 // / _ \ | '_ \ / _` | | |_) || '__|/ _ \ / __|/ _ \/ __|/ __| / _ \/ __| //
1567 // / ___ \ | | | || (_| | | __/ | | | (_) || (__| __/\__ \\__ \| __/\__ \ //
1568 // /_/ \_\|_| |_| \__,_| |_| |_| \___/ \___|\___||___/|___/ \___||___/ //
1569 // //
1571 
1572 // *********************
1573 // SPAWNING APPLICATIONS
1574 // *********************
1575 
1576 #ifdef WIN32
1577 #define WB_FILE_HANDLE HANDLE
1578 #define WB_PROCESS_ID HANDLE
1579 #define WB_INVALID_FILE_HANDLE INVALID_HANDLE_VALUE
1580 #else // !WIN32
1581 #define WB_FILE_HANDLE int
1582 #define WB_PROCESS_ID unsigned int
1583 #define WB_INVALID_FILE_HANDLE -1
1584 #endif // WIN32
1585 
1599 WB_PROCESS_ID WBRunAsync(const char *szAppName, ...);
1600 
1618 char * WBRunResult(const char *szAppName, ...);
1619 
1642 char * WBRunResultPipe(const char *szStdInBuf, const char *szAppName, ...);
1643 
1644 
1670 WB_PROCESS_ID WBRunAsyncPipe(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr,
1671  const char *szAppName, ...);
1672 
1673 
1704 WB_PROCESS_ID WBRunAsyncPipeV(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr,
1705  const char *szAppName, va_list va);
1706 
1707 
1708 
1709 
1711 // ____ _ _ _ ____ _____ ____ _ ___ ____ ____ //
1712 // / ___|| | | | / \ | _ \| ____| _ \ | | |_ _| __ ) ___| //
1713 // \___ \| |_| | / _ \ | |_) | _| | | | | | | | || _ \___ \ //
1714 // ___) | _ |/ ___ \| _ <| |___| |_| | | |___ | || |_) |__) | //
1715 // |____/|_| |_/_/ \_\_| \_\_____|____/ |_____|___|____/____/ //
1716 // //
1718 
1729 WB_MODULE WBLoadLibrary(const char *szModuleName); // load a library module (shared lib, DLL, whatever)
1730 
1740 void WBFreeLibrary(WB_MODULE hModule);
1741 
1753 WB_PROCADDRESS WBGetProcAddress(WB_MODULE hModule, const char *szProcName);
1754 
1755 
1756 
1758 // _____ _ _ ____ _____ _ ____ ____ //
1759 // |_ _| | | | _ \| ____| / \ | _ \/ ___| //
1760 // | | | |_| | |_) | _| / _ \ | | | \___ \ //
1761 // | | | _ | _ <| |___ / ___ \| |_| |___) | //
1762 // |_| |_| |_|_| \_\_____/_/ \_\____/|____/ //
1763 // //
1765 
1776 
1786 void WBThreadFreeLocal(WB_THREAD_KEY keyVal);
1787 
1798 void * WBThreadGetLocal(WB_THREAD_KEY keyVal);
1799 
1810 void WBThreadSetLocal(WB_THREAD_KEY keyVal, void *pValue);
1811 
1812 
1813 // simplified thread support (cross-platform)
1814 
1826 
1838 WB_THREAD WBThreadCreate(void *(*function)(void *), void *pParam);
1839 
1851 void *WBThreadWait(WB_THREAD hThread); // closes hThread, returns exit code, waits for thread to terminate (blocks)
1852 
1866 int WBThreadRunning(WB_THREAD hThread);
1867 
1879 void WBThreadExit(void *pRval);
1880 
1894 void WBThreadClose(WB_THREAD hThread);
1895 
1896 
1908 int WBCondCreate(WB_COND *pCond);
1909 
1920 int WBMutexCreate(WB_MUTEX *pMtx);
1921 
1931 void WBCondFree(WB_COND *pCond);
1932 
1942 void WBMutexFree(WB_MUTEX *pMtx);
1943 
1957 int WBMutexLock(WB_MUTEX *pMtx, int nTimeout);
1958 
1969 int WBMutexUnlock(WB_MUTEX *pMtx);
1970 
1982 int WBCondSignal(WB_COND *pCond);
1983 
1996 int WBCondWait(WB_COND *pCond, int nTimeout);
1997 
2016 int WBCondWaitMutex(WB_COND *pCond, WB_MUTEX *pMtx, int nTimeout);
2017 
2018 
2031 WB_UINT32 WBInterlockedDecrement(volatile WB_UINT32 *pValue);
2032 
2033 
2046 WB_UINT32 WBInterlockedIncrement(volatile WB_UINT32 *pValue);
2047 
2048 
2063 WB_UINT32 WBInterlockedExchange(volatile WB_UINT32 *pValue, WB_UINT32 nNewVal);
2064 
2065 
2079 WB_UINT32 WBInterlockedRead(volatile WB_UINT32 *pValue);
2080 
2081 
2082 
2084 // ____ ____ ___ _ _ _____ ___ _ _ ____ //
2085 // | _ \| _ \|_ _| \ | |_ _|_ _| \ | |/ ___| //
2086 // | |_) | |_) || || \| | | | | || \| | | _ //
2087 // | __/| _ < | || |\ | | | | || |\ | |_| | //
2088 // |_| |_| \_\___|_| \_| |_| |___|_| \_|\____| //
2089 // //
2091 
2092 // NOTE: the POSIX world uses postscript, particularly with CUPS. So does this library.
2093 
2121 int WBPrintPostScriptFile(const char *szPrinterName, const char *szFileName);
2122 
2141 char *WBGetPrinterList(void);
2142 
2143 // TODO: complete IPP support for cups and network-capable printers
2144 
2145 // TODO: printer capabilities in a binary structure
2146 
2147 // TODO: support for port 515 'printer' TCP/UDP printer services (i.e. cups-lpd or lpd)
2148 
2149 // TODO: dynamically load CUPS API when available. see 'cups-config' application docs
2150 
2151 
2152 
2153 #ifdef __cplusplus
2154 };
2155 #endif // __cplusplus
2156 
2157 
2158 #endif // _PLATFORM_HELPER_H_INCLDUED_
2159 
void * WBGetPointerFromHash(WB_UINT32 uiHash)
Obtain a pointer from a 32-bit &#39;secure&#39; pointer hash value.
unsigned int WB_UINT32
Platform abstract unsigned 32-bit integer.
const char * GetStartupAppName(void)
returns a pointer to a copy of the application name from argv[0]
void WBPlatformOnExit(void)
Resource &#39;free-up&#39; on exit (must call)
void * WB_MODULE
MODULE HANDLE equivalent.
char * WBTempFile(const char *szExt)
Get the name for a new, unique temporary file, creating the file in the process, and save its name fo...
WB_UINT32 WB_COND
CONDITION HANDLE equivalent (similar to an &#39;event&#39;)
WB_THREAD_KEY WBThreadAllocLocal(void)
Allocate &#39;thread local&#39; storage.
int bQuitFlag
&#39;Quit&#39; Flag - you should check this periodically in your main (message) loop and exit whenever it is ...
void WBThreadFreeLocal(WB_THREAD_KEY keyVal)
Free &#39;thread local&#39; storage allocated by WBThreadAllocLocal()
int WB_INT32
Platform abstract 32-bit integer.
int WBMutexUnlock(WB_MUTEX *pMtx)
Unlock a previously locked mutex.
void * WBThreadGetLocal(WB_THREAD_KEY keyVal)
Get &#39;thread local&#39; data identified by &#39;keyVal&#39;.
void WBCatStringN(char **ppDest, const char *pSrc, unsigned int nMaxChars)
A simple utility that concatenates a string onto the end of a 0-byte terminated WBAlloc() string up t...
int WBStringLineCount(const char *pSrc, unsigned int nMaxChars)
Determine how many &#39;lines&#39; are in a block of text by counting &#39;linefeed&#39; characters.
char * WBRunResult(const char *szAppName,...)
Run an application synchronously, returning &#39;stdout&#39; output in a character buffer.
void WBSubAllocTrashMasher(void)
High performance memory sub-allocator &#39;trash masher&#39; - call periodically to minimize wasted memory...
int MyLoadPixmapFromData(Display *pDisplay, Window wID, char *aData[], Pixmap *pPixmap, Pixmap *pMask, XPM_ATTRIBUTES *pAttr)
Alternate for XpmCreatePixmapFromData() whenever libXpm is not being used.
void WBFreeLibrary(WB_MODULE hModule)
Frees a shared library, DLL, module, or whatever, that was loaded via &#39;WBLoadLibrary()&#39;.
WB_MODULE WBLoadLibrary(const char *szModuleName)
Loads a shared library, DLL, module, or whatever you call it on your operating system.
void * WBThreadWait(WB_THREAD hThread)
Wait for a specified threat to exit.
void WBThreadExit(void *pRval)
Exit the current thread immediately, specifying return code.
WB_UINT32 WBInterlockedIncrement(volatile WB_UINT32 *pValue)
Interlocked &#39;atomic&#39; increment of an unsigned integer.
void my_qsort_r(void *base, int nmemb, int size, void *thunk, int(*compar)(void *, const void *, const void *))
Local implementation of qsort_r() for operating systems that do not have it.
pthread_key_t WB_THREAD_KEY
THREAD LOCAL STORAGE &#39;key&#39; equivalent.
WB_UINT32 WBCreatePointerHash(void *pPointer)
Create/obtain a 32-bit &#39;secure&#39; hash for a pointer.
WB_PROCESS_ID WBRunAsyncPipe(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr, const char *szAppName,...)
Run an application asynchronously, specifying file handles for STDIN, STDOUT, and STDERR...
WB_UINT32 WBInterlockedExchange(volatile WB_UINT32 *pValue, WB_UINT32 nNewVal)
Interlocked &#39;atomic&#39; exchange of an unsigned integer with a specified value.
void * WBReAlloc(void *pBuf, int nNewSize)
High performance memory sub-allocator &#39;re-allocate&#39;.
pthread_mutex_t WB_MUTEX
MUTEX HANDLE equivalent.
int depth
depth of the returned &#39;image&#39; pixmap. The mask pixmap always has a depth of &#39;1&#39;.
WB_UINT64 WBGetTimeIndex(void)
Returns the current &#39;time index&#39; (in microseconds)
WB_THREAD WBThreadCreate(void *(*function)(void *), void *pParam)
Create a new thread, returning its WB_THREAD identifier.
void WBDeQuoteString(char *pszStr)
De-Quote a string &#39;in place&#39;, that is modifying the original string by removing quotes.
void WBToolkitUsage(void)
Displays &#39;usage&#39; for toolkit options to stderr.
void WBThreadSetLocal(WB_THREAD_KEY keyVal, void *pValue)
Get &#39;thread local&#39; data identified by &#39;keyVal&#39;.
void WBDestroyPointerHashPtr(void *pPointer)
Destroy a 32-bit &#39;secure&#39; hash for a pointer regardless of reference count.
void(* WB_PROCADDRESS)(void)
PROC ADDRESS equivalent.
void * WBAlloc(int nSize)
High performance memory sub-allocator &#39;allocate&#39;.
int WBCondSignal(WB_COND *pCond)
Signal a condition (event)
unsigned long long WB_UINT64
Platform abstract unsigned 64-bit integer.
WB_PROCESS_ID WBRunAsync(const char *szAppName,...)
Run an application asynchronously.
char * WBGetPrinterList(void)
Get a list of printer names.
Atom WBLookupAtom(Display *pDisplay, const char *szAtomName)
Lookup (but do not allocate) an internal (or X11) Atom for a named string.
WB_THREAD WBThreadGetCurrent(void)
Get &#39;current thread&#39; identifier.
char * WBSearchPath(const char *szFileName)
search for a file using the PATH environment variable
char * WBRunResultPipe(const char *szStdInBuf, const char *szAppName,...)
Run an application synchronously, returning &#39;stdout&#39; output in a character buffer.
void WBFree(void *pBuf)
High performance memory sub-allocator &#39;free&#39;.
void WBDelay(uint32_t uiDelay)
Delay for a specified period in microseconds.
int WBParseStandardArguments(int *pargc, char ***pargv, char ***penvp)
parses standard C arguments as passed to &#39;main()&#39;
void WBPlatformOnInit(void)
Resource initialization on startup.
WB_UINT32 WBInterlockedDecrement(volatile WB_UINT32 *pValue)
Interlocked &#39;atomic&#39; decrement of an unsigned integer.
int WBAllocUsableSize(void *pBuf)
High performance memory sub-allocator, similar to &#39;malloc_usable_size&#39;.
unsigned long long WB_UINTPTR
Platform abstract unsigned integer that matches pointer size.
Atom WBGetAtom(Display *pDisplay, const char *szAtomName)
Lookup and/or allocate an internal Atom for a named string (lookups include X11 atoms) ...
WB_PROCADDRESS WBGetProcAddress(WB_MODULE hModule, const char *szProcName)
Loads a shared library, DLL, module, or whatever you call it on your operating system.
int WBMutexCreate(WB_MUTEX *pMtx)
Create a lockable mutex.
int WBMutexLock(WB_MUTEX *pMtx, int nTimeout)
Wait for and lock a mutex, blocking until it is available.
int WBThreadRunning(WB_THREAD hThread)
Determine whether a thread is running (can be suspended)
const char * WBStringNextLine(const char *pSrc, unsigned int *pnMaxChars)
Locate the next line in a block of text, returning its pointer (and updating remaining length) ...
struct _XPM_ATTRIBUTES_ XPM_ATTRIBUTES
Compatibility structure for use with MyLoadPixmapFromData() whenever libXpm is not in use...
WB_PROCESS_ID WBRunAsyncPipeV(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr, const char *szAppName, va_list va)
Run an application asynchronously, specifying file handles for STDIN, STDOUT, and STDERR...
char * WBCopyStringN(const char *pSrc, unsigned int nMaxChars)
A simple utility that returns a WBAlloc() copy of a string up to a maximum length (can also be 0-byte...
long long WB_INT64
Platform abstract 64-bit integer.
int WBCondWait(WB_COND *pCond, int nTimeout)
Wait for a signal on a condition (event)
void WBMutexFree(WB_MUTEX *pMtx)
Free a lockable mutex.
void WBDestroyPointerHash(WB_UINT32 uiHash)
Destroy a 32-bit &#39;secure&#39; hash for a pointer.
int height
height of the returned pixmaps
char * WBGetAtomName(Display *pDisplay, Atom aAtom)
Lookup and/or allocate an internal Atom for a named string.
int width
The width of the returned pixmaps.
pthread_t WB_THREAD
THREAD HANDLE equivalent.
char * WBTempFile0(const char *szExt)
Get the name for a new, unique temporary file, creating the file in the process.
char * WBCopyString(const char *pSrc)
A simple utility that returns a WBAlloc() copy of a 0-byte terminated string.
int WBCondWaitMutex(WB_COND *pCond, WB_MUTEX *pMtx, int nTimeout)
Wait for a signal on a condition (event)
Compatibility structure for use with MyLoadPixmapFromData() whenever libXpm is not in use...
void WBThreadClose(WB_THREAD hThread)
Close the specified WB_THREAD identifier.
int WBCPUCount(void)
Get the number of available CPU cores.
WB_UINT32 WBInterlockedRead(volatile WB_UINT32 *pValue)
Interlocked &#39;atomic&#39; read of an unsigned integer.
int WBPrintPostScriptFile(const char *szPrinterName, const char *szFileName)
Send postscript file to a printer (using lpr-cups or lpr on POSIX systems)
int WBCondCreate(WB_COND *pCond)
Create a signallable condition.
void WBNormalizeXMLString(char *pString)
De-Quote and &#39;normalize&#39; an XML string &#39;in place&#39;, that is modifying the original string by removing ...
void WBCatString(char **ppDest, const char *pSrc)
A simple utility that concatenates a string onto the end of a 0-byte terminated WBAlloc() string...
void WBCondFree(WB_COND *pCond)
Free a signallable condition.