[Contents]

2. Interpreter Architecture

2.16. Other System Dependant Functions

2.16.47. file_CreateProcessEx

@c Run a new program and wait for it

This function starts a new process and starts to wait for the process. The caller can specify a timeout period in seconds until the function waits.

When the process terminates or the timeout period is over the function returns.

int file_CreateProcessEx(char *pszCommandLine,
                          long lTimeOut,
                          unsigned long *plPid,
                          unsigned long *plExitCode
  ){

• pszCommandLine the command to execute
• lTimeOut the maximum number of seconds to wait for the process to finish. If this is zero the function will not wait for the process. If the value is -1 the function wait without limit until the created process finishes.
• plPid pointer to variable where the PID of the new process is placed. This parameter can be NULL. If the function returns after the new process has terminated this value is more or less useless. However this parameter can be used to kill processes that reach the timeout period and do not terminate.
• plExitCode pointer to a variable where the exit code of the new process is placed. If the process is still running when the function returns this parameter is unaltered.

The return value indicates the success of the execution of the new process:

• FILESYSE_SUCCESS The process was started and terminated within the specified timeout period.
• FILESYSE_NOTSTARTED The function could not start the new process. (not used under UNIX)
• FILESYSE_TIMEOUT The process was started but did not finish during the timeout period.
• FILESYSE_NOCODE The process was started and finished within the timeout period but it was not possible to retrieve the exit code.

Note that the behaviour of this function is slightly different on Windows NT and on UNIX. On Windows NT the function will return FILESYSE_NOTSTARTED when the new process can not be started. Under UNIX the process performs a fork() and then an execv. The fork() does not return an error value. When the execvp fails it is already in the new process and can not return an error code. It exists using the exit code 1. This may not be distinguished from the program started and returning an exit code 1.