ggConfigIterTarget man page on Cygwin

Man page or keyword search:  
man Server   22533 pages
apropos Keyword Search (all sections)
Output format
Cygwin logo
[printable version]

ggLoadConfig(3)			      GGI		       ggLoadConfig(3)

NAME
       ggLoadConfig,  ggFreeConfig, ggConfigIterTarget, ggConfigIterLocation :
       Configuration helpers

SYNOPSIS
       int ggLoadConfig(const char *file, gg_config *config);

       void ggFreeConfig(gg_config config);

       struct gg_location_iter {
	     struct gg_iter iter;
	     const void * config;
	     const char * name;
	     char * location;
	     const char * symbol;
	     void * _state;
       };

       int ggConfigIterLocation(struct gg_location_iter * iter);

       struct gg_target_iter {
	     struct gg_iter iter;
	     void * config;
	     const char * input;
	     char * target;
	     char * options;
	     void * nested;
       };

       int ggConfigIterTarget(struct gg_target_iter *iter);

DESCRIPTION
       These functions provides a simple way of handling configuration files.

       ggLoadConfig tries to load the configuration file given	as  parameter.
       It  adds the content to the config handle found at *config. If the han‐
       dle is NULL, a new one is created.

       ggFreeConfig deletes the internal structure for the configuration  han‐
       dle config. This handle becomes invalid and should not be used anymore.

       ggConfigIterLocation allows to retreive the location and symbol associ‐
       ated to canonical names. This function is mainly used together with the
       scope  abstraction to query application modules at runtime.  This func‐
       tion will prepare the iter structure to be used	as  an	iterator  that
       will generate correct matches.  iter is a pointer to a gg_location_iter
       structure owned by the caller. This user part of the structure must  be
       set by the caller before calling ggConfigIterLocation. The config field
       must be filled with the config handle which  contains  target  informa‐
       tion;  the  name	 field	must be filled with the canonical name that is
       being looked for. location and symbol are  placeholders	in  which  the
       results	will  be found along the iteration. The resulting strings Bdo*
       belong to libgg and Bmust not* be freed or altered,  and	 they  may  be
       invalidated  if	not  used  during  the iteration process. They must be
       copied if needed later.	_state is  an  internal	 opaque	 pointer  that
       keeps  track  of the iterator state. Its value must never be touched by
       the caller.

       ggConfigIterTarget allows to iterate over canonical  target  names  and
       options strings found in a target spec string.  This function also work
       as a generator. iter is a pointer to a gg_target_iter  structure	 owned
       by the caller. This user part of the structure must be set by the call‐
       er before calling ggConfigIterTarget.  The config field must be	filled
       with  the  config  handle  which contains target information; the input
       field must be filled with the initial input spec	 string.   target  and
       options	are  placeholders in which the results will be found along the
       iteration.  Here again, the resulting strings Bdo* belong to libgg  and
       Bmust not* be freed or altered, and they may be invalidated if not used
       during the iteration process. They must	be  copied  if	needed	later.
       nested  is  an internal opaque pointer that keeps track of the iterator
       state. Its value must never be touched by the caller.

RETURN VALUE
       ggLoadConfig returns GGI_OK on success, or:

       ·   GGI_ENOMEM if it can not allocate a new configuration handle.  Note
	   that	 if  subsequent memory allocations fail (when feeding the han‐
	   dle), those will not be reported as an error. The  handle  will  be
	   incomplete with regard to the config file contents;

       ·   GGI_ENOTFOUND  if the file does not exists. Note that missing files
	   in include directives will not be reported an  error.  Also,	 other
	   parse error in the file will simply cause the incriminated lines to
	   be ignored.

       ggConfigIterLocation returns GGI_OK on success or GGI_ENOMEM.

       ggConfigIterTarget always return GGI_OK and will never fail.

CONFIG FILE FORMAT
       The configuration file is line oriented. Each line may define a mapping
       between a canonical name and a location. The generic format is:

       <pattern>  <location>[:<symbol>]

       alias <name> <expansion>

       On the first line pattern is a canonical name that may contain one * as
       a wildcard, location is a string that corresponds to a scope  location,
       and  symbol  is an optional string that gives the name of the symbol to
       retreive from the scope. If not given, NULL will be reported. The  sec‐
       ond  line  defines  an  alias. When a target called name is found while
       iterating over target spec strings, the iterator parse expansion	 as  a
       sub-input  spec,	 and  aggregate all option strings that where found on
       upstream aliases.

       In addition, the configuration file loader knowns the following	direc‐
       tives:

       When  locations	following  the	.root  directive are given as relative
       path, path will be prepended. .include will parse the given file recur‐
       sively, before continuing with the current one.

EXAMPLE
       This code demonstrates how to get the first module init function acces‐
       sible from a scope for a given name. It also shows how to use the libgg
       iterator scheme:

       int openModule(gg_config cfg, const char * moduleName,
				     const char * defaultSymbol) {
	 struct gg_location_iter match;
	 gg_scope scope;
	 module_init_func *init;

	 /* prepare the iterator */

	 match.name = name;
	 match.config = cfg;
	 ggConfigMatchIter(&match);

	 /* iterate over the matches */

	 GG_ITER_FOREACH(&match) {

	    /* try to retreive the collection at suggested location */
	    if((scope = ggGetScope(match.location)) == NULL)
		      continue;

	    /* use default symbol if none suggested */
	    if (match.symbol == NULL) match.symbol = defaultSymbol;

	    /* try to retreive the symbol from that scope */
	    if((init = ggFromScope(scope, match.symbol)) == NULL) {
		     ggDelScope(scope);
		     continue;
	    }
	    /* try to initialize the module */
	    if(init() != GGI_OK) {
		     ggDelScope(scope);
		     continue;
	    }
	    /* the module is up, abort iteration and return */
	    GG_ITER_DONE(&match);
	    return GGI_OK;
	 }

	 /* module not found */
	 GG_ITER_DONE(&match);
	 return GGI_ENOTFOUND;

       Note that this code is not completely correct, because the scope cannot
       be deleted later if it is not remembered somewhere.  This next  example
       shows how to list all targets and options specified by a string:

       static void showAllTargets(void * cfg, const char * input)
       {
	     struct gg_target_iter match;

	     match.config = cfg;
	     match.input = input;
	     ggConfigIterTarget(&match);
	     GG_ITER_FOREACH(&match) {
		     printf("Target \"%s\" with options \"%s\".\n",
			    match.target, match.options);
	     }
	     GG_ITER_DONE(&match);
       }

SEE ALSO
       ggGetScope(3)

libgg-1.0.x			  2005-08-26		       ggLoadConfig(3)
[top]

List of man pages available for Cygwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net