X11 Work Bench Toolkit  1.0
Process Control Functions

Functions

WB_PROCESS_ID WBRunAsync (const char *szAppName,...)
 Run an application asynchronously. More...
 
char * WBRunResult (const char *szAppName,...)
 Run an application synchronously, returning 'stdout' output in a character buffer. More...
 
char * WBRunResultPipe (const char *szStdInBuf, const char *szAppName,...)
 Run an application synchronously, 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)
 Loads a shared library, DLL, module, or whatever you call it on your operating system. 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

void WBFreeLibrary ( WB_MODULE  hModule)

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

Parameters
hModuleA valid WB_MODULE module handle, as returned by WBLoadLibrary()

This function is identical to FreeLibrary() under Windows, and calls 'dlfree()' on POSIX systems

Header File: platform_helper.h

Definition at line 3328 of file platform_helper.c.

WB_PROCADDRESS WBGetProcAddress ( WB_MODULE  hModule,
const char *  szProcName 
)

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

Parameters
hModuleA valid WB_MODULE module handle, as returned by WBLoadLibrary()
szProcNameA const pointer to a character string containing the proc name
Returns
A valid WB_MODULE module handle, depending upon the operating system

This function is identical to GetProcAddress() under Windows, and calls 'dlproc()' on POSIX systems

Header File: platform_helper.h

Definition at line 3333 of file platform_helper.c.

WB_MODULE WBLoadLibrary ( const char *  szModuleName)

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

Parameters
szModuleNameA 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 calls 'dlopen()' on POSIX systems

Header File: platform_helper.h

Definition at line 3323 of file platform_helper.c.

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

Run an application asynchronously.

Parameters
szAppNameA 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

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

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
hStdInA WB_FILE_HANDLE for STDIN, or WB_INVALID_FILE_HANDLE
hStdOutA WB_FILE_HANDLE for STDOUT, or WB_INVALID_FILE_HANDLE
hStdErrA 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.
szAppNameA 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

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

Header File: platform_helper.h

Definition at line 3000 of file platform_helper.c.

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
hStdInA WB_FILE_HANDLE for STDIN, or WB_INVALID_FILE_HANDLE
hStdOutA WB_FILE_HANDLE for STDOUT, or WB_INVALID_FILE_HANDLE
hStdErrA 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.
szAppNameA const pointer to a character string containing the path to the application
vaA va_list of the arguments (the final one must be NULL)
Returns
A valid process ID or process handle, depending upon the operating system

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

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

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

Parameters
szAppNameA 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 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 3182 of file platform_helper.c.

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

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

Parameters
szStdInBufA const pointer to 0-byte terminated string/buffer containing the input for piped data.
szAppNameA 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 2 parameters. On error this function returns a NULL value. Any non-NULL value must be 'free'd by the caller using WBFree().

To create piped output, pass the result of the previous 'WBRunResult' or 'WBRunResultPipe' as the 'szStdInBuf' parameter to a subsequent 'WBRunResultPipe' call.

Header File: platform_helper.h

Definition at line 3199 of file platform_helper.c.