Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

Core treeconf library.


Data Structures

struct  _treeconf_ctx_s
 Treeconf context structure. More...
struct  _treeconf_node_s
 Treeconf node structure. More...
struct  _treeconf_str_s
 Treeconf string structure. More...
struct  _treeconf_subst_s
 Treeconf substitution structure. More...

Defines

#define TREECONF_CTX_MAGIC
 Treeconf context magic number.
#define TREECONF_CTX_INIT
 Configuration context initializer.
#define tx_verify(ctx)
 Context verification macro.
#define tx_config(ctx)
 Context configuration node pointer.
#define tx_count(ctx)
 Context configuration node count.
#define tc_init(ctx)
 Configuration context dynamic initializer.
#define TREECONF_NODE_MAGIC
 Treeconf node magic number.
#define tn_verify(node)
 Configuration node verification macro.
#define tn_context(node)
 Configuration node context.
#define tn_type(node)
 Configuration node type.
#define tn_next(node)
 Next configuration node.
#define tn_down(node)
 Child configuration node.
#define tn_parent(node)
 Parent configuration node.
#define tn_nodown(node)
 Implicit registration callback function.
#define tn_change(node)
 Value change callback function.
#define tn_value(node)
 Variable value.
#define tn_default(node)
 Variable default value.
#define tn_assoc(node)
 Association data.
#define tn_name(node)
 Node name.
#define tn_isdef(node)
 Node value is default?
#define ts_string(strs, n)
 String pointer.
#define ts_length(strs, n)
 String length.
#define TC_SUBST_INSECURE
 Insecure substitution flag.
#define TC_SUBST_IGNORE
 Ignore substitution flag.
#define TC_SUBST_INIT(chr, str, flags)
 Substitution static initializer.
#define tu_char(sub)
 Substitution rule character.
#define tu_value(sub)
 Substitution value.
#define tu_flags(sub)
 Substitution flags.
#define TC_PATH_SECURE
 Prohibit insecure substitutions.
#define TC_PATH_ALL
 Search all files in the path.

Typedefs

typedef _treeconf_ctx_s treeconf_ctx_t
 Configuration context.
typedef _treeconf_node_s treeconf_node_t
 Configuration node.
typedef _treeconf_str_s treeconf_str_t
 Configuration strings.
typedef _treeconf_subst_s treeconf_subst_t
 Path substitutions.
typedef int(* treeconf_nodown_t )(treeconf_ctx_t *ctx, treeconf_node_t *parent, treeconf_str_t *name, int elements)
 Unregistered variable callback.
typedef void(* treeconf_change_t )(treeconf_ctx_t *ctx, treeconf_node_t *node)
 Variable change callback.
typedef unsigned int(* treeconf_file_t )(const char *file, void *data)
 Path callback.

Enumerations

enum  treeconf_type_t { TC_NODETYPE_VARIABLE, TC_NODETYPE_NODE, TC_NODETYPE_IMPLICIT, TC_NODETYPE_MASK }
 Node type. More...

Functions

unsigned int tc_break (treeconf_str_t **str_p, int *cnt_p, const char *name, const char *delims)
 Break a string into an array of components.
unsigned int tc_path (const char *path, const char *def, treeconf_subst_t substs[], int s_cnt, unsigned int flags, treeconf_file_t call, void *call_data)
 Search a path-like string for readable files.
unsigned int tc_destroy (treeconf_ctx_t *ctx)
 Destroy a context.
unsigned int tc_register (treeconf_ctx_t *ctx, const char *name, const char *def, treeconf_node_t *parent, treeconf_nodown_t nodown, treeconf_change_t change, void *assoc)
 Register a configuration variable.
unsigned int tc_set (treeconf_ctx_t *ctx, const char *name, const char *value, treeconf_node_t *parent)
 Set a variable to a given value.
unsigned int tc_get (treeconf_ctx_t *ctx, const char *name, const char **value, treeconf_node_t *parent)
 Get the value of a variable.
