X11 Work Bench 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-2016 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 
69 // X11 header files (TODO: use 'ifdef' blocks around this as needed for non-X platforms)
70 
71 #include <X11/Xlib.h>
72 #include <X11/Xutil.h>
73 #include <X11/Xmd.h> // for 'CARD32' and other things
74 #include <X11/Xatom.h> // for 'XA_CARDINAL' and other things
75 
76 
77 #if defined(__GNUC__) || defined(__DOXYGEN__)
78 
79 // this section included for doxygen documentation using the X11 definitions
80 
81 #include <pthread.h> /* make sure this is included for POSIX */
82 
83 #ifdef X11WORKBENCH_PROJECT_BUILD
84 
85 // Globally include the output of the configure script for GNUC compiles for "the project"
86 #include "X11workbenchToolkit_config.h" // the 'generated' version'
87 
88 #else // X11WORKBENCH_PROJECT_BUILD
89 
90 // This is for the installed version, a subset of the things defined by the configure output script.
91 // NOTE: this must be installed in the appropriate package directory along with platform_helper.h
92 #include "X11workbenchToolkit_install_config.h"
93 
94 #endif // X11WORKBENCH_PROJECT_BUILD
95 
96 // TESTING THE CONFIGURATION - TODO: for some, provide alternates?
97 
98 #if !defined( HAVE_ALARM ) || !defined( HAVE_CHOWN ) || \
99  !defined( HAVE_CLOCK_GETTIME ) || !defined( HAVE_DUP2 ) || !defined( HAVE_FORK ) || \
100  !defined( HAVE_FTRUNCATE ) || !defined( HAVE_GETCWD ) || !defined( HAVE_GETTIMEOFDAY ) || \
101  !defined( HAVE_MALLOC ) || !defined( HAVE_MBLEN ) || !defined( HAVE_MEMCHR ) || \
102  !defined( HAVE_MEMMOVE ) || !defined( HAVE_MEMSET ) || !defined( HAVE_MKDIR ) || \
103  !defined( HAVE_PRINTF ) || !defined( HAVE_REALLOC ) || \
104  !defined( HAVE_SELECT ) || !defined( HAVE_SETLOCALE ) || !defined( HAVE_STRCASECMP ) || \
105  !defined( HAVE_STRCHR ) || !defined( HAVE_STRNCASECMP ) || !defined( HAVE_STRRCHR ) || \
106  !defined( HAVE_STRSTR ) || !defined( HAVE_VFORK ) || !defined( HAVE_WORKING_FORK ) || \
107  !defined( HAVE_WORKING_VFORK ) || !defined( HAVE__BOOL ) || !defined( LSTAT_FOLLOWS_SLASHED_SYMLINK )
108 #error
109 #error configure script feature check 1 fail
110 #error critical features missing
111 #error
112 #else
113 #if !( HAVE_ALARM ) || !( HAVE_CHOWN ) || \
114  !( HAVE_CLOCK_GETTIME ) || !( HAVE_DUP2 ) || !( HAVE_FORK ) || \
115  !( HAVE_FTRUNCATE ) || !( HAVE_GETCWD ) || !( HAVE_GETTIMEOFDAY ) || \
116  !( HAVE_MALLOC ) || !( HAVE_MBLEN ) || !( HAVE_MEMCHR ) || \
117  !( HAVE_MEMMOVE ) || !( HAVE_MEMSET ) || !( HAVE_MKDIR ) || \
118  !( HAVE_PRINTF ) || !( HAVE_REALLOC ) || \
119  !( HAVE_SELECT ) || !( HAVE_SETLOCALE ) || !( HAVE_STRCASECMP ) || \
120  !( HAVE_STRCHR ) || !( HAVE_STRNCASECMP ) || !( HAVE_STRRCHR ) || \
121  !( HAVE_STRSTR ) || !( HAVE_VFORK ) || !( HAVE_WORKING_FORK ) || \
122  !( HAVE_WORKING_VFORK ) || !( HAVE__BOOL ) || !( LSTAT_FOLLOWS_SLASHED_SYMLINK )
123 #error
124 #error configure script feature check 2 fail
125 #error critical features missing
126 #error
127 #endif // all that stuff
128 #endif // all that prior stuff
129 
130 #ifndef HAVE_BZERO
131 #define bzero(X,Y) memset((X),0,(Y))
132 #endif // !HAVE_BZERO
133 
134 
135 // DEBUG vs RELEASE code
136 
137 #ifdef DEBUG /* explicit DEBUG build */
138 #ifdef NO_DEBUG
139 #undef NO_DEBUG
140 #endif // NO_DEBUG
141 #endif // DEBUG
142 
143 // NOTE: The debug code will be included when NO_DEBUG is *NOT* defined
144 
145 
152 #define INVALID_HANDLE_VALUE ((int)-1)
153 
154 
159 //--------------------------------------
160 // branch optimization macros - gcc only
161 //--------------------------------------
162 
163 #define WB_UNLIKELY(x) (__builtin_expect (!!(x), 0))
164 #define WB_LIKELY(x) (__builtin_expect (!!(x), 1))
184 #define WB_INTERNAL_ATOM_MIN_VAL 0x3f000000L
195 typedef int WB_INT32;
196 
202 typedef unsigned int WB_UINT32;
203 
204 
205 #if defined(HAVE_LONGLONG) || defined(__DOXYGEN__) /* 'configure' tests for 'long long' datatype valid in configure script */
206 
210 #define HAS_WB_UINT64_BUILTIN
211 
212 
218 typedef long long WB_INT64;
219 
225 typedef unsigned long long WB_UINT64;
226 
227 #else // !defined HAVE_LONGLONG, unlikely (this part won't show up in doxygen either)
228 
229 typedef struct __WB_INT64__ { WB_UINT32 dw2; WB_INT32 dw1; } WB_INT64; // note 'dw1' is a signed value
230 typedef struct __WB_UINT64__ { WB_UINT32 dw2; WB_UINT32 dw1; } WB_UINT64;
231 
232 #endif // _LONGLONG
233 
234 #ifdef __DOXYGEN__
235 
240 typedef unsigned long long WB_UINTPTR;
241 #else /* regular code uses this next part */
242 
243 #if !defined(__SIZEOF_POINTER__) // TODO find a better way to deal with pointer size if this isn't defined
244 #define __SIZEOF_POINTER__ 0
245 #endif
246 
247 #ifdef __LP64__ /* TODO see what WIN32 vs WIN64 does */
248 typedef WB_UINT64 WB_UINTPTR;
249 #elif __SIZEOF_POINTER__ == 4 /* 4-byte pointer */
250 typedef WB_UINT32 WB_UINTPTR;
251 #else // assume long pointer
252 typedef WB_UINT64 WB_UINTPTR;
253 #endif // __LP64__
254 #endif // __DOXYGEN__
255 
256 
257 // pointer to integer conversion without those irritating truncation warnings
258 
259 
260 
261 
262 #define WB_C99_INITIALIZERS /* allow C99-style initializers */
263 
269 typedef void * WB_MODULE;
270 
276 typedef pthread_t WB_THREAD;
277 
283 typedef void (* WB_PROCADDRESS)(void);
284 
290 typedef pthread_key_t WB_THREAD_KEY;
291 
297 typedef WB_UINT32 WB_COND; // defined as 'WB_UINT32' because of pthread_cond problems under Linux
298 //typedef pthread_cond_t WB_COND;
299 
305 typedef pthread_mutex_t WB_MUTEX;
306 
307 
308 // TODO: sizeof(int) sizeof(long) - long is 64-bit for GNUC - MS compilers make it 32-bit
309 
310 
311 
312 #ifdef __DOXYGEN__
313 
319 #define __PACKED__ /* platform dependent; actual def must be a blank or doxygen barphs on it */
320 
321 #else // !__DOXYGEN__
322 
323 #define __PACKED__ __attribute__((__packed__))
324 
325 #endif // __DOXYGEN__
326 
327 #elif defined(_MSC_VER) /* Microsoft C/C++ compiler */
328 
329 // TODO: add proper support for MS compiler
330 #if _MSC_VER > 1300
331 
332 // TODO: specify correct version in which C99 initializers are supported
333 // as of MSC for ".Net" 2010 it's _NOT_ supported (still!)
334 //#define WB_C99_INITIALIZERS
335 
336 #endif // _MSC_VER > xxxx
337 
338 #define WB_UNLIKELY(x) (x)
339 #define WB_LIKELY(x) (x)
340 
341 #ifndef __inline__
342 #define __inline__ inline /* this assumes 'inline' is supported (MSC should support this) */
343 #endif // __inline__
344 
345 typedef __int64 WB_INT64;
346 typedef unsigned __int64 WB_UINT64;
347 typedef int WB_INT32;
348 typedef unsigned int WB_UINT32;
349 
350 // assume MS Windows Win32 API
351 typedef HMODULE WB_MODULE ; /* module handle */
352 typedef HANDLE WB_THREAD; /* thread handle - thread IDs are still 'int' types */
353 typedef FARPROC WB_PROCADDRESS; // generic proc address returned from GetProcAddress()
354 
355 typedef DWORD WBTHREAD_KEY; // return from 'TlsAlloc()'
356 typedef HANDLE WB_COND; // equivalent to an event handle
357 typedef HANDLE WB_MUTEX; // equivalent to a mutex handle
358 
359 
360 // TODO: sizeof(int) sizeof(long) - long is 32-bit for MSC
361 
362 // TODO: compatibility definition file for winders
363 
364 #define __PACKED__ /* TODO: a definition for packing in MS-land */
365 
366 #else // !defined(_MSVC_VER) && !defined(__GNUC__)
367 
368 #error unknown and/or unsupported compiler
369 
370 #define __PACKED__
371 
372 #endif // __GNUC__
373 
374 
375 // put standard '#define's and typedefs here, the ones that apply to EVERYBODY
376 
380 #define WB_SECURE_HASH_TIMEOUT 60000
382 typedef char * WB_PSTR;
383 typedef const char * WB_PCSTR;
384 
390 // //
392 // ____ _ _ _ _ ____ _ _ _ //
393 // / ___| | |_ __ _ _ __ | |_ _ _ _ __ / \ _ __ __| | / ___| | |__ _ _ | |_ __| | ___ __ __ _ __ //
394 // \___ \ | __|/ _` || '__|| __|| | | || '_ \ / _ \ | '_ \ / _` | \___ \ | '_ \ | | | || __|/ _` | / _ \\ \ /\ / /| '_ \ //
395 // ___) || |_| (_| || | | |_ | |_| || |_) | / ___ \ | | | || (_| | ___) || | | || |_| || |_| (_| || (_) |\ V V / | | | | //
396 // |____/ \__|\__,_||_| \__| \__,_|| .__/ /_/ \_\|_| |_| \__,_| |____/ |_| |_| \__,_| \__|\__,_| \___/ \_/\_/ |_| |_| //
397 // |_| //
398 // //
400 
417 extern int bQuitFlag;
418 
419 // these functions are internal-only, implemented in window_helper.c, but must be defined here
420 void __internal_startup_display(const char *szVal);
421 void __internal_startup_minimize(void);
422 void __internal_startup_maximize(void);
423 void __internal_startup_geometry(const char *szVal);
424 
425 
426 
427 // *******************************************
428 // STARTUP AND SHUTDOWN (must-call functions)
429 // *******************************************
430 
440 void WBPlatformOnInit(void);
441 
452 void WBPlatformOnExit(void);
453 
454 
469 int WBParseStandardArguments(int *pargc, char ***pargv, char ***penvp);
470 
476 void WBToolkitUsage(void);
477 
487 const char *GetStartupAppName(void);
488 
489 
490 
491 
493 // //
494 // __ __ _ _ _ _ _ //
495 // | \/ | ___ _ __ ___ ___ _ __ _ _ / \ | || | ___ ___ __ _ | |_ (_) ___ _ __ //
496 // | |\/| | / _ \| '_ ` _ \ / _ \ | '__|| | | | / _ \ | || | / _ \ / __|/ _` || __|| | / _ \ | '_ \ //
497 // | | | || __/| | | | | || (_) || | | |_| | / ___ \ | || || (_) || (__| (_| || |_ | || (_) || | | | //
498 // |_| |_| \___||_| |_| |_| \___/ |_| \__, | /_/ \_\|_||_| \___/ \___|\__,_| \__||_| \___/ |_| |_| //
499 // |___/ //
500 // //
502 
503 
504 // memory allocation (with debug support)
505 
514 void *WBAlloc(int nSize);
515 
524 void WBFree(void *pBuf);
525 
543 int WBAllocUsableSize(void *pBuf);
544 
554 void * WBReAlloc(void *pBuf, int nNewSize);
555 
565 void WBSubAllocTrashMasher(void);
566 
567 
568 // BASIC STRING UTILITIES
569 
570 // simple but helpful string utilities
571 
584 char *WBCopyString(const char *pSrc);
585 
600 char *WBCopyStringN(const char *pSrc, unsigned int nMaxChars);
601 
617 void WBCatString(char **ppDest, const char *pSrc);
618 
636 void WBCatStringN(char **ppDest, const char *pSrc, unsigned int nMaxChars);
637 
649 void WBDeQuoteString(char *pszStr); // de-quote a string in place
650 
663 void WBNormalizeXMLString(char *pString);
664 
678 int WBStringLineCount(const char *pSrc, unsigned int nMaxChars);
679 
693 const char *WBStringNextLine(const char *pSrc, unsigned int *pnMaxChars);
694 
695 
696 #if 0
697 
698 // THIS IS ALL RESERVED FOR FUTURE USE
699 // MAY NOT BE NEEDED IF I USE _Xmbtowc _Xwctomb and _Xwctomb
700 // X11 defines them as mblen(), mbtowc(), and wctomb()
701 // The alternative is to do something similar on WIN32, once that is implemented in the toolkit
702 // with '#ifdef blocks all around it
703 
721 int WBIsMultiByte(const char *pszStr);
722 
723 
735 XChar2b * WBConvertMultiByteTo16(const char *pszStr);
736 
747 char *WBConvertMultiByteFrom16(const XChar2b *pwzStr);
748 #endif // 0
749 
750 
752 // //
753 // __ __ ____ __ __ _ _ _ //
754 // \ \/ /| _ \ | \/ | | | (_)| |__ _ __ __ _ _ __ _ _ //
755 // \ / | |_) || |\/| | | | | || '_ \ | '__|/ _` || '__|| | | | //
756 // / \ | __/ | | | | | |___ | || |_) || | | (_| || | | |_| | //
757 // /_/\_\|_| |_| |_| |_____||_||_.__/ |_| \__,_||_| \__, | //
758 // |___/ //
759 // //
761 
762 
763 // XPM library (libXpm) and X11/xpm.h
764 
765 #if defined(X11WORKBENCH_TOOLKIT_HAVE_XPM) && !defined(__DOXYGEN__)
766 
767 // Doxygen doesn't need THIS part, it needs the other one.
768 
769 #include <X11/xpm.h>
770 
771 // no need for doxygen doc comments here, see '!defined(__DOXYGEN__)' above
772 // these definitions are for when libXpm is being used
773 #define XPM_ATTRIBUTES XpmAttributes
774 #define XPM_CREATE_PIXMAP_FROM_DATA(A,B,C,D,E,F) XpmCreatePixmapFromData(A,B,C,D,E,F)
775 #define XPM_FREE_ATTRIBUTES(pAttr) XpmFreeAttributes(pAttr)
776 
777 #else // !X11WORKBENCH_TOOLKIT_HAVE_XPM or __DOXYGEN__
778 
825 typedef struct _XPM_ATTRIBUTES_
826 {
827  // I only need certain information from MyLoadPixmapFromData(), so that's all I'm doing with this structure
828 
829  int width;
830  int height;
831  int depth;
832 
834 
835 
864 int MyLoadPixmapFromData(Display *pDisplay, Window wID, char *aData[],
865  Pixmap *pPixmap, Pixmap *pMask, XPM_ATTRIBUTES *pAttr);
866 
881 #define XPM_CREATE_PIXMAP_FROM_DATA(A,B,C,D,E,F) MyLoadPixmapFromData(A,B,C,D,E,F)
882 
894 #define XPM_FREE_ATTRIBUTES(pAttr) /* does nothing */
895 
896 
897 #endif
898 
899 
900 // some helpful macros that need to be universal without being in a different header
901 
911 #define NEXT_WORD(pX, pY, pZ) {while(*(pX) && *(pX) <= ' '){(pX)++;} (pY)=(pZ)=(pX); while(*(pX)>' '){(pX)++;} (pZ)=(pX);}
912 
913 
914 
915 
916 
917 #ifdef __cplusplus
918 extern "C" {
919 #endif // __cplusplus
920 
921 // common macros
922 
923 #ifndef FALSE
924 #define FALSE 0
925 #endif // FALSE
926 #ifndef TRUE
927 #define TRUE !0
928 #endif // TRUE
929 
930 
931 
932 // HANDLING qsort_r CALLING CONVENTION DIFFERENCES
933 //
934 #if defined(QSORT_R_BSD) && !defined(__DOXYGEN__)
935 
936 // DECLARE_SORT_FUNCTION based on - int (*compar)(void *, const void *, const void *)
937 // generates int fn_name(void *p0, const void *p1, const void *p2)
938 #define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(void *p0, const void *p1, const void *p2)
939 // void qsort_r(void *base, size_t nmemb, size_t size, void *thunk, int (*compar)(void *, const void *, const void *))
940 #define QSORT_R(A,B,C,D,E) qsort_r((A),(B),(C),(D),(E))
941 
942 #elif defined(QSORT_R_GNUC) && !defined(__DOXYGEN__)
943 
944 // DECLARE_SORT_FUNCTION based on typedef int (*__compar_d_fn_t) (__const void *, __const void *, void *)
945 // generates int fn_name(const void *p1, const void *p2, void *p0)
946 #define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(const void *p1, const void *p2, void *p0)
947 // extern void qsort_r (void *__base, size_t __nmemb, size_t __size, __compar_d_fn_t __compar, void *__arg)
948 #define QSORT_R(A,B,C,D,E) qsort_r((A),(B),(C),(E),(D))
949 
950 #else
951 
952 // here is where I implement 'vectored' quicksort for OTHER PLATFORMS
953 
967 void my_qsort_r(void *base, int nmemb, int size, void *thunk,
968  int (*compar)(void *, const void *, const void *));
969 
970 // the rest is exactly like the BSD version
971 
1004 #define DECLARE_SORT_FUNCTION(fn_name,p0,p1,p2) int fn_name(void *p0, const void *p1, const void *p2)
1005 
1006 
1020 #define QSORT_R(base,nmemb,size,thunk,compar) my_qsort_r((base),(nmemb),(size),(thunk),(compar))
1021 
1022 #endif
1023 
1024 
1026 // //
1027 // ___ _ _ //
1028 // |_ _| _ __ | |_ ___ _ __ _ __ __ _ | | //
1029 // | | | '_ \ | __|/ _ \| '__|| '_ \ / _` || | //
1030 // | | | | | || |_| __/| | | | | || (_| || | //
1031 // |___||_| |_| \__|\___||_| |_| |_| \__,_||_| //
1032 // //
1033 // //
1035 
1036 
1037 // *********************************
1038 // INTERNAL memory/security helpers
1039 // *********************************
1040 
1066 WB_UINT32 WBCreatePointerHash(void *pPointer);
1067 
1084 void WBDestroyPointerHash(WB_UINT32 uiHash);
1085 
1102 void WBDestroyPointerHashPtr(void *pPointer);
1103 
1122 void * WBGetPointerFromHash(WB_UINT32 uiHash);
1123 
1124 
1125 
1127 // //
1128 // _ _ //
1129 // / \ | |_ ___ _ __ ___ ___ //
1130 // / _ \ | __|/ _ \ | '_ ` _ \ / __| //
1131 // / ___ \| |_| (_) || | | | | |\__ \ //
1132 // /_/ \_\\__|\___/ |_| |_| |_||___/ //
1133 // //
1134 // //
1136 
1137 //-----------------------------------------
1138 // ATOM HELPERS (internally-defined atoms)
1139 //-----------------------------------------
1140 
1141 
1165 Atom WBGetAtom(Display *pDisplay, const char *szAtomName);
1166 
1194 Atom WBLookupAtom(Display *pDisplay, const char *szAtomName);
1195 
1216 char * WBGetAtomName(Display *pDisplay, Atom aAtom);
1217 
1218 
1219 
1220 
1222 // //
1223 // ____ _ _ _ _____ _____ _ _ //
1224 // | _ \ __ _ | |_ | |__ ___ __ _ _ __ __| | |_ _|___ _ __ ___ _ __ | ___|(_)| | ___ ___ //
1225 // | |_) |/ _` || __|| '_ \ / __| / _` || '_ \ / _` | | | / _ \| '_ ` _ \ | '_ \ | |_ | || | / _ \/ __| //
1226 // | __/| (_| || |_ | | | |\__ \ | (_| || | | || (_| | | || __/| | | | | || |_) | | _| | || || __/\__ \ //
1227 // |_| \__,_| \__||_| |_||___/ \__,_||_| |_| \__,_| |_| \___||_| |_| |_|| .__/ |_| |_||_| \___||___/ //
1228 // |_| //
1229 // //
1231 
1232 // *******************************************
1233 // FILE/APPLICATION SEARCH PATH AND TEMP FILES
1234 // *******************************************
1235 
1250 char * WBSearchPath(const char *szFileName);
1251 
1270 char * WBTempFile(const char *szExt);
1271 
1272 
1287 char * WBTempFile0(const char *szExt);
1288 
1289 
1290 
1292 // //
1293 // _____ _ _ _ _ _ _ _ //
1294 // | ____|__ __| |_ ___ _ __ _ __ __ _ | | / \ _ __ _ __ | |(_) ___ __ _ | |_ (_) ___ _ __ ___ //
1295 // | _| \ \/ /| __|/ _ \| '__|| '_ \ / _` || | / _ \ | '_ \ | '_ \ | || | / __|/ _` || __|| | / _ \ | '_ \ / __| //
1296 // | |___ > < | |_| __/| | | | | || (_| || | / ___ \ | |_) || |_) || || || (__| (_| || |_ | || (_) || | | |\__ \ //
1297 // |_____|/_/\_\ \__|\___||_| |_| |_| \__,_||_| /_/ \_\| .__/ | .__/ |_||_| \___|\__,_| \__||_| \___/ |_| |_||___/ //
1298 // |_| |_| //
1299 // //
1300 // _ _ ____ //
1301 // / \ _ __ __| | | _ \ _ __ ___ ___ ___ ___ ___ ___ ___ //
1302 // / _ \ | '_ \ / _` | | |_) || '__|/ _ \ / __|/ _ \/ __|/ __| / _ \/ __| //
1303 // / ___ \ | | | || (_| | | __/ | | | (_) || (__| __/\__ \\__ \| __/\__ \ //
1304 // /_/ \_\|_| |_| \__,_| |_| |_| \___/ \___|\___||___/|___/ \___||___/ //
1305 // //
1307 
1308 // *********************
1309 // SPAWNING APPLICATIONS
1310 // *********************
1311 
1312 #ifdef WIN32
1313 #define WB_FILE_HANDLE HANDLE
1314 #define WB_PROCESS_ID HANDLE
1315 #define WB_INVALID_FILE_HANDLE INVALID_HANDLE_VALUE
1316 #else // !WIN32
1317 #define WB_FILE_HANDLE int
1318 #define WB_PROCESS_ID unsigned int
1319 #define WB_INVALID_FILE_HANDLE -1
1320 #endif // WIN32
1321 
1335 WB_PROCESS_ID WBRunAsync(const char *szAppName, ...);
1336 
1354 char * WBRunResult(const char *szAppName, ...);
1355 
1378 char * WBRunResultPipe(const char *szStdInBuf, const char *szAppName, ...);
1379 
1380 
1406 WB_PROCESS_ID WBRunAsyncPipe(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr,
1407  const char *szAppName, ...);
1408 
1409 
1440 WB_PROCESS_ID WBRunAsyncPipeV(WB_FILE_HANDLE hStdIn, WB_FILE_HANDLE hStdOut, WB_FILE_HANDLE hStdErr,
1441  const char *szAppName, va_list va);
1442 
1443 
1444 
1445 
1447 // ____ _ _ _ ____ _____ ____ _ ___ ____ ____ //
1448 // / ___|| | | | / \ | _ \| ____| _ \ | | |_ _| __ ) ___| //
1449 // \___ \| |_| | / _ \ | |_) | _| | | | | | | | || _ \___ \ //
1450 // ___) | _ |/ ___ \| _ <| |___| |_| | | |___ | || |_) |__) | //
1451 // |____/|_| |_/_/ \_\_| \_\_____|____/ |_____|___|____/____/ //
1452 // //
1454 
1465 WB_MODULE WBLoadLibrary(const char *szModuleName); // load a library module (shared lib, DLL, whatever)
1466 
1476 void WBFreeLibrary(WB_MODULE hModule);
1477 
1489 WB_PROCADDRESS WBGetProcAddress(WB_MODULE hModule, const char *szProcName);
1490 
1491 
1492 
1494 // _____ _ _ ____ _____ _ ____ ____ //
1495 // |_ _| | | | _ \| ____| / \ | _ \/ ___| //
1496 // | | | |_| | |_) | _| / _ \ | | | \___ \ //
1497 // | | | _ | _ <| |___ / ___ \| |_| |___) | //
1498 // |_| |_| |_|_| \_\_____/_/ \_\____/|____/ //
1499 // //
1501 
1512 
1522 void WBThreadFreeLocal(WB_THREAD_KEY keyVal);
1523 
1534 void * WBThreadGetLocal(WB_THREAD_KEY keyVal);
1535 
1546 void WBThreadSetLocal(WB_THREAD_KEY keyVal, void *pValue);
1547 
1548 
1549 // simplified thread support (cross-platform)
1550 
1562 
1574 WB_THREAD WBThreadCreate(void *(*function)(void *), void *pParam);
1575 
1587 void *WBThreadWait(WB_THREAD hThread); // closes hThread, returns exit code, waits for thread to terminate (blocks)
1588 
1602 int WBThreadRunning(WB_THREAD hThread);
1603 
1615 void WBThreadExit(void *pRval);
1616 
1630 void WBThreadClose(WB_THREAD hThread);
1631 
1632 
1644 int WBCondCreate(WB_COND *pCond);
1645 
1656 int WBMutexCreate(WB_MUTEX *pMtx);
1657 
1667 void WBCondFree(WB_COND *pCond);
1668 
1678 void WBMutexFree(WB_MUTEX *pMtx);
1679 
1693 int WBMutexLock(WB_MUTEX *pMtx, int nTimeout);
1694 
1705 int WBMutexUnlock(WB_MUTEX *pMtx);
1706 
1718 int WBCondSignal(WB_COND *pCond);
1719 
1732 int WBCondWait(WB_COND *pCond, int nTimeout);
1733 
1752 int WBCondWaitMutex(WB_COND *pCond, WB_MUTEX *pMtx, int nTimeout);
1753 
1754 
1767 WB_UINT32 WBInterlockedDecrement(volatile WB_UINT32 *pValue);
1768 
1769 
1782 WB_UINT32 WBInterlockedIncrement(volatile WB_UINT32 *pValue);
1783 
1784 
1799 WB_UINT32 WBInterlockedExchange(volatile WB_UINT32 *pValue, WB_UINT32 nNewVal);
1800 
1801 
1815 WB_UINT32 WBInterlockedRead(volatile WB_UINT32 *pValue);
1816 
1817 
1818 
1820 // ____ ____ ___ _ _ _____ ___ _ _ ____ //
1821 // | _ \| _ \|_ _| \ | |_ _|_ _| \ | |/ ___| //
1822 // | |_) | |_) || || \| | | | | || \| | | _ //
1823 // | __/| _ < | || |\ | | | | || |\ | |_| | //
1824 // |_| |_| \_\___|_| \_| |_| |___|_| \_|\____| //
1825 // //
1827 
1828 // NOTE: the POSIX world uses postscript, particularly with CUPS. So does this library.
1829 
1857 int WBPrintPostScriptFile(const char *szPrinterName, const char *szFileName);
1858 
1877 char *WBGetPrinterList(void);
1878 
1879 // TODO: complete IPP support for cups and network-capable printers
1880 
1881 // TODO: printer capabilities in a binary structure
1882 
1883 // TODO: support for port 515 'printer' TCP/UDP printer services (i.e. cups-lpd or lpd)
1884 
1885 // TODO: dynamically load CUPS API when available. see 'cups-config' application docs
1886 
1887 
1888 
1889 #ifdef __cplusplus
1890 };
1891 #endif // __cplusplus
1892 
1893 
1894 #endif // _PLATFORM_HELPER_H_INCLDUED_
1895 
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)
WB_THREAD_KEY WBThreadAllocLocal(void)
Allocate &#39;thread local&#39; storage.
void * WBGetPointerFromHash(WB_UINT32 uiHash)
Obtain a pointer from a 32-bit &#39;secure&#39; pointer hash value.
int bQuitFlag
&#39;Quit&#39; Flag - you should check this periodically in your main (message) loop and exit whenever it is ...
void(* WB_PROCADDRESS)(void)
PROC ADDRESS equivalent.
Atom WBLookupAtom(Display *pDisplay, const char *szAtomName)
Lookup (but do not allocate) an internal (or X11) Atom for a named string.
void WBThreadFreeLocal(WB_THREAD_KEY keyVal)
Free &#39;thread local&#39; storage allocated by WBThreadAllocLocal()
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.
int WB_INT32
Platform abstract 32-bit integer.
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...
char * WBTempFile0(const char *szExt)
Get the name for a new, unique temporary file, creating the file in the process.
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.
char * WBSearchPath(const char *szFileName)
Run an application asynchronously.
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.
pthread_mutex_t WB_MUTEX
MUTEX HANDLE equivalent.
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.
unsigned long long WB_UINT64
Platform abstract unsigned 64-bit integer.
void * WBReAlloc(void *pBuf, int nNewSize)
High performance memory sub-allocator &#39;re-allocate&#39;.
WB_UINT32 WBCreatePointerHash(void *pPointer)
Create/obtain a 32-bit &#39;secure&#39; hash for a pointer.
void * WB_MODULE
MODULE HANDLE equivalent.
int depth
depth of the returned &#39;image&#39; pixmap. The mask pixmap always has a depth of &#39;1&#39;.
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_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.
unsigned int WB_UINT32
Platform abstract unsigned 32-bit integer.
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 * WBAlloc(int nSize)
High performance memory sub-allocator &#39;allocate&#39;.
int WBCondSignal(WB_COND *pCond)
Signal a condition (event)
WB_PROCESS_ID WBRunAsync(const char *szAppName,...)
Run an application asynchronously.
char * WBGetPrinterList(void)
Get a list of printer names.
WB_THREAD WBThreadGetCurrent(void)
Get &#39;current thread&#39; identifier.
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;.
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.
void WBDestroyPointerHashPtr(void *pPointer)
Destroy a 32-bit &#39;secure&#39; hash for a pointer regardless of reference count.
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;.
pthread_t WB_THREAD
THREAD HANDLE equivalent.
void WBDestroyPointerHash(WB_UINT32 uiHash)
Destroy a 32-bit &#39;secure&#39; hash for a pointer.
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...
pthread_key_t WB_THREAD_KEY
THREAD LOCAL STORAGE &#39;key&#39; equivalent.
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...
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.
char * WBGetAtomName(Display *pDisplay, Atom aAtom)
Lookup and/or allocate an internal Atom for a named string.
int WBCondWait(WB_COND *pCond, int nTimeout)
Wait for a signal on a condition (event)
void WBMutexFree(WB_MUTEX *pMtx)
Free a lockable mutex.
int height
height of the returned pixmaps
WB_UINT32 WB_COND
CONDITION HANDLE equivalent (similar to an &#39;event&#39;)
unsigned long long WB_UINTPTR
Platform abstract unsigned integer that matches pointer size.
int width
The width of the returned pixmaps.
long long WB_INT64
Platform abstract 64-bit integer.
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.
Atom WBGetAtom(Display *pDisplay, const char *szAtomName)
Lookup and/or allocate an internal Atom for a named string (lookups include X11 atoms) ...
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.