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 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 ex-
			      ited.

     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+15.1.quarterly>

home | help