Distrotech Application Library

A Collection of helper functions and wrapped up interfaces to other libraries. More...

Modules
	Referenced Lockable Objects
	Utilities for managing referenced lockable objects.
	Posix thread interface
	Functions for starting and managing threads.
	Network socket interface
	Allocate and initialise a socket for use as a client or server.
	Linux network interface functions
	Implement various interface routines from libnetlink.
	INI Style config file Interface
	Reads a ini config file into grouped hashed buckets.
	Radius client interface
	Simple implementation of experimental radius client.
	Micelaneous utilities.
	Utilities commonly used.
	IPv4 and IPv6 functions
	Helper functions for various calculations.
	File utility functions
	Convinece wrappers arround stat.
	Openldap/SASL Interface
	Functions to interface with a LDAP server.
	XML Interface
	Utilities for managing XML documents.
	CURL Url interface.
	Interface to libCURL.
	Zlib Interface
	Simplified implementation of zlib functions.
	Burtle Bob hash algorythim.
	lookup3.c, by Bob Jenkins, May 2006, Public Domain (Original Documentation)
	IPv6 Nat Mapping
	Implementation of RFC6296.
	Windows Support
	Support for building with mingw32 (Requires XP SP1+)

Files
file	dtsapp.h
	DTS Application library API Include file.
file	main.c
	Application framework.

Macros
#define	FRAMEWORK_MAIN(progname, name, email, www, year, runfile, flags, sighfunc)
	A macro to replace main() with initilization and daemonization code. More...
#define	ALLOC_CONST(const_var, val)
	Macro to assign values to char const. More...

Typedefs
typedef int(*	frameworkfunc )(int, char **)
	Framework callback function. More...
typedef void(*	syssighandler )(int, siginfo_t *, void *)
	Callback to user supplied signal handler. More...

Enumerations
enum	framework_flags { FRAMEWORK_FLAG_DAEMON = 1 << 0, FRAMEWORK_FLAG_NOGNU = 1 << 1, FRAMEWORK_FLAG_DAEMONLOCK = 1 << 2 }
	Application control flags. More...

Functions
void	printgnu (const char *pname, int year, const char *dev, const char *email, const char *www)
	Print a brief GNU copyright notice on console. More...
void	daemonize ()
	Daemonise the application using fork/exit. More...
int	lockpidfile (const char *runfile)
	Lock the run file in the framework application info. More...
void	framework_mkcore (char *progname, char *name, char *email, char *web, int year, char *runfile, int flags, syssighandler sigfunc)
	Initilise application data structure and return a reference. More...
int	framework_init (int argc, char *argv[], frameworkfunc callback)
	Initilise the application daemonise and join the manager thread. More...

Detailed Description

A Collection of helper functions and wrapped up interfaces to other libraries.

Macro Definition Documentation

#define ALLOC_CONST	(		const_var,
			val
	)

Value:

{ \
        char *tmp_char; \
        if (val) { \
            tmp_char = (char*)malloc(strlen(val) + 1); \
            strcpy(tmp_char, val); \
            const_var = (const char*)tmp_char; \
        } else { \
            const_var = NULL; \
        } \
    }

Macro to assign values to char const.

Definition at line 959 of file dtsapp.h.

Referenced by add_radserver(), framework_mkcore(), ldap_addinit(), ldap_modifyinit(), ldap_saslbind(), xml_modify(), and xslt_addparam().

#define FRAMEWORK_MAIN	(		progname,
			name,
			email,
			www,
			year,
			runfile,
			flags,
			sighfunc
	)

Value:

static int  framework_main(int argc, char *argv[]); \
int  main(int argc, char *argv[]) { \
	framework_mkcore(progname, name, email, www, year, runfile, flags, sighfunc); \
    return (framework_init(argc, argv, framework_main)); \
} \
static int  framework_main(int argc, char *argv[])

A macro to replace main() with initilization and daemonization code.

Note

Argument count is argc and arguments is array argv.

See Also

framework_flags

framework_mkcore()

framework_init()

Parameters

progname	Descriptive program name.
name	Copyright holders name.
email	Copyright holders email.
www	Web address.
year	Copyright year.
runfile	Application runfile.
flags	Application flags.
sighfunc	Signal handler function.

Definition at line 949 of file dtsapp.h.

Typedef Documentation

typedef int(* frameworkfunc)(int, char **)

Framework callback function.

Parameters

argc	Argument count.
argv	Argument array.

Returns

Application exit code.

Definition at line 219 of file dtsapp.h.

