X11 Work Bench Toolkit  1.0
Platform-specific 'Helper' Functions and Definitions

Macros

#define INVALID_HANDLE_VALUE
 INVALID HANDLE VALUE equivalent. More...
 
#define HAS_WB_UINT64_BUILTIN
 defined whenever the 'WB_UINT64' data type is a 'built in' data type
 
#define __PACKED__   /* platform dependent; actual def must be a blank or doxygen barphs on it */
 PACKED definition. More...
 
#define DECLARE_SORT_FUNCTION(fn_name, p0, p1, p2)   int fn_name(void *p0, const void *p1, const void *p2)
 Wrapper to declare a sort function for QSORT_R. More...
 
#define QSORT_R(base, nmemb, size, thunk, compar)   my_qsort_r((base),(nmemb),(size),(thunk),(compar))
 Local implementation of qsort_r() for operating systems that do not have it. More...
 

Typedefs

typedef int WB_INT32
 Platform abstract 32-bit integer. More...
 
typedef unsigned int WB_UINT32
 Platform abstract unsigned 32-bit integer. More...
 
typedef long long WB_INT64
 Platform abstract 64-bit integer. More...
 
typedef unsigned long long WB_UINT64
 Platform abstract unsigned 64-bit integer. More...
 
typedef void * WB_MODULE
 MODULE HANDLE equivalent. More...
 
typedef pthread_t WB_THREAD
 THREAD HANDLE equivalent. More...
 
typedef void(* WB_PROCADDRESS )(void)
 PROC ADDRESS equivalent. More...
 
typedef pthread_key_t WB_THREAD_KEY
 THREAD LOCAL STORAGE 'key' equivalent. More...
 
typedef WB_UINT32 WB_COND
 CONDITION HANDLE equivalent (similar to an 'event') More...
 
typedef pthread_mutex_t WB_MUTEX
 MUTEX HANDLE equivalent. More...
 

Functions

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. More...
 
WB_UINT32 WBCreatePointerHash (void *pPointer)
 Create/obtain a 32-bit 'secure' hash for a pointer. More...
 
void WBDestroyPointerHash (WB_UINT32 uiHash)
 Destroy a 32-bit 'secure' hash for a pointer. More...
 
void * WBGetPointerFromHash (WB_UINT32 uiHash)
 Obtain a pointer from a 32-bit 'secure' pointer hash value. More...
 
Atom WBGetAtom (Display *pDisplay, const char *szAtomName)
 Lookup and/or allocate an internal Atom for a named string (lookups include X11 atoms) More...
 
Atom WBLookupAtom (Display *pDisplay, const char *szAtomName)
 Lookup (but do not allocate) an internal (or X11) Atom for a named string. More...
 
char * WBGetAtomName (Display *pDisplay, Atom aAtom)
 Lookup and/or allocate an internal Atom for a named string. More...
 
char * WBSearchPath (const char *szFileName)
 Run an application asynchronously. More...
 
char * WBTempFile (const char *szExt)
 Get the name for a new, unique temporary file, creating the file in the process, and save its name for later deletion. More...
 
char * WBTempFile0 (const char *szExt)
 Get the name for a new, unique temporary file, creating the file in the process. More...
 
#define WB_UNLIKELY(x)   (__builtin_expect (!!(x), 0))
 
#define WB_LIKELY(x)   (__builtin_expect (!!(x), 1))
 
#define WB_INTERNAL_ATOM_MIN_VAL   0x3f000000L
 The minimum 'internal' Atom value used by the toolkit. More...
 
typedef char * WB_PSTR
 pointer to char string - a convenience typedef
 
typedef const char * WB_PCSTR
 pointer to const char string - a convenience typedef
 
#define WB_SECURE_HASH_TIMEOUT   60000
 

Detailed Description

Some functions either need special help on certain platforms, or are missing entirely. In other cases, the manner in which a function is implemented is very specific for a particular platform. Additionally, common definitions change from one platform to another. The functions and definitions in this group deal with these specific problems.

Macro Definition Documentation

