Functions

Functions
WB_UINT64	WBGetTimeIndex (void)
	Returns the current 'time index' (in microseconds) More...
void	WBDelay (uint32_t uiDelay)
	Delay for a specified period in microseconds. More...
int	WBCPUCount (void)
	Get the number of available CPU cores. More...
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	WBDestroyPointerHashPtr (void *pPointer)
	Destroy a 32-bit 'secure' hash for a pointer regardless of reference count. 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...
int	WBMkDir (const char *szFileName, int flags)
	a wrapper for 'mkdir' that makes directories recursively (as needed) More...
char *	WBSearchPath (const char *szFileName)
	search for a file using the PATH environment variable 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...

Detailed Description

Function Documentation

my_qsort_r()

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

base	Pointer to 'base' of items to sort
nmemb	Number of members to sort
size	Size of a single member (including any padding)
thunk	The value to pass along as the first parameter to 'compar'
compar	The 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 2600 of file platform_helper.c.

WBCPUCount()

int WBCPUCount

(

void

)

Get the number of available CPU cores.

Returns

The total number of available CPU cores on the system. On a VM, only those cores that have been assigned to the VM will be counted.

A generic delay utility that returns the total number of available cores on the system. This may be useful when determining how to divide up a parallel algorithm, for example.

If the number of available cores is not known or cannot be determined for some reason, this function returns a value of 0.

Header File: platform_helper.h

Definition at line 1068 of file platform_helper.c.

WBCreatePointerHash()

WB_UINT32 WBCreatePointerHash

(

void *

pPointer

)

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

Parameters

pPointer

A 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 the reference will 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 1902 of file platform_helper.c.

WBDelay()

void WBDelay

(

uint32_t

uiDelay

)

Delay for a specified period in microseconds.

Parameters

uiDelay

The delay period, in microseconds

A generic delay utility that will use 'nanosleep' (when available), or some other means (such as 'usleep') when it is not. On systems that do not support microsecond resolution on delays, this function will always delay at least one millisecond. On some systems, this delay may be interruptible. For exact timing, a non-interruptible loop that times execution by counting CPU instructions shyould be used instead. This function is approximate only.

Header File: platform_helper.h

Definition at line 1042 of file platform_helper.c.

WBDestroyPointerHash()

void WBDestroyPointerHash

(

WB_UINT32

uiHash

)

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

Parameters

uiHash

The 'hash' value created by WBCreatePointerHash()

This function will reduce the reference count on a 'secure' hash for a pointer that was created by WBCreatePointerHash(). When the reference count reaches zero, the hash itself will be destroyed.

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 a 'secure' pointer hash, particularly if it was received as part of an Event. In some cases, this will be done for you, such as via WBWindowDispatch() with certain ClientMessage events. In other cases, you will have to explicitly do this yourself.

If you have physically free'd (or otherwise invalidated) a hashed pointer, you should call WBDestroyPointerHashPtr() so that a hash for that pointer will not exist.

Header File: platform_helper.h

Definition at line 2073 of file platform_helper.c.

WBDestroyPointerHashPtr()

void WBDestroyPointerHashPtr

(

void *

pPointer

)

Destroy a 32-bit 'secure' hash for a pointer regardless of reference count.

Parameters

pPointer

A pointer for which a hash may exist

This function will destroy a 'secure' hash for a pointer that was created by WBCreatePointerHash(), regardless of the reference count. The hash will remain valid for up to WB_SECURE_HASH_TIMEOUT milliseconds, but will have a value of 'NULL'. This helps to mitigate possible pointer re-use.

You should call this function immediately before you free a pointer that might be referenced by a secure pointer hash, to prevent 'use after free' problems. This will NOT solve problems where the hash is being used across threads, however. You may need to provide a different method of synchronizing hashes under such a condition, such as thread-safe reference counting.

Header File: platform_helper.h

Definition at line 2141 of file platform_helper.c.

WBGetAtom()

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

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

Parameters

pDisplay	The display to search for a matching X11 Atom
szAtomName	The 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 2288 of file platform_helper.c.

WBGetAtomName()

char* WBGetAtomName	(	Display *	pDisplay,
		Atom	aAtom
	)

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

Parameters

pDisplay	The display to search for a matching X11 Atom
aAtom	The 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 2476 of file platform_helper.c.

WBGetPointerFromHash()

void* WBGetPointerFromHash

(

WB_UINT32

uiHash

)

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

Parameters

uiHash

The '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 referenced pointer will 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 XEvents 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 2195 of file platform_helper.c.

WBGetTimeIndex()

WB_UINT64 WBGetTimeIndex

(

void

)

Returns the current 'time index' (in microseconds)

Returns

An unsigned 64-bit time index value, in microseconds

The 'time index' is the master timer that determines when a timer event will be generated. By design it uses a 64-bit integer that never 'wraps around' to zero. It is generally derived from the 'gettimeofday' API call for operating systems such as BSD and Linux that support the POSIX standard.

The return value from this function is derived from the 'gettimeofday' call on POSIX systems.

On systems that do not natively support a 64-bit integer type, the return value will be WB_UINT32 and may actually wrap around after about 1 hour.

Header File: platform_helper.h

Definition at line 1016 of file platform_helper.c.

WBLookupAtom()

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

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

Parameters

pDisplay	The display to search for a matching X11 Atom
szAtomName	The 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 2417 of file platform_helper.c.

WBMkDir()

int WBMkDir	(	const char *	szFileName,
		int	flags
	)

a wrapper for 'mkdir' that makes directories recursively (as needed)

Parameters

szFileName

A const pointer to a character string containing a file or path name

Returns

a zero value if succssful, non-zero if it failed.

This is a wrapper for 'mkdir' that also handles recursive directory creation when not all paths exist already.

Header File: platform_helper.h

Definition at line 3324 of file platform_helper.c.

WBSearchPath()

char* WBSearchPath

(

const char *

szFileName

)

search for a file using the PATH environment variable

Parameters

szFileName

A 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 3380 of file platform_helper.c.

WBTempFile()

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

szExt

A 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 3625 of file platform_helper.c.

WBTempFile0()

char* WBTempFile0

(

const char *

szExt

)

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

Parameters

szExt

A 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 3509 of file platform_helper.c.