Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
AG_EXECUTE(3)		    Library Functions Manual		 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 run-
       ning 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, re-
       turning 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  immedi-
				ately 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.

Agar 1.7		       December	21, 2022		 AG_EXECUTE(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Execute&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help