SYNOPSIS
#include <agar/core.h>
DESCRIPTION
The
AG_Execute() function provides a cross-platform interface for running executable programs
and monitoring their execution.
INTERFACE
AG_ProcessID AG_Execute (const char *file, char **argv)
AG_ProcessID AG_WaitOnProcess (AG_ProcessID pid, enum ag_exec_wait_type wait_type)
int AG_Kill (AG_ProcessID pid)
AG_Execute() runs the specified program with the given arguments, returning an integer process ID. If an error has occurred, the function returns -1 with an error message.
AG_WaitOnProcess() checks for status or waits until the specified process terminates. The wait_type argument may be one of:
| AG_EXEC_WAIT_IMMEDIATE | If the process has not exited, return immediately without blocking. |
| AG_EXEC_WAIT_INFINITE | Block the calling thread until the process has exited. |
The function returns the PID of the terminated process, -1 if an error has occurred, or 0 if wait_type is AG_EXEC_WAIT_IMMEDIATE and the process is still running.
The AG_Kill() function immediately terminates the specified process.
EXAMPLES
The following code runs a program on a Unix-like system:
The following code launches a background task on Windows and terminates its execution after 10 seconds:
char *argv[3];
AG_ProcessID pid;
argv[0] = "ls";
argv[1] = "-l"
argv[2] = (char *)NULL;
pid = AG_Execute("/bin/ls", argv);
if (pid == -1)
AG_Verbose("Execute failed (%s)\n", AG_GetError());
The following code launches a background task on Windows and terminates its execution after 10 seconds:
char *argv[2];
AG_ProcessID pid;
int counter = 0;
argv[0] = "MyTask";
argv[1] = (char *)NULL;
pid = AG_Execute("C:\Program Files\"
"Example\MyTask.exe");
for (;;) {
if (AG_WaitOnProcess(pid, AG_EXEC_WAIT_IMMEDIATE)
== -1) {
AG_Verbose("Task exited unexpectedly (%s)\n",
AG_GetError());
break;
}
if (counter++ == 10) {
if (AG_Kill(pid) == -1) {
AG_Verbose("Kill failed (%s)\n",
AG_GetError());
}
break;
}
sleep(1);
}
SEE ALSO
HISTORY
The
AG_Execute interface first appeared in
Agar 1.4.1.
