SYNOPSIS

    #include "libut/ut.h"
    int UT_var_restrict(char *name, UT_var_restrict_type type, args);

DESCRIPTION

This function places a restriction on the configuration variable having the given name.

The type of restriction is specified by type which must be one of these pre-defined constants:

range

This can only be used for configuration variables of type UT_var_int or UT_var_double. The value of the configuration variable is restricted to the range specified by the following two arguments min and max, which must be ints or doubles as determined by the type of the configuration variable.

Warning: Use decimals (e.g., pass 1.0 instead of 1) when placing a range on a UT_var_double type. This is necessary in a variable-length argument list, as the compiler cannot tell 1 is meant as a double unless it is passed as 1.0. The binary format of int and double are completely different and the restriction range will be set incorrectly if a double is not passed where it is expected. (The same issue can be observed using printf(3). The code printf("1 is not %f", 1); prints ``1 is not -1.998432''!)

strenum

This applies only to configuration variables of the type UT_var_string. The variable's string value is restricted to be one of a fixed, enumerated list of strings. The strings are specified in the char** argument which follows. It points to a NULL-terminated array of pointers to strings. Additionally, these strings must not be volatile (i.e., not on the stack or in malloc'd memory that is later freed). Strings written in C programs like char *c = "hello"; automatically satisfy this requirement.

readonly

With this restriction, the value of the configuration variable cannot be changed in the control port or in the configuration file. However, C code can still change the value using UT_var_set(3).

More than one restriction can be placed on a configuration variable, e.g. range and readonly, although this is not particularly useful.

RETURN VALUE

The return value is always 0. If name refers to a configuration variable that doesn't exist, it logged as a Fatal error, and the application exits with exit status -1.

RELATED CONTROL PORT COMMANDS

The var control port command lists and sets the configuration variables.

BUGS

It is possible to restrict a single numeric configuration variable to more than one range (by calling this function twice for example); or to restrict a string configuration variable to two (potentially conflicting) enumerated lists. In other words, setting a range or an enumeration twice does not replace the previous restrictions; it adds to them.

EXAMPLES

Imagine that a server defines a ``max_files'' configuration variable of type UT_var_int, a ``delay_sec'' variable of type UT_var_double, and a ``msg_protocol'' variable of type UT_var_string.

    /* Restrict max_files to values between 1 and 100, inclusive. */
    UT_var_restrict( "max_files", range, 1, 100);
    
    /*
     * Restrict delay_sec to values in the range 1.0 to 1.5. Note,
     * we pass 1.0 (not 1) because this variable is a UT_var_double.
     * (See the warning above about the "range" restriction.)
     */
    UT_var_restrict( "delay_sec", range, 1.0, 1.5);  
    
    /* Restrict msg_protocol to xmlrpc, soap or email. */
    char *protos[] = { "xmlrpc", "soap", "email", NULL };
    UT_var_restrict( "msg_protocol", protos );

SEE ALSO

UT_var_create(3), UT_var_set(3), UT_var_get(3), UT_var_reg_cb(3), UT_var_bindc(3)

AUTHOR

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