unsigned int tc_find (treeconf_ctx_t *ctx, const char *name, treeconf_node_t **node, treeconf_node_t *parent)
 Obtain a pointer to a given node.
unsigned int tc_load (const char *file, void *ctx)
 Load a configuration file.

Define Documentation

#define tc_init (  ctx   ) 
 

This macro simply initializes a dynamically allocated treeconf_ctx_t.

Parameters:
ctx A pointer to an uninitialized treeconf_ctx_t.

Definition at line 267 of file treeconf.h.

#define TC_PATH_ALL
 

Normally, tc_path() searches for the first readable file and calls the callback for that file. However, some applications may wish to read all files in a given path. This flag may be used to force tc_path() to behave in that fashion.

Definition at line 701 of file treeconf.h.

Referenced by _subst().

#define TC_PATH_SECURE
 

This flag, when passed to the tc_path() function, prohibits any and all insecure substitutions---tilde expansion for the current user and any caller-specific substitutions flagged as insecure.

Definition at line 692 of file treeconf.h.

Referenced by tc_path().

#define TC_SUBST_IGNORE
 

Some substitutions may not be available under certain circumstances. This flag will cause the given substitution to be ignored.

Definition at line 543 of file treeconf.h.

#define TC_SUBST_INIT (  chr,
str,
flags   ) 
 

This static initializer may be used for statically creating an array of substitutions. The values of the given substitutions may be filled in just prior to the call to tc_path().

Parameters:
chr The character of the substitution.
str The string value of the substitution, or 0 if dynamic.
flags Any flags for the substitution.

Definition at line 555 of file treeconf.h.

#define TC_SUBST_INSECURE
 

Some substitutions may be insecure when used by a setuid program. This flag may be used to mark a particular substitution as insecure.

Definition at line 535 of file treeconf.h.

#define tn_assoc (  node   ) 
 

This macro retrieves a pointer to the association data associated with the given node.

Note:
This macro may be used as an lvalue to change the application-specified association data.
Parameters:
node A pointer to a treeconf_node_t.
Returns:
A pointer to void.

Definition at line 452 of file treeconf.h.

#define tn_change (  node   ) 
 

Some applications may need to know when the value of a particular variable changes. They may do this by setting the change callback for a given variable, either at variable registration time, or by using this macro as an lvalue after the fact. This macro will retrieve the change callback for a given node, or, as indicated, it may be used as an lvalue to set the change callback.

Parameters:
node A pointer to a treeconf_node_t.
Returns:
A treeconf_change_t function pointer.

Definition at line 408 of file treeconf.h.

#define tn_context (  node   ) 
 

This macro returns a pointer to the configuration context a given node is in.

Parameters:
node A pointer to a treeconf_node_t.
Returns:
A pointer to a treeconf_ctx_t.

Definition at line 324 of file treeconf.h.

#define tn_default (  node   ) 
 

This macro retrieves a pointer to the string representing the default value of the given node.

Warning:
The pointer so obtained must never be passed to free(), nor may it be stored elsewhere. The library is at liberty to release the memory the value is stored in at any time.
Parameters:
node A pointer to a treeconf_node_t.
Returns:
A pointer to char.

Definition at line 438 of file treeconf.h.

#define tn_down (  node   ) 
 

This macro is used when traversing the configuration tree. It returns the first child node of the current node, or NULL if there is no child. To traverse all the children of the current node, use the tn_next() macro.

Parameters:
node A pointer to a treeconf_node_t.
Returns:
A pointer to a treeconf_node_t.

Definition at line 363 of file treeconf.h.

#define tn_isdef (  node   ) 
 

This macro checks to see if the given node is set to its default value.

Parameters:
node A pointer to a treeconf_node_t.
Returns:
Boolean true if node has its default value, or false otherwise.

Definition at line 483 of file treeconf.h.

Referenced by _tc_set(), and main().

#define tn_name (  node   ) 
 

This macro retrieves a pointer to the name of the given node.

