.\" Copyright (c) 2010-2022 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 21, 2022
.Dt AG_EXECUTE 3
.Os Agar 1.7
.Sh NAME
.Nm AG_Execute
.Nd agar file execution interface
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
.Ed
.Sh DESCRIPTION
The
.Fn AG_Execute
function provides a cross-platform interface for running executable programs
and monitoring their execution.
.Sh INTERFACE
.nr nS 1
.Ft "AG_ProcessID"
.Fn AG_Execute "const char *file" "char **argv"
.Pp
.Ft "AG_ProcessID"
.Fn AG_WaitOnProcess "AG_ProcessID pid" "enum ag_exec_wait_type wait_type"
.Pp
.Ft "int"
.Fn AG_Kill "AG_ProcessID pid"
.Pp
.nr nS 0
.Fn 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.
.Pp
.Fn AG_WaitOnProcess
checks for status or waits until the specified process terminates.
The
.Fa wait_type
argument may be one of:
.Bl -tag -width "AG_EXEC_WAIT_IMMEDIATE "
.It AG_EXEC_WAIT_IMMEDIATE
If the process has not exited, return immediately without blocking.
.It AG_EXEC_WAIT_INFINITE
Block the calling thread until the process has exited.
.El
.Pp
The function returns the PID of the terminated process, -1 if an error
has occurred, or 0 if
.Fa wait_type
is
.Dv AG_EXEC_WAIT_IMMEDIATE
and the process is still running.
.Pp
The
.Fn AG_Kill
function immediately terminates the specified process.
.Sh EXAMPLES
The following code runs a program on a Unix-like system:
.Bd -literal -offset indent
.\" SYNTAX(c)
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());
.Ed
.Pp
The following code launches a background task on Windows and terminates its
execution after 10 seconds:
.Bd -literal -offset indent
.\" SYNTAX(c)
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);
}
.Ed
.Sh SEE ALSO
.Xr AG_Intro 3
.Sh HISTORY
The
.Nm
interface first appeared in Agar 1.4.1.