#define __PACKED__   /* platform dependent; actual def must be a blank or doxygen barphs on it */

PACKED definition.

This assignes the 'packed' attribute; i.e. byte-level alignment

Definition at line 249 of file platform_helper.h.

#define DECLARE_SORT_FUNCTION (   fn_name,
  p0,
  p1,
  p2 
)    int fn_name(void *p0, const void *p1, const void *p2)

Wrapper to declare a sort function for QSORT_R.

Parameters
fn_nameThe function name
p0The 'thunk' parameter passed in by QSORT_R
p1The first compare parameter
p2The second compare parameter

Use this wrapper macro to properly declare a compare function for QSORT_R, similar to the following example:

DECLARE_SORT_FUNCTION(MySort,pThunk,pParam1,pParam2)
{
const char **pStringArray = (const char **)pThunk; // the real data
const int *pP1 = (const int *)pParam1;
const int *pP2 = (const int *)pParam2;
// I am sorting integer indices into an array of character strings so
// that I can sort the integers and not the actual strings. But I needed
// a pointer to my string array, so I pass that in as 'pThunk'.
return strcmp(pStringArray[*pP1],pStringArray[*pP2]);
}

this helps resolve the known platform differences in qsort_r() for POSIX systems

See Also
QSORT_R

Definition at line 795 of file platform_helper.h.

#define INVALID_HANDLE_VALUE

INVALID HANDLE VALUE equivalent.

This definition generically refers to an INVALID HANDLE, more specifically a FILE or SOCKET handle on POSIX systems

Definition at line 109 of file platform_helper.h.

#define QSORT_R (   base,
  nmemb,
  size,
  thunk,
  compar 
)    my_qsort_r((base),(nmemb),(size),(thunk),(compar))

Local implementation of qsort_r() for operating systems that do not have it.

Parameters
basePointer to 'base' of items to sort
nmembNumber of members to sort
sizeSize of a single member (including any padding)
thunkThe value to pass along as the first parameter to 'compar'
comparThe comparison function, declared using DECLARE_SORT_FUNCTION

Use this UNIVERSALLY whenever you need to use qsort_r(), as it is platform independent and deals with the incompatibilities associated with the BSD version and the Linux version, as well as implementing qsort_r() for systems that do not support it directly.

Definition at line 811 of file platform_helper.h.

#define WB_INTERNAL_ATOM_MIN_VAL   0x3f000000L

The minimum 'internal' Atom value used by the toolkit.

This is the minimum 'internal' Atom value that is used by the toolkit. Atoms that are allocated via XInternAtom() will have a value that is LESS than WB_INTERNAL_ATOM_MIN_VAL, and anything allocated via WBGetAtom() will have a value that is GREATER THAN OR EQUAL to WB_INTERNAL_ATOM_MIN_VAL.

Use of this constant to determine 'internal' from 'X11' Atoms is based on the source code for the Xorg X11 server, which uses the function 'MakeAtom()' (in 'dix/atom.c') to allocate new atoms. These values are assigned SEQUENTIALLY, beginning with 'XA_LAST_PREDEFINED+1' and continuing from there. A value of this magnitude allows for about 1 billion Atom allocations before 'hitting the limit'. (having that many atoms would negatively impact the X windows system)

In the future, it is possible that an Atom MAY have a randomly assigned value, or a value assigned that clashes with this definition. In such a case, a major re-write might be needed to correct for it.

NOTE: This value must NOT include any of the bits 'Or'd with an Atom within a menu, such as 'WBMENU_POPUP_HIGH_BIT' or 'WBMENU_DYNAMIC_HIGH_BIT'. Otherwise, THAT architecture would need to be modified as well.the minimum 'internal' Atom value used by the toolkit

Definition at line 141 of file platform_helper.h.

#define WB_LIKELY (   x)    (__builtin_expect (!!(x), 1))

optimization for code branching when condition is 'likely'. use within conditionals

Definition at line 121 of file platform_helper.h.

#define WB_SECURE_HASH_TIMEOUT   60000