Note:
The node name is not the same as the variable name. A variable name is composed of several node names strung together with approprate separators defining a path from the root of the configuration tree to a given node.
Warning:
The pointer so obtained must never be passed to free(), nor may it be stored elsewhere. The library is at liberty to release the memory the value is stored in at any time.
Parameters:
node A pointer to a treeconf_node_t.
Returns:
A pointer to char.

Definition at line 471 of file treeconf.h.

Referenced by _tc_lookup_node().

#define tn_next (  node   ) 
 

This macro is used when traversing the configuration tree. It returns the next node at the same level as the current node, or NULL when there are no more nodes at this level of the tree.

Parameters:
node A pointer to a treeconf_node_t.
Returns:
A pointer to a treeconf_node_t.

Definition at line 350 of file treeconf.h.

#define tn_nodown (  node   ) 
 

When the application sets a variable that has not yet been registered, but has nodes that have, the nodown callback of the last registered node is called to determine whether to create the subnodes. If that function returns a non-zero value, the subnodes will be created. This macro may be used to retrieve the current value of the nodown callback for a given node. It may also be used as an lvalue to change the nodown callback, though this should be done with care.

Parameters:
node A pointer to a treeconf_node_t.
Returns:
A treeconf_nodown_t function pointer.

Definition at line 392 of file treeconf.h.

Referenced by main().

#define tn_parent (  node   ) 
 

This macro is used to retrieve the parent node of a given node. If the node is at the root of the configuration tree, it will return NULL.

Parameters:
node A pointer to a treeconf_node_t.
Returns:
A pointer to a treeconf_node_t.

Definition at line 375 of file treeconf.h.

#define tn_type (  node   ) 
 

This macro is used to determine the type of the given node. The type will be either TC_NODETYPE_VARIABLE or TC_NODETYPE_NODE, possibly or'd with TC_NODETYPE_IMPLICIT. TC_NODETYPE_MASK may be used to isolate the type value from flags such as TC_NODETYPE_IMPLICIT.

Parameters:
node A pointer to a treeconf_node_t.
Returns:
A treeconf_type_t.

Definition at line 338 of file treeconf.h.

Referenced by _tc_lookup_node(), and main().

#define tn_value (  node   ) 
 

This macro retrieves a pointer to the string representing the current value of the given node.

Warning:
The pointer so obtained must never be passed to free(), nor may it be stored elsewhere. The library is at liberty to release the memory the value is stored in at any time.
Parameters:
node A pointer to a treeconf_node_t.
Returns:
A pointer to char.

Definition at line 423 of file treeconf.h.

Referenced by main().

#define tn_verify (  node   ) 
 

This macro verifies that a given pointer actually does point to a configuration node.

Warning:
This macro may evaluate the node argument twice.
Parameters:
node A pointer to a treeconf_node_t.
Returns:
Boolean true if ctx is a valid configuration node, or false otherwise.

Definition at line 312 of file treeconf.h.

Referenced by tc_find(), tc_get(), tc_register(), and tc_set().

#define TREECONF_CTX_INIT
 

This is a static initialier for objects of type treeconf_ctx_t.

Definition at line 219 of file treeconf.h.

#define TREECONF_CTX_MAGIC
 

This is the magic number used for the treeconf context structure.

Definition at line 213 of file treeconf.h.

#define TREECONF_NODE_MAGIC
 

This is the magic number used for the treeconf node structure.

Definition at line 298 of file treeconf.h.

#define ts_length (  strs,
n   ) 
 

This macro returns the length of the string designated by n in the array of strings strs.

Parameters:
strs An array of treeconf_str_t.
n An index into the array.
Returns:
An int.

Definition at line 517 of file treeconf.h.

Referenced by main().

#define ts_string (  strs,
n   ) 
 

This macro returns a pointer to the beginning of the string designated by n in the array of strings strs.

Parameters:
strs An array of treeconf_str_t.
n An index into the array.
Returns:
A pointer to char.

Definition at line 505 of file treeconf.h.

Referenced by main().

#define tu_char (  sub   ) 
 

