SYNOPSIS

    #include "libut/ut.h"
    int UT_init( int opt1, ..., INIT_END);

DESCRIPTION

This function initializes the libut library. This function must be called prior to any other libut function.

A variable number of arguments are accepted, each of which specifies an option, the last (or only) of which must be INIT_END.

These are the options, some of which require parameters:

INIT_DETACH

This causes the server to ``detach'' from the terminal and run in the background.

INIT_JOBNAME

Set the job name to the string specified in the following argument.

INIT_CONFIGFILE

Set the config file to the string specified in the following argument.

INIT_SHL_IPPORT

Set the control port IP address and port according to string passed as the next parameter, e.g., ``127.0.0.1:3333''.

INIT_LOGFILE

Set the log file to the string passed as the next parameter.

INIT_LOGLEVEL

Set the log level to the unsigned integer passed as the next parameter. The log levels are: 0 (Fatal), 1 (Error), 2 (Warning), 3 (Info), 4 (Debug) and 5 (Debugk).

INIT_SIGNALS( signal1, ..., signalN )

This option specifies a list of signals that will be caught. It has a special syntax. The signal are specified in parenthesis, e.g.:

    UT_init( INIT_SIGNALS(SIGHUP, SIGTERM), INIT_END );

The signal names are defined in <signal.h>.

The application can subsequently call UT_signal_reg(3) to request notification of the receipt of any of these signals.

Some signals cannot be caught, e.g. SIGKILL. Please consult other documentation such as the signal(2) manual page for further information.

INIT_ARGCV

This special option instructs libut to scan the command-line arguments for recognized configuration flags. It must be followed by the two arguments argc, argv which the program obtained when its main() function was invoked.

These command-line flags are recognized (all others are ignored):

-p ``127.0.0.1:3333''

Specifies the control port IP address and port.

-l ``<logfile>''

Specifies the log file.

-v ``<loglevel>''

Specifies the loglevel, one of Debugk, Debug, Info, Warning, Fatal.

-j ``<jobname>''

Specifies the job name.

-c ``<configfile>''

Specifies the server configuration file.

-b

Background mode. The application will ``detach'' from the controlling terminal.

-h

Prints a help message and exits.

INIT_END

This option is mandatory at the end of all other options, or as the only one.

RETURN VALUE

The return value is always 0. If an invalid option is encountered, it is logged and the application exits with exit status -1.

NOTES

Options are scanned in the order they appear (left-to-right). I.e., later options override earlier ones, in the case of repetition. This is useful when INIT_ARGCV is used. I.e., defaults can be set early in the option list, followed by INIT_ARGCV (allowing user-specified command-line options to override the previous options). If other options follow INIT_ARGCV, they override any options the user specified on the command-line.

EXAMPLES

Set the logfile, and detach server from the controlling terminal.

    UT_init( INIT_LOGFILE, "/var/server.log", INIT_DETACH, INIT_END);

Set control port, then parse any command-line options.

    UT_init( INIT_SHL_IPPORT, "127.0.0.1:5555", 
             INIT_ARGCV, argc, argv, 
             INIT_END );

AUTHOR

Troy D. Hanson <thanson@users.sourceforge.net>