'secure hash' maximum lifetime, in milliseconds

Definition at line 310 of file platform_helper.h.

#define WB_UNLIKELY (   x)    (__builtin_expect (!!(x), 0))

optimization for code branching when condition is 'unlikely'. use within conditionals

Definition at line 120 of file platform_helper.h.

Typedef Documentation

typedef WB_UINT32 WB_COND

CONDITION HANDLE equivalent (similar to an 'event')

This 'typedef' refers to a CONDITION, a triggerable synchronization resource

Definition at line 227 of file platform_helper.h.

typedef int WB_INT32

Platform abstract 32-bit integer.

This definition identifies the data type for a 32-bit integer

Definition at line 152 of file platform_helper.h.

typedef long long WB_INT64

Platform abstract 64-bit integer.

This definition identifies the data type for a 64-bit integer

Definition at line 175 of file platform_helper.h.

typedef void* WB_MODULE

MODULE HANDLE equivalent.

This 'typedef' refers to a MODULE

Definition at line 199 of file platform_helper.h.

typedef pthread_mutex_t WB_MUTEX

MUTEX HANDLE equivalent.

This 'typedef' refers to a MUTEX, a lockable synchronization object

Definition at line 235 of file platform_helper.h.

typedef void(* WB_PROCADDRESS)(void)

PROC ADDRESS equivalent.

This 'typedef' refers to a PROC ADDRESS as exported from a shared library

Definition at line 213 of file platform_helper.h.

typedef pthread_t WB_THREAD

THREAD HANDLE equivalent.

This 'typedef' refers to a THREAD

Definition at line 206 of file platform_helper.h.

typedef pthread_key_t WB_THREAD_KEY

THREAD LOCAL STORAGE 'key' equivalent.

This 'typedef' refers to a THREAD LOCAL STORAGE key, identifying a storage slot

Definition at line 220 of file platform_helper.h.

typedef unsigned int WB_UINT32

Platform abstract unsigned 32-bit integer.

This definition identifies the data type for an unsigned 32-bit integer

Definition at line 159 of file platform_helper.h.

typedef unsigned long long WB_UINT64

Platform abstract unsigned 64-bit integer.

This definition identifies the data type for an unsigned 64-bit integer

Definition at line 182 of file platform_helper.h.

Function Documentation

void my_qsort_r ( void *  base,
int  nmemb,
int  size,
void *  thunk,
int(*)(void *, const void *, const void *)  compar 
)

Local implementation of qsort_r() for operating systems that do not have it.

Parameters
basePointer to 'base' of items to sort
nmembNumber of members to sort
sizeSize of a single member (including any padding)
thunkThe value to pass along as the first parameter to 'compar'
comparThe comparison function, declared using DECLARE_SORT_FUNCTION

This function implements the QSORT_R macro when there is no libc function for qsort_r()

Header File: platform_helper.h

Definition at line 1348 of file platform_helper.c.

WB_UINT32 WBCreatePointerHash ( void *  pPointer)

Create/obtain a 32-bit 'secure' hash for a pointer.

Parameters
pPointerA pointer to memory that remains valid after the call
Returns
An allocated 'hash' to the pointer. The hash should be free'd after use.

This function will create a 'secure' hash for a pointer. The hash can be used asynchronously for up to WB_SECURE_HASH_TIMEOUT milliseconds, after which it the reference automatically be free'd. In this way, an asynchronous message can contain references to pointers that are difficult to 'fake' if another application were to attempt to inject Events into the queue.

NOTE: automatically freeing the reference does NOT free the pointer. Failure to handle these correctly can result in memory leaks, but THAT is preferable to security vulnerabilities

If the same pointer is used more than once in a call to this function, and the hash is still 'valid', the same hash will be returned as before, but with a higher (internal) reference count. The timeout threshold will be reset using the current request time. This makes it 'thread safe'.

Passing a pointer asynchronously via a hash, particularly across thread boundaries, SHOULD implement its own method of reference counting to avoid re-using a pointer after the memory has been free'd. If you do not queue the message, this becomes less important. In any case, care needs to be taken to avoid using a pointer after it has been free'd.

