AG_EXECUTE(3)

NAME
AG_Execute - agar file execution interface

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:

    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
AG_Intro(3)

HISTORY
The AG_Execute interface first appeared in Agar 1.4.1.