The substitutions provided by tc_path() are introduced by a % character followed by another single character, as defined in a treeconf_subst_t structure. This macro, given sub, will retrieve the substitution character. It may also be used as an lvalue to set the substitution character.

Parameters:
sub A pointer to a treeconf_subst_t.
Returns:
A char.

Definition at line 570 of file treeconf.h.

#define tu_flags (  sub   ) 
 

This macro, given a sub, will retrieve the flags of the given substitution rule. It may also be used as an lvalue to set the flags.

Parameters:
sub A pointer to a treeconf_subst_t.
Returns:
An unsigned int

Definition at line 594 of file treeconf.h.

#define tu_value (  sub   ) 
 

This macro, given a sub, will retrieve the current value of the substitution rule. It may also be used as an lvalue to set the value.

Parameters:
sub A pointer to a treeconf_subst_t.
Returns:
A pointer to char.

Definition at line 582 of file treeconf.h.

Referenced by _subst().

#define tx_config (  ctx   ) 
 

The tx_config() macro returns a pointer to the first configuration node at the root level. The entire configuration tree may then be traversed.

Parameters:
ctx A pointer to a treeconf_ctx_t.
Returns:
A pointer to a treeconf_node_t.

Definition at line 246 of file treeconf.h.

Referenced by _tc_lookup_node(), and main().

#define tx_count (  ctx   ) 
 

The tx_count() macro merely returns an integer indicating the number of configuration nodes allocated for this configuration.

Parameters:
ctx A pointer to a treeconf_ctx_t.
Returns:
An unsigned int containing the count of nodes in the configuration.

Definition at line 258 of file treeconf.h.

Referenced by main().

#define tx_verify (  ctx   ) 
 

This macro verifies that a given pointer actually does point to a configuration context.

Warning:
This macro may evaluate the ctx argument twice.
Parameters:
ctx A pointer to a treeconf_ctx_t.
Returns:
Boolean true if ctx is a valid configuration context, or false otherwise.

Definition at line 233 of file treeconf.h.

Referenced by main(), tc_destroy(), tc_find(), tc_get(), tc_load(), tc_register(), and tc_set().

Typedef Documentation

typedef void(* treeconf_change_t)(treeconf_ctx_t *ctx, treeconf_node_t *node)
 

When a variable is registered, the application may set a callback so that it may be informed of that change. This type represents a pointer to that callback function.

Parameters:
ctx A pointer to a treeconf_ctx_t.
node A pointer to the treeconf_node_t that has had its value changed.

Definition at line 180 of file treeconf.h.

typedef struct _treeconf_ctx_s treeconf_ctx_t
 

Almost all of the treeconf functions operate within a context defined by this structure. All of the various configuration settings and variable registrations are tied directly to this context, and so the context itself represents the exact configuration.

Note:
The configuration context is allocated by the caller and must be initialized either with TREECONF_CTX_INIT or tc_init().

Definition at line 89 of file treeconf.h.

Referenced by _tc_create_node(), _tc_lookup_node(), load_results(), main(), nodown_false(), nodown_true(), t_change(), tc_destroy(), tc_find(), tc_get(), tc_load(), tc_register(), and tc_set().

typedef unsigned int(* treeconf_file_t)(const char *file, void *data)
 

This type represents a pointer to a callback function used by tc_path() when a file in the path list exists and is readable. A non-zero return value will terminate the path search and will be returned by tc_path().

Parameters:
file A pointer to char with the name of a file found by tc_path().
data A pointer to void with application-specific data passed as the call_data parameter of tc_path().
Returns:
Non-zero to abort tc_path(); zero otherwise.

Definition at line 196 of file treeconf.h.

typedef struct _treeconf_node_s treeconf_node_t
 

Each configuration variable is represented as a node of a generalized tree. This structure represents each node of the tree, and will contain the actual value assigned to a specific configuration variable, as well as any references to callback functions.

Note:
The configuration node structure is variable in size and is dynamically allocated by the library.

Definition at line 102 of file treeconf.h.