Header File: platform_helper.h

Definition at line 858 of file platform_helper.c.

void WBDestroyPointerHash ( WB_UINT32  uiHash)

Destroy a 32-bit 'secure' hash for a pointer.

Parameters
uiHashThe 'hash' value created by WBCreatePointerHash()

This function will destroy a 'secure' hash for a pointer that was created by WBCreatePointerHash()

NOTE: destroying the hash reference does NOT free the pointer. Failure to handle these correctly can result in memory leaks, but that is preferable to security vulnerabilities

You should call this function immediately, once you have completed using the 'secure' pointer hash.

Header File: platform_helper.h

Definition at line 977 of file platform_helper.c.

Atom WBGetAtom ( Display *  pDisplay,
const char *  szAtomName 
)

Lookup and/or allocate an internal Atom for a named string (lookups include X11 atoms)

Parameters
pDisplayThe display to search for a matching X11 Atom
szAtomNameThe text 'Atom name' to search (and optionally create) for an Atom
Returns
An Atom representing the specified szAtomName. For values less than WB_INTERNAL_ATOM_MIN_VAL, it will be an X11 Atom. Otherwise, the value will be 'internal only'

This function will lookup and/or allocate an internal Atom based on the specified Atom name. If the Atom name exists as an X11 Atom, or already exists as an internal atom, the function will return that value. Otherwise, this function will return an allocated Atom with a value >= WB_INTERNAL_ATOM_MIN_VAL.

NOTE: If an X11 Atom with a matching name exists, along with an 'internal' definition, the internal definition will be returned. This is to prevent problems with a 'race condition' on an atom name.

If you need a globally defined atom with the matching name, use 'XInternAtom' instead. Internally defined atoms must never be used with other applications, window properties, or the window manager.

The X11 workbench toolkit makes use of Atoms for menu and dialog box events. To prevent flooding the X11 server with a lot of unnecessary proprietary Atom names, this function lets X11 workbench continue to use the Atom paradigm while simultaneously keeping its own separate, private list of Atoms.

Header File: platform_helper.h

Definition at line 1078 of file platform_helper.c.

char* WBGetAtomName ( Display *  pDisplay,
Atom  aAtom 
)

Lookup and/or allocate an internal Atom for a named string.

Parameters
pDisplayThe display to search for a matching X11 Atom
aAtomThe Atom to return the text for
Returns
An allocated pointer containing the 'Atom name' text string. This pointer will need to be free'd using WBFree() (it is created via 'WBCopyString()')

This function returns the Atom name (as an allocated character string) associate with the specified Atom, whether the Atom is an X11 Atom or an internal 'X11 workbench toolkit' Atom.

The X11 workbench toolkit makes use of Atoms for menu and dialog box events. To prevent flooding the X11 server with a lot of unnecessary proprietary Atom names, this function lets X11 workbench continue to use the Atom paradigm while simultaneously keeping its own separate, private list of Atoms. This function is intended to be compatible with the X11 function 'XGetAtomName()' to simplify the implementation of the application's code.

A non-NULL return value must be free'd using 'WBFree()' rather than 'XFree()' (as it would have been with 'XGetAtomName()'). This is primarily for future cross-platform compatibility.

Header File: platform_helper.h

Definition at line 1259 of file platform_helper.c.

void* WBGetPointerFromHash ( WB_UINT32  uiHash)

Obtain a pointer from a 32-bit 'secure' pointer hash value.

Parameters
uiHashThe 'hash' value created by WBCreatePointerHash()
Returns
An allocated 'hash' to the pointer, or NULL if not valid. The hash should be destroyed immediately after use.

This function will create a 'secure' hash for a pointer. The hash can be used asynchronously for up to WB_SECURE_HASH_TIMEOUT milliseconds, after which it the reference automatically be free'd. In this way, an asynchronous message can contain references to pointers that are difficult to 'fake' if another application were to attempt to inject Events into the queue.

