Functions
WB_PROCESS_ID	WBRunAsync (const char *szAppName,...)
	Run an application asynchronously. More...

int	WBGetProcessState (WB_PROCESS_ID idProcess, WB_INT32 *pExitCode)
	Check on a running process, and return its state, and optionally the exit code. More...

char *	WBRunResult (const char *szAppName,...)
	Run an application synchronously, returning 'stdout' output in a character buffer. More...

char *	WBRunResultWithInput (const char szStdInBuf, const char szAppName,...)
	Run an application synchronously, supplying an input buffer for 'stdin', and returning 'stdout' output in a character buffer. More...

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. More...

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, using a va_list for the program's parameters. More...

WB_MODULE	WBLoadLibrary (const char *szModuleName)
	Loads a shared library, DLL, module, or whatever you call it on your operating system. More...

void	WBFreeLibrary (WB_MODULE hModule)
	Frees a shared library, DLL, module, or whatever, that was loaded via 'WBLoadLibrary()'. More...

WB_PROCADDRESS	WBGetProcAddress (WB_MODULE hModule, const char *szProcName)
	Obtains a function pointer for an exported function symbol in a shared library (or DLL) More...

void *	WBGetDataAddress (WB_MODULE hModule, const char *szDataName)
	Obtains a data pointer for an exported data symbol in a shared library (or DLL) More...

Detailed Description

This group consists of a set of functions that allow you to synchronously or asynchronously run processes, optionally re-directing input and output to or from a file or memory buffer.

Function Documentation

◆ WBFreeLibrary()

void WBFreeLibrary ( WB_MODULE hModule )

Frees a shared library, DLL, module, or whatever, that was loaded via 'WBLoadLibrary()'.

Parameters

hModule A valid WB_MODULE module handle, as returned by WBLoadLibrary()

This function is identical to FreeLibrary() under Windows, and is a wrapper for 'dlfree()' on POSIX systems.

Use this to free a shared library (or DLL) that was opened with WBLoadLibrary().

In POSIX systems, the 'dlfree' function will invoke '_fini()' within the shared library, if it is present, the when the library is finally unmapped from the address space. In Windows, the FreeLibrary() function calls 'DllMain()' within the DLL, with one of various parameters, typically DLL_PROCESS_DETACH. The semantics are much more complicated for Windows (see MSDN documentation for 'DllMain()')

Certain library and API functions may not be available in '_fini()' or 'DllMain()' - see appropriate documentation for any restrictions that might apply to your shared libraries (DLLs).

Header File: platform_helper.h

Definition at line 4597 of file platform_helper.c.

◆ WBGetDataAddress()

void* WBGetDataAddress	(	WB_MODULE	hModule,
		const char *	szDataName
	)

Obtains a data pointer for an exported data symbol in a shared library (or DLL)

Parameters

hModule	A valid WB_MODULE module handle, as returned by WBLoadLibrary()
szDataName	A const pointer to a character string containing the data name

Returns: A pointer to the data item, or NULL if the symbol does not exist.

This function is identical to GetProcAddress() under Windows, with the return data type cast to 'void *'. It is a wrapper for 'dlsym()' on POSIX systems.

Header File: platform_helper.h

Definition at line 4612 of file platform_helper.c.

◆ WBGetProcAddress()

WB_PROCADDRESS WBGetProcAddress	(	WB_MODULE	hModule,
		const char *	szProcName
	)

Obtains a function pointer for an exported function symbol in a shared library (or DLL)

Parameters

hModule	A valid WB_MODULE module handle, as returned by WBLoadLibrary()
szProcName	A const pointer to a character string containing the proc name

Returns: A function pointer as a 'WB_PROCADDRESS' type, or NULL if the symbol does not exist

This function is identical to GetProcAddress() under Windows, and is a wrapper for 'dlfunc()' or 'dlsym()' on POSIX systems

Header File: platform_helper.h

Definition at line 4602 of file platform_helper.c.

◆ WBGetProcessState()

int WBGetProcessState	(	WB_PROCESS_ID	idProcess,
		WB_INT32 *	pExitCode
	)

Check on a running process, and return its state, and optionally the exit code.

Parameters

idProcess	A WB_PROCESS_ID for the running process
pExitCode	An optional pointer to a WB_INT32 to retrieve the exit code (may be NULL)

Returns: A positive value if the process is still running, zero if the process has terminated, negative on error.

Call this function to determine if an asynchronous process is still running, and possibly retrieve the exit code if it is no longer running. On POSIX systems, the exit code is generally a single byte (other values may be reserved). On Windows, it's officially an unsigned 32-bit integer.

