VCSAgExecWithTimeout
int VCSAgExecWithTimeout(const char *path, char *const argv[], unsigned int timeout, char *buf, long buf_size, unsigned long *exit_codep)
Fork a new process, exec a program, wait for it to complete, return the status. If the process does not complete within the timeout value, kill it. Also, capture the messages from stdout or stderr to buf. The caller must ensure that buf is of size >= buf_size. VCSAgExecWithTimeout is a forced cancellation point. Even if the C++ entry point that calls VCSAgExecWithTimeout disables cancellation before invoking this API, the thread can get cancelled inside VCSAgExecWithTimeout. So the entry point needs to make sure that is pushes appropriate cancellation cleanup handlers before calling VCSAgExecWithTimeout. The forced cancellation ensures that a service thread running a timed out entry point does not keep running or waiting for the child process created by this API to exit but instead honors a cancellation request when it receives one.
Note
This API is not available on Windows.
Explanation of arguments to the function:
path
|
Name of the program to be executed.
|
argv
|
Arguments to the program. argv[0] must be same as path. The last entry of argv must be NULL. (Same as execv syntax).
|
timeout
|
Number of seconds within which the process should complete its execution. If zero is specified, this API defaults to VCSAgExec(), meaning the timeout is to be ignored. If the timeout value specified exceeds the time left for the entry point itself to timeout, the maximum possible timeout value is automatically used by this API. For example, if the timeout value specified in the API is 40 seconds, but the entry point itself times out after the next 20 seconds, the agent internally sets the timeout value for this API to 20-3=17 seconds. The 3 seconds are a grace period between the timeout for the process created using this API and the entry point process timeout.
|
buf
|
Buffer to hold the messages from stdout/stderr. The caller must supply it. This function does not allocate. When this function returns, buf is NULL-terminated.
|
bufsize
|
Size of buf. If the total size of the messages to stdout/stderr is more than bufsize, only the first (buf_size - 1) characters is returned.
|
exit_codep
|
Pointer to a location where the exit code of the executed program is stored. This value should interpreted as described by wait() on Unix
|
Return value: VCSAgSuccess if the execution is successful.