NOTE: automatically freeing the reference does NOT free the pointer. Failure to handle these correctly can result in memory leaks, but that is preferable to security vulnerabilities

Header File: platform_helper.h

Definition at line 1004 of file platform_helper.c.

Atom WBLookupAtom ( Display *  pDisplay,
const char *  szAtomName 
)

Lookup (but do not allocate) an internal (or X11) Atom for a named string.

Parameters
pDisplayThe display to search for a matching X11 Atom
szAtomNameThe text 'Atom name' to search for an Atom
Returns
An Atom representing the specified szAtomName. For values less than WB_INTERNAL_ATOM_MIN_VAL, it will be an X11 Atom. Otherwise, the value will be 'internal only'

If an atom is not found, this function will return 'None'. It does not allocate a new atom.

This function will lookup an internal (or X11) Atom based on the specified Atom name. If the Atom name exists as an X11 Atom, or already exists as an internal atom, the function will return that value. Otherwise, this function will return 'None'.

An internal atom will have a value >= WB_INTERNAL_ATOM_MIN_VAL

NOTE: If an X11 Atom with a matching name exists, along with an 'internal' definition, the internal definition will be returned. This is to prevent problems with a 'race condition' on an atom name.

If you need a globally defined atom with the matching name, use 'XInternAtom' instead. Internally defined atoms must never be used with other applications, window properties, or the window manager.

The X11 workbench toolkit makes use of Atoms for menu and dialog box events. To prevent flooding the X11 server with a lot of unnecessary proprietary Atom names, this function lets X11 workbench continue to use the Atom paradigm while simultaneously keeping its own separate, private list of Atoms.

Header File: platform_helper.h

Definition at line 1200 of file platform_helper.c.

char* WBSearchPath ( const char *  szFileName)

Run an application asynchronously.

Parameters
szFileNameA const pointer to a character string containing a file or path name
Returns
A 'WBAlloc() pointer to a character string containing the ACTUAL path to the file

This function locates a file using the PATH environment variable and the value of 'szFileName' by testing the file (or directory name) using 'stat'. When the file (or directory) is located, this function returns the path name as a 'WBAlloc() string. If the file (or directory) cannot be located, the function returns NULL.
The caller must 'WBFree()' any non-NULL pointer returned by this function.

Header File: platform_helper.h

Definition at line 2189 of file platform_helper.c.

char* WBTempFile ( const char *  szExt)

Get the name for a new, unique temporary file, creating the file in the process, and save its name for later deletion.

Parameters
szExtA const pointer to a string containing the file's extension (without the '.'), or NULL if no extension is desired.
Returns
A 'WBAlloc() pointer to a character string containing fully qualified path to the file

This function obtains a unique temporary file name and then creates the file with a zero length, returning the name of the file in a WBAlloc() character string. On error, it returns NULL.
The actual location of the temporary file depends upon platform-specific parameters, such as environment variables and system settings.
The caller must 'WBFree()' any non-NULL pointer returned by this function.
This function preserves the name of the file in a list of temporary files that need to be deleted once the application has terminated. This way an external application can keep the file open indefinitely, or even re-read the file, without negative effects. The 'WBPlatformOnExit()' function will delete all temporary files that have been previously created by 'WBTempFile'.

Header File: platform_helper.h

Definition at line 2446 of file platform_helper.c.

char* WBTempFile0 ( const char *  szExt)

Get the name for a new, unique temporary file, creating the file in the process.

Parameters
szExtA const pointer to a string containing the file's extension (without the '.'), or NULL if no extension is desired.
Returns
A 'WBAlloc() pointer to a character string containing fully qualified path to the file

This function obtains a unique temporary file name and then creates the file with a zero length, returning the name of the file in a WBAlloc() character string. On error, it returns NULL.
The actual location of the temporary file depends upon platform-specific parameters, such as environment variables and system settings.
The caller must 'WBFree()' any non-NULL pointer returned by this function.

Header File: platform_helper.h

Definition at line 2330 of file platform_helper.c.