typedef void(* syssighandler)(int, siginfo_t *, void *)

Callback to user supplied signal handler.

Parameters

sig	Signal been handled.
si	Sa sigaction.
unsed	Unused cast to void from ucontext_t

Definition at line 228 of file dtsapp.h.

Enumeration Type Documentation

enum framework_flags

Application control flags.

Enumerator
FRAMEWORK_FLAG_DAEMON	Allow application daemonization.
FRAMEWORK_FLAG_NOGNU	Dont print GNU copyright.
FRAMEWORK_FLAG_DAEMONLOCK	Create lockfile on daemonize latter. Its possible you want to call daemonize latter and want the lockfile created then Note not compatible with FRAMEWORK_FLAG_DAEMON and has no effect FRAMEWORK_FLAG_DAEMON is set.

Definition at line 310 of file dtsapp.h.

                      {
    FRAMEWORK_FLAG_DAEMON       = 1 << 0,
    FRAMEWORK_FLAG_NOGNU        = 1 << 1,
    FRAMEWORK_FLAG_DAEMONLOCK   = 1 << 2
};

Function Documentation

void daemonize

(

)

Daemonise the application using fork/exit.

This should be run early before file descriptors and threads are started

See Also

FRAMEWORK_MAIN()

Warning

on failure the program will exit.

Todo:

WIN32 options is there a alternative for this.

Definition at line 94 of file main.c.

References framework_core::flags, framework_core::flock, FRAMEWORK_FLAG_DAEMONLOCK, lockpidfile(), objunref(), and framework_core::runfile.

Referenced by framework_init(), and FRAMEWORK_MAIN().

                        {
    struct framework_core *ci =  framework_core_info;

#ifndef __WIN32__
    pid_t   forkpid;

    /* fork and die daemonize*/
    forkpid = fork();
    if (forkpid > 0) {
        /* im all grown up and can pass onto child*/
        exit(0);
    } else if (forkpid < 0) {
        /* could not fork*/
        exit(-1);
    }

    setsid();

    /* Dont want these as a daemon*/
    signal(SIGTSTP, SIG_IGN);
    signal(SIGCHLD, SIG_IGN);
#endif

    /*delayed lock file from FRAMEWORK_MAIN / framework_init*/
    if (ci && (ci->flags & FRAMEWORK_FLAG_DAEMONLOCK)) {
        if ((ci->flock = lockpidfile(ci->runfile)) < 0) {
            printf("Could not lock pid file Exiting\n");
            while(framework_core_info) {
                objunref(framework_core_info);
            }
            exit (-1);
        }
        objunref(ci);
    }
}

int framework_init	(	int	argc,
		char *	argv[],
		frameworkfunc	callback
	)

Initilise the application daemonise and join the manager thread.

Warning

failure to pass a callback will require running stopthreads and jointhreads.

framework information configured by framework_mkcore will be freed on exit.

Parameters

argc	Argument count argv[0] will be program name.
argv	Argument array.
callback	Function to pass control too.

Definition at line 260 of file main.c.

References daemonize(), framework_core::developer, framework_core::email, framework_core::flags, framework_core::flock, FRAMEWORK_FLAG_DAEMON, FRAMEWORK_FLAG_DAEMONLOCK, FRAMEWORK_FLAG_NOGNU, lockpidfile(), objref(), objunref(), printgnu(), framework_core::progname, framework_core::runfile, framework_core::sa, seedrand(), sslstartup(), stopthreads(), unrefconfigfiles(), framework_core::www, and framework_core::year.

                                                                          {
    struct framework_core *ci =  framework_core_info;
    int ret = 0;

    seedrand();
    sslstartup();

    /*prinit out a GNU licence summary*/
    if (ci && !(ci->flags & FRAMEWORK_FLAG_NOGNU)) {
        printgnu(ci->progname, ci->year, ci->developer, ci->email, ci->www);
    }

    /* grab a ref for framework_core_info to be used latter*/
    if (ci && ci->flags & FRAMEWORK_FLAG_DAEMONLOCK) {
        objref(ci);
    }

    /* fork the process to daemonize it*/
    if (ci && ci->flags & FRAMEWORK_FLAG_DAEMON) {
        daemonize();
    }

    /* write pid to lockfile this should be done post daemonize*/
    if (ci && !(ci->flags & FRAMEWORK_FLAG_DAEMONLOCK)) {
        if ((ci->flock = lockpidfile(ci->runfile)) < 0) {
            printf("Could not lock pid file Exiting\n");
            return -1;
        }
    }

#ifndef __WIN32__
    /* interupt handler close clean on term so physical is reset*/
    configure_sigact(framework_core_info->sa);
#endif

    /*run the code from the application*/
    if (callback) {
        ret = callback(argc, argv);
        /* wait for all threads to end*/
        stopthreads(1);
    }

    /* turn off the lights*/
    objunref(ci);
    if (framework_core_info && framework_core_info->flags & FRAMEWORK_FLAG_DAEMONLOCK) {
        objunref(framework_core_info);
    }
    unrefconfigfiles();
    return (ret);
}

void framework_mkcore	(	char *	progname,
		char *	name,
		char *	email,
		char *	web,
		int	year,
		char *	runfile,
		int	flags,
		syssighandler	sigfunc
	)

Initilise application data structure and return a reference.

Warning

failure to supply a signal handler on non WIN32 systems will deafault to exiting with -1 on SIGINT/SIGKILL.

Todo:

does threads actually work in windows with no sighandler.

Warning

do not call this function without calling framework_init as the memory allocated will not be freed.

Parameters

progname	Descrioptive program name.
name	Copyright holder.
email	Copyright email address.
web	Website address.
year	Copyright year.
runfile	Run file that will store the pid and be locked (flock).
flags	Application flags.
sigfunc	Signal handler.

Definition at line 221 of file main.c.

References ALLOC_CONST, framework_core::developer, framework_core::email, framework_core::flags, objalloc(), objunref(), framework_core::progname, framework_core::runfile, framework_core::sa, framework_core::sig_handler, framework_core::www, and framework_core::year.

                                                                                                                                            {
    struct framework_core *core_info;
    if (framework_core_info) {
        objunref(framework_core_info);
        framework_core_info = NULL;
    }

    if (!(core_info = objalloc(sizeof(*core_info), framework_free))) {
        return;
    }

#ifndef __WIN32__
    if (core_info && !(core_info->sa = malloc(sizeof(*core_info->sa)))) {
        free(core_info);
        return;
    }
#endif

    ALLOC_CONST(core_info->developer, name);
    ALLOC_CONST(core_info->email, email);
    ALLOC_CONST(core_info->www, web);
    ALLOC_CONST(core_info->runfile, runfile);
    ALLOC_CONST(core_info->progname, progname);
    core_info->year = year;
    core_info->flags = flags;
#ifndef __WIN32__
    core_info->sig_handler = sigfunc;
#endif
    /* Pass reference to static system variable*/
    framework_core_info = core_info;
}

int lockpidfile

(

const char *

runfile

)

Lock the run file in the framework application info.

This can be delayed till running daemonize in the user function loop setting flag FRAMEWORK_FLAG_DAEMONLOCK

Parameters

runfile

File to write pid to and lock.

Returns

0 if no file is specified or not supported. The file descriptor on success.

Definition at line 135 of file main.c.

References framework_core::flock.

Referenced by daemonize(), and framework_init().

                                            {
    int lck_fd = 0;
#ifndef __WIN32__
    char pidstr[12];
    pid_t   mypid;

    mypid = getpid();
    sprintf(pidstr,"%i\n", (int)mypid);
    if (runfile && ((lck_fd = open(runfile, O_RDWR|O_CREAT, 0640)) > 0) && (!flock(lck_fd, LOCK_EX | LOCK_NB))) {
        if (write(lck_fd, pidstr, strlen(pidstr)) < 0) {
            close(lck_fd);
            lck_fd = -1;
        }
    /* file was opened and not locked*/
    } else if (runfile && lck_fd) {
        close(lck_fd);
        lck_fd = -1;
    }
#endif
    return (lck_fd);
}

void printgnu	(	const char *	pname,
		int	year,
		const char *	dev,
		const char *	email,
		const char *	www
	)

Print a brief GNU copyright notice on console.

See Also

FRAMEWORK_MAIN()

framework_mkcore()

Parameters

pname	Detailed application name.
year	Copyright year.
dev	Programer / copyright holder name.
email	Email address.
www	HTTP URL.

Definition at line 78 of file main.c.

Referenced by framework_init().

                                                                                                       {
    printf("\n"
           "    %s\n\n"
           "    Copyright (C) %i %s <%s>\n\n"
           "        %s\n\n"
           "    This program comes with ABSOLUTELY NO WARRANTY\n"
           "    This is free software, and you are welcome to redistribute it\n"
           "    under certain conditions.\n\n", pname, year, dev, email, www);
}