If a process is suspended, killed, or exits due to a system error, this function will not differentiate between normal or abnormal termination, or between running or suspended. If you need this kind of complex application status, use 'waitpid()' (POSIX) or GetExitCodeProcess() (Windows).

This function does not perform any explicit wait states when checking a process's state. If you must block your thread's execution in order to wait for a process to exit, you should call WBSleep() (or its equivalent) within the loop to avoid 'maxing out' the CPU utilization, which would very likely use up more electricity than a more efficient wait state.

Definition at line 4392 of file platform_helper.c.

◆ WBLoadLibrary()

WB_MODULE WBLoadLibrary ( const char * szModuleName )

Loads a shared library, DLL, module, or whatever you call it on your operating system.

Parameters

szModuleName A const pointer to a character string containing the path for the library, module, DLL, or whatever

Returns: A valid WB_MODULE module handle, depending upon the operating system

This function is identical to LoadLibrary() under Windows, and is a wrapper for 'dlopen()' on POSIX systems.

Use this to dynamically load a shared library (or DLL under Windows) at run-time from within your application.

In POSIX systems, the 'dlopen' function will invoke '_init()' within the shared library, if it is present, the first time the library is mapped into the address space. In Windows, the LoadLibrary() function calls 'DllMain()' within the DLL, with one of various parameters, typically DLL_PROCESS_ATTACH. The semantics are much more complicated for Windows (see MSDN documentation for 'DllMain()')

Additionally, for POSIX systems, the 'dlopen()' function is called with access set to (RTLD_LAZY | RTLD_LOCAL). This implies that a) each external reference is resolved when you call the appropriate function; and b) Only symbols defined in the library and it's "DAG" of needed objects will be resolvable [default behavior]. If you want a different behavior, you can call 'dlopen()' yourself, and cast the return value to a WB_MODULE.

Certain library and API functions may not be available in '_init()' or 'DllMain()' - see appropriate documentation for any restrictions that might apply to your shared libraries (DLLs).

Header File: platform_helper.h

Definition at line 4592 of file platform_helper.c.

◆ WBRunAsync()

WB_PROCESS_ID WBRunAsync	(	const char *	szAppName,
			...
	)

Run an application asynchronously.

Parameters

szAppName A const pointer to a character string containing the path to the application

Returns: A valid process ID or process handle, depending upon the operating system. On error it returns WB_INVALID_FILE_HANDLE

Use this function to spawn an asynchronous process. The function returns an invalid process ID or process handle on error. If the process ID is an allocated resource, the caller must free it. Each additional parameter passed to this function is a parameter that is to be passed to the program. The final parameter in the list must be NULL, so any call to this function will need to have at least 2 parameters.

Header File: platform_helper.h

Definition at line 4177 of file platform_helper.c.

◆ WBRunAsyncPipe()

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.

Parameters

hStdIn	A WB_FILE_HANDLE for STDIN, or WB_INVALID_FILE_HANDLE
hStdOut	A WB_FILE_HANDLE for STDOUT, or WB_INVALID_FILE_HANDLE
hStdErr	A WB_FILE_HANDLE for STDERR, or WB_INVALID_FILE_HANDLE. This can be the same handle as hStdErr, though interleaved output may not occur as expected.
szAppName	A const pointer to a character string containing the path to the application

Returns: A valid process ID or process handle, depending upon the operating system. On error, it returns WB_INVALID_FILE_HANDLE

Use this function to spawn an asynchronous process in which you want to track STDIN, STDOUT, and/or STDERR. The function returns an invalid process ID or process handle on error. If the process ID is an allocated resource, the caller must free it. Each additional parameter passed to this function will become a parameter that is to be passed to the program. The final parameter in the list must be NULL to mark the end of the list, so any call to this function will need to have at least 5 parameters.

If you do not want to re-direct a file handle, pass 'WB_INVALID_FILE_HANDLE' for its value. It is also possible to pass the SAME file handle for hStdIn, hStdOut, and hStdErr provided that it has the correct read/write access available. File handles passed to this function will be duplicated, but not closed. It is safe (and prudent) to close the original file handles immediately after calling this function.

You can monitor 'WB_PROCESS_ID' to find out if the process is running. Additionally, you can use the output of hStdOut and hStdErr by re-directing them to anonymous pipes and monitoring their activity.

Header File: platform_helper.h

Definition at line 4201 of file platform_helper.c.