Referenced by _tc_create_node(), _tc_lookup_node(), _tc_release_children(), _tc_set(), main(), nodown_false(), nodown_true(), t_change(), tc_destroy(), tc_find(), tc_get(), tc_load(), tc_register(), and tc_set().

typedef int(* treeconf_nodown_t)(treeconf_ctx_t *ctx, treeconf_node_t *parent, treeconf_str_t *name, int elements)
 

If an attempt is made to set an unregistered variable, the library will call a callback with a pointer to the last registered node in the line. If that callback returns a true value, then the unregistered variable will be implicitly registered. This type represents a pointer to that callback function.

Parameters:
ctx A pointer to a treeconf_ctx_t.
parent A pointer to a treeconf_node_t representing the closest existing parent for the given node.
name A pointer to a treeconf_str_t containing the remaining name elements for the given node.
elements An integer giving the number of name elements.
Returns:
Boolean true if the node should be created, false otherwise.

Definition at line 167 of file treeconf.h.

typedef struct _treeconf_str_s treeconf_str_t
 

One fundamental operation in the Tree-based Configuration Management Library is breaking up variable names into lists of variable node names. This must be done without modifying the string, as some strings may be statically allocated in read-only memory. This is done by associating a length with each string. This structure is simply a means for grouping a length with a string pointer, and is only used by tc_break() and one callback function.

Definition at line 115 of file treeconf.h.

Referenced by _add_string(), _subst(), main(), nodown_false(), nodown_true(), tc_break(), and tc_path().

typedef struct _treeconf_subst_s treeconf_subst_t
 

The library provides a helper function, tc_path(), for locating file(s) in a colon-separated list of file paths. Occasionally, substitutions may be desired---for instance, a path containing "~/.tconf" should always refer to the ".tconf" in the current user's home directory. This tilde expansion is performed automatically by tc_path(), but other substitutions may be permitted by the application. This structure provides a means of specifying the desired substitutions to tc_path().

Definition at line 128 of file treeconf.h.

Referenced by _subst(), and tc_path().

Enumeration Type Documentation

enum treeconf_type_t
 

Each node in the configuration tree may be a variable node, meaning that it has an associated value, or a tree node, meaning that the node has no associated value but that it does have other nodes, possibly variable nodes, as descendants. This enumeration is used to indicate the type of node. It also contains a flag to indicate whether the node has been implicitly registered.

Enumeration values:
TC_NODETYPE_VARIABLE  Node is a variable node.
TC_NODETYPE_NODE  Node is a transit node with no value.
TC_NODETYPE_IMPLICIT  Node has been implicitly registered.
TC_NODETYPE_MASK  Node type mask.

Definition at line 140 of file treeconf.h.

Referenced by tc_register().

Function Documentation

unsigned int tc_break (  treeconf_str_t **  str_p,
int *  cnt_p,
const char *  name,
const char *  delims
) 
 

The tc_break() function is similar to strtok(), in that it splits a string up in components based on the delimiters in the delims string. Unlike strtok(), however, it is fully reentrant and does not modify the original string. The result is an array of treeconf_str_t structures returned through the str_p result parameter, with the size of the array returned via cnt_p. The array contains pointers into the original name string, so don't free that string until you're done with the whole array. The array must be released by passing it to free().

Test:
This function is tested in t_tc_break.c.
Parameters:
str_p A pointer to a pointer to treeconf_str_t. This is a result parameter through which the array of strings is returned.
cnt_p A pointer to an int. This is a result parameter through which the size of the array is returned.
name A pointer to a constant string which is to be split.
delims A pointer to a constant string which contains the list of delimiters to use for splitting the name.
Return values:
EINVAL An invalid argument was given.
ENOMEM Unable to allocate memory.

Definition at line 92 of file tc_break.c.

References _add_string(), stringbuf::sb_comps, stringbuf::sb_count, and treeconf_str_t.

Referenced by _tc_lookup_node(), main(), and tc_path().

Here is the call graph for this function:

unsigned int tc_destroy (  treeconf_ctx_t *  ctx  ) 
 

