SYNOPSIS

#include <agar/core.h>

DESCRIPTION

The Agar-Core library implements the AG_Object(3) system and provides interfaces to common operating system services (filesystems, network APIs, threads, etc). Agar-GUI is built on top of AG_Core, but Agar-Core itself contains no GUI-related code and may be installed independently.

For a complete listing of available subsystems and interfaces, see the AGAR-CORE section of AG_Intro(3).

INITIALIZATION

int AG_InitCore (const char *progname, Uint flags)

void AG_AtExitFunc (void (*fn)(void))

void AG_Quit (void)

void AG_Destroy (void)

The AG_InitCore() function initializes the AG_Core library. progname is an optional identifier for the program. This name may be used to construct platform-specific directory paths. Unless the AG_CREATE_DATADIR flags option is set, the progname argument can be NULL.

Available flags options include:

AG_VERBOSE	Allow errors/warnings on the standard error output.
AG_CREATE_DATADIR	Check that the application data directory exists, create it if necessary (or fail if it cannot be created). It contains the state of objects saved by AG_ObjectSave(3). The default is `$HOME/.progname/` on Unix and platform-dependent elsewhere.
AG_SOFT_TIMERS	Don't use OS-provided timer mechanisms (such as BSD kqueue(2), Linux timerfd or select(2)). Timers will be handled either by explicitely updating a software-based timing wheel (see AG_ProcessTimeouts(3)), or some other mechanism.
AG_POSIX_USERS	If both AG_User(3) modules "getenv" and "posix" are available, prefer "posix". This is not the default because "posix" incurs potential startup overhead while initially accessing the password database (and $HOME is all Agar needs for its own purposes).

The AG_AtExitFunc() registers a function that will be invoked automatically by AG_Destroy().

AG_Quit() terminates the application by releasing resources allocated by AG_Core and invoking exit(2).

The AG_Destroy() function releases all resources allocated by the AG_Core library.

AGAR VERSION INFORMATION

void AG_GetVersion (AG_AgarVersion *ver)

bool AG_VERSION_ATLEAST (int major, int minor, int patchlevel)

The AG_GetVersion() function fills an AG_AgarVersion structure with version information:

typedef struct ag_agar_version {
	int major;
	int minor;
	int patch;
	const char *release;
} AG_AgarVersion;

Agar does not need to have been previously initialized for AG_GetVersion() to work.

The AG_VERSION_ATLEAST() macro evaluates to true if the current Agar version is equal to, or exceeds the given version number.

EXAMPLES

The following program initializes Agar-Core and prints the Agar version and release information:

int
main(int argc, char *argv[])
{
	AG_AgarVersion *ver;

	if (AG_InitCore("myProgram", 0) == -1) {
		AG_Verbose("AG_InitCore: %s\n", AG_GetError());
		return (1);
	}

	AG_GetVersion(&ver);
	AG_Verbose("Hello Agar %d.%d.%d (\"%s\")\n",
	    ver.major, ver.minor, ver.patch, ver.release);

	AG_Destroy()
	return (0);
}

HISTORY

The AG_InitCore() function first appeared in Agar 1.0. The AG_CREATE_DATADIR option appeared in Agar 1.3.3. AG_SOFT_TIMERS in Agar 1.5.0 and AG_POSIX_USERS in Agar 1.6.0.