◆ WBRunAsyncPipeV()

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, using a va_list for the program's parameters.

Parameters

hStdIn	A WB_FILE_HANDLE for STDIN, or WB_INVALID_FILE_HANDLE
hStdOut	A WB_FILE_HANDLE for STDOUT, or WB_INVALID_FILE_HANDLE
hStdErr	A WB_FILE_HANDLE for STDERR, or WB_INVALID_FILE_HANDLE. This can be the same handle as hStdErr, though interleaved output may not occur as expected.
szAppName	A const pointer to a character string containing the path to the application
va	A va_list of the arguments (the final one must be NULL)

Returns: A valid process ID or process handle, depending upon the operating system. On error, it returns WB_INVALID_FILE_HANDLE

This function is identical to WBRunAsyncPipe() except that the variable argument list is passed as a va_list.
Use this function to spawn an asynchronous process in which you want to track STDIN, STDOUT, and/or STDERR. The function returns an invalid process ID or process handle on error. If the process ID is an allocated resource, the caller must free it. Parameters passed to this function as part of the va_list are parameters that are to be passed to the program. The final parameter in the va_list must be NULL to mark the end of the list.
If you do not want to re-direct a file handle, pass 'WB_INVALID_FILE_HANDLE' for its value. It is also possible to pass the SAME file handle for hStdIn, hStdOut, and hStdErr provided that it has the correct read/write access available. File handles passed to this function will be duplicated, but not closed. It is also safe to close the original file handles immediately after calling this function.
You can monitor 'WB_PROCESS_ID' to find out if the process is running. Additionally, you can use the output of hStdOut and hStdErr by re-directing them to anonymous pipes and monitoring their activity.

This function is used internally by the other process control functions, and is defined here in case you need to write a customized version of one of the process control functions. A typical example might be the use of stderr rather than stdout for WBRunResult().

Header File: platform_helper.h

Definition at line 3701 of file platform_helper.c.

◆ WBRunResult()

char* WBRunResult	(	const char *	szAppName,
			...
	)

Run an application synchronously, returning 'stdout' output in a character buffer.

Parameters

szAppName A const pointer to a character string containing the path to the application

Returns: A WBAlloc() pointer to a buffer containing the 'stdout' output from the application, or NULL on error.

Use this function to run an external process and capture its output. This function will ignore the error return code from the program, so if this information is necessary, you should write a different function (based on this one) using 'WBRunAsync' and a wait loop, etc. that checks the application's return value on exit. Each additional parameter passed to this function is a parameter that is to be passed to the program. The final parameter in the list must be NULL, so any call to this function will need to have at least 2 parameters. On error this function returns a NULL value. Any non-NULL value must be 'free'd by the caller using WBFree().

Header File: platform_helper.h

Definition at line 4446 of file platform_helper.c.

◆ WBRunResultWithInput()

char* WBRunResultWithInput	(	const char *	szStdInBuf,
		const char *	szAppName,
			...
	)

Run an application synchronously, supplying an input buffer for 'stdin', and returning 'stdout' output in a character buffer.

Parameters

szStdInBuf	A const pointer to 0-byte terminated string/buffer containing the input for piped data.
szAppName	A const pointer to a character string containing the path to the application

Returns: A WBAlloc() pointer to a buffer containing the 'stdout' output from the application.

Use this function to run an external process, providing a buffer that contains data to be sent to the applications 'stdin', and in the process, capture its output. This function will ignore the error return code from the program, so if this information is necessary, you should write a different function (based on this one) using 'WBRunAsync' and a wait loop, etc. that checks the application's return value on exit.

Each additional parameter passed to this function is a parameter that is to be passed to the program. The final parameter in the list must be NULL, so any call to this function will need to have at least 3 parameters.

On error this function returns a NULL value. Any non-NULL value must be 'free'd by the caller using WBFree().
To create simple piped output, pass the result of the previous 'WBRunResult' or 'WBRunResultWithInput()' as the 'szStdInBuf' parameter to a subsequent 'WBRunResultWithInput()' call.

Header File: platform_helper.h

Definition at line 4463 of file platform_helper.c.

Functions

Detailed Description

Function Documentation

◆ WBFreeLibrary()

◆ WBGetDataAddress()

◆ WBGetProcAddress()

◆ WBGetProcessState()

◆ WBLoadLibrary()

◆ WBRunAsync()

◆ WBRunAsyncPipe()

◆ WBRunAsyncPipeV()

◆ WBRunResult()

◆ WBRunResultWithInput()