This function is used to clean up the library. Every configuration variable is destroyed and the memory returned to the system. The context is unusable after calling this function; it must be reinitialized by calling tc_init().

Test:
This function is tested in t_treeconf.c.
Parameters:
ctx A pointer to a treeconf_ctx_t.
Return values:
EINVAL An invalid argument was given.

Definition at line 34 of file tc_destroy.c.

References _tc_release_node, _treeconf_node_s::tn_next, treeconf_ctx_t, treeconf_node_t, _treeconf_ctx_s::tx_config, _treeconf_ctx_s::tx_count, _treeconf_ctx_s::tx_magic, and tx_verify.

Referenced by main().

unsigned int tc_find (  treeconf_ctx_t *  ctx,
const char *  name,
treeconf_node_t **  node,
treeconf_node_t *  parent
) 
 

The tc_find() function simply looks up the node named by name and returns a pointer to it via the node result parameter. The name parameter is interpreted relative to parent, if specified, or relative to the root of the configuration tree if parent is NULL. Nodes that have not been registered previously may be implicitly created if the last extant node defines a nodown callback and that callback returns non-zero.

Test:
This function is tested in t_treeconf.c.
Parameters:
ctx A pointer to a treeconf_ctx_t.
name A pointer to a constant string naming the node.
node A pointer to a pointer to a treeconf_node_t into which a pointer to the node will be placed.
parent A pointer to a treeconf_node_t designating the root of the subtree under which this node may be found. If NULL, the node will be looked up relative to the tree in the context.
Return values:
EINVAL An invalid argument was given.
ENOMEM Unable to allocate memory.
ENOENT No node by that name and not permitted to implicitly register one.

Definition at line 36 of file tc_find.c.

References _tc_create_node(), _tc_doerror, _tc_lookup_node(), _tn_call_nodown, result::r_comps, result::r_count, result::r_node, result::r_startnew, TC_NODETYPE_IMPLICIT, TC_NODETYPE_NODE, TC_NODETYPE_VARIABLE, _treeconf_node_s::tn_change, _treeconf_node_s::tn_context, _treeconf_node_s::tn_nodown, tn_verify, treeconf_ctx_t, treeconf_node_t, _treeconf_str_s::ts_length, _treeconf_str_s::ts_string, and tx_verify.

Referenced by main(), and tc_load().

Here is the call graph for this function:

unsigned int tc_get (  treeconf_ctx_t *  ctx,
const char *  name,
const char **  value,
treeconf_node_t *  parent
) 
 

The tc_get() function obtains the value of the variable named by the name parameter. The name is interpreted relative to parent, if specified, or relative to the root of the configuration tree if parent is NULL. The value of the node is returned via the value result parameter.

Test:
This function is tested in t_treeconf.c.
Parameters:
ctx A pointer to a treeconf_ctx_t.
name A pointer to a constant string naming the node.
value A pointer to a pointer to a string into which a pointer to the value string will be placed.
parent A pointer to a treeconf_node_t designating the root of the subtree under which this node may be found. If NULL, the node will be looked up relative to the tree in the context.
Return values:
EINVAL An invalid argument was given.
ENOMEM Unable to allocate memory.
ENOENT No node by that name.
TC_ERR_MISMATCH The named node is a tree node, not a variable node.

Definition at line 36 of file tc_get.c.

References _tc_lookup_node(), result::r_comps, result::r_count, result::r_node, result::r_startnew, _treeconf_node_s::tn_context, _treeconf_node_s::tn_type, _treeconf_node_s::tn_value, tn_verify, treeconf_ctx_t, treeconf_node_t, and tx_verify.

Referenced by main().

Here is the call graph for this function:

unsigned int tc_load (  const char *  file,
void *  ctx
) 
 

This is a convenience function for loading a configuration from a file or a set of files. Its signature matches that of the treeconf_file_t callback function so that it may be used with the tc_path() function.

The configuration file format is loosely based on the Windows INI format. Basically, it consists of a number of key-equals-value pairs, with each such pair terminated by a semicolon (';'). Additionally, keys (or variable names) may be interpreted relative to some base node by specifying those keys after the name of the base node enclosed in square brackets ('[]'). Keys followed immediately by a semicolon cause the corresponding variable to be reset to its default value; empty square brackets force all following keys to be interpreted relative to the root of the configuration tree.

The tc_load() function may return any of the errors specified for tc_find(), tc_set(), open(), or read().

Test:
This function is tested in t_tc_load.c.
Parameters:
file A pointer to a constant string naming the configuration file.
ctx A pointer to a treeconf_ctx_t. This is declared as a void * in order to be compatible with the signature of the tc_path() callback.
Return values:
EINVAL An invalid argument was given or the file is invalid.
ENOMEM Unable to allocate memory.
ENOENT A named node does not exist and cannot be created, or file does not exist.
TC_ERR_MISMATCH A named node is a tree node, not a variable node.

Definition at line 203 of file tc_load.c.

References _tc_doerror, accum, clear, cunget, finish, Q_O, Q_S, Q_X, quoted, tc_find(), tc_set(), treeconf_ctx_t, treeconf_node_t, tx_verify, and xlate.

Referenced by main().

Here is the call graph for this function:

unsigned int tc_path (  const char *  path,
const char *  def,
treeconf_subst_t  substs[],
int  s_cnt,
unsigned int  flags,
treeconf_file_t  call,
void *  call_data
) 
 

The tc_path() function is a helper function designed to find one or more readable files in a colon-separated list of files. It performs a variety of substitutions, including inserting a default search string if the given path contains an empty field; expansion of user home directories via the ~ mechanism; and arbitrary, caller-defined substitutions of the form %c, where c may be any single character. The path to search is given via the path parameter, which may be NULL if no user-defined path was given. The default path to search---which may not be NULL---is given via the def parameter. All caller-defined substitutions are defined by creating an array of treeconf_subst_t structures, which is passed via the substs parameter; the number of elements in that array is passed via the s_cnt parameter. Flags controlling how tc_path() searches the path are passed in via the flags parameter.

For the first readable file in the path (or for all readable files, if the TC_PATH_ALL flag was used), the function specified by the function pointer call will be called with that file name and extra data specified by call_data.

For more information about substitutions, see the documentation for treeconf_subst_t and the TC_SUBST_INSECURE, TC_SUBST_INIT(), tu_char(), tu_value(), and tu_flags() macros. For more information on the callback function, see the documentation for treeconf_file_t. For the possible flags that may be given, see the documentation for TC_PATH_SECURE and TC_PATH_ALL.

Note:
This mechanism is not designed to handle file races. It should not be used for files that are to be written or which are expected to live in /tmp.

Test:
This function is tested in t_tc_path.c.
Parameters:
path A pointer to a string specifying the search path, or NULL if none is given.
def A pointer to a string specifying the default search path. This parameter may not be NULL.
substs An array of treeconf_subst_t structures specifying all caller-specified substitutions.
s_cnt An int containing the number of caller-specified substitution rules passed in the substs parameter.
flags An unsigned int specifying flags to control the path search.
call A treeconf_file_t function pointer.
call_data Extra data to pass to the call function.
Return values:
EINVAL An invalid argument was given.
ENOMEM Unable to allocate memory.
ENOENT No such user in a tilde expansion.

Definition at line 349 of file tc_path.c.

References _subst(), buf::str, substs, tc_break(), TC_PATH_SECURE, treeconf_str_t, treeconf_subst_t, and _treeconf_str_s::ts_length.

Referenced by do_test(), and main().

Here is the call graph for this function:

unsigned int tc_register (  treeconf_ctx_t *  ctx,
const char *  name,
const char *  def,
treeconf_node_t *  parent,
treeconf_nodown_t  nodown,
treeconf_change_t  change,
void *  assoc
) 
 

The tc_register() function registers a configuration node with the library. A given configuration node may be either a variable node, which may have a value, or a tree node, which may have children. A variable node may not have children, and a tree node may not have a value. Variable nodes are created by passing a non-NULL value for def.

The name of the node to register is given by the constant string name. If the parent parameter is NULL, the name is interpreted as an absolute path from the root of the tree; otherwise, the name is interpreted as a relative path from that parent node.

Finally, the nodown and change parameters specify callback functions for implicit creation of nodes and for value changes, respectively. For more information about these callbacks, see the documentation for treeconf_nodown_t and tn_nodown(), and treeconf_change_t and tn_change().

Test:
This function is tested in t_treeconf.c.
Parameters:
ctx A pointer to a treeconf_ctx_t.
name A pointer to a constant string naming the node to register.
def A pointer to a string listing the default value of a variable node. If NULL, a tree node will be created. The string will be copied into allocated memory, so the caller may deallocate this parameter safely.
parent A pointer to a treeconf_node_t designating the root of the subtree under which this node will be created. If NULL, the node will be created relative to the tree in the context.
nodown A treeconf_nodown_t function pointer.
change A treeconf_change_t function pointer.
assoc A pointer to void designating application-specific association data.
Return values:
EINVAL An invalid argument was given.
ENOMEM Unable to allocate memory.
TC_ERR_MULTREG Node has already been registered.

Definition at line 36 of file tc_register.c.

References _tc_create_node(), _tc_doerror, _tc_lookup_node(), _tc_release_children(), _tn_call_change, result::r_comps, result::r_count, result::r_node, result::r_startnew, TC_NODETYPE_NODE, TC_NODETYPE_VARIABLE, _treeconf_node_s::tn_assoc, _treeconf_node_s::tn_change, _treeconf_node_s::tn_context, _treeconf_node_s::tn_default, _treeconf_node_s::tn_down, _treeconf_node_s::tn_nodown, _treeconf_node_s::tn_parent, _treeconf_node_s::tn_type, _treeconf_node_s::tn_value, tn_verify, treeconf_ctx_t, treeconf_node_t, treeconf_type_t, _treeconf_str_s::ts_length, _treeconf_str_s::ts_string, and tx_verify.

Referenced by load_results(), and main().

Here is the call graph for this function:

unsigned int tc_set (  treeconf_ctx_t *  ctx,
const char *  name,
const char *  value,
treeconf_node_t *  parent
) 
 

The tc_set() function sets the variable named by name to the specified value. The name parameter is interpreted relative to parent, if specified, or relative to the root of the configuration tree if parent is NULL. Nodes that have not been registered previously may be implicitly created if the last extant node defines a nodown callback and that callback returns non-zero.

Test:
This function is tested in t_treeconf.c.
Parameters:
ctx A pointer to a treeconf_ctx_t.
name A pointer to a constant string naming the node.
value A pointer to a string containing the value to give the variable node. If NULL, the value will revert to the default value. The string will be copied into allocated memory, so the caller may deallocate this parameter safely.
parent A pointer to a treeconf_node_t designating the root of the subtree under which this node may be found. If NULL, the node will be looked up relative to the tree in the context.
Return values:
EINVAL An invalid argument was given.
ENOMEM Unable to allocate memory.
ENOENT No node by that name and not permitted to implicitly register one.
TC_ERR_MISMATCH The named node is a tree node, not a variable node.

Definition at line 76 of file tc_set.c.

References _tc_create_node(), _tc_doerror, _tc_lookup_node(), _tc_release_children(), _tc_set(), _tn_call_nodown, result::r_comps, result::r_count, result::r_node, result::r_startnew, TC_NODETYPE_IMPLICIT, TC_NODETYPE_NODE, TC_NODETYPE_VARIABLE, _treeconf_node_s::tn_change, _treeconf_node_s::tn_context, _treeconf_node_s::tn_nodown, _treeconf_node_s::tn_type, tn_verify, treeconf_ctx_t, treeconf_node_t, _treeconf_str_s::ts_length, _treeconf_str_s::ts_string, and tx_verify.

Referenced by main(), and tc_load().

Here is the call graph for this function:

Generated on Wed Jun 8 09:18:41 2005 for treeconf by  doxygen 1.3.9.1