FreeBSD Manual Pages
cfg(3m) MBA Library Functions cfg(3m) NAME cfg - persistent configuration properties interface SYNOPSIS #include <mba/cfg.h> int cfg_init(struct cfg *cfg, struct allocator *al); int cfg_deinit(struct cfg *cfg); struct cfg *cfg_new(struct allocator *al); int cfg_del(void *cfg); int cfg_load(struct cfg *cfg, const char *filename); int cfg_load_str(struct cfg *cfg, const tchar *src, const tchar *slim); int cfg_load_env(struct cfg *cfg); int cfg_load_cgi_query_string(struct cfg *cfg, const tchar *qs); int cfg_store(struct cfg *cfg, const char *filename); int cfg_fwrite(struct cfg *cfg, FILE *stream); void cfg_iterate(void *cfg, iter_t *iter); const tchar *cfg_next(void *cfg, iter_t *iter); int cfg_get_str(struct cfg *cfg, tchar *dst, int dn, const tchar *def, const tchar *name); int cfg_vget_str(struct cfg *cfg, tchar *dst, int dn, const tchar *def, const tchar *name, ...); int cfg_get_short(struct cfg *cfg, short *dst, short def, const tchar *name); int cfg_get_int(struct cfg *cfg, int *dst, int def, const tchar *name); int cfg_get_long(struct cfg *cfg, long *dst, long def, const tchar *name); int cfg_vget_short(struct cfg *cfg, short *dst, short def, const tchar *name, ...); int cfg_vget_int(struct cfg *cfg, int *dst, int def, const tchar *name, ...); int cfg_vget_long(struct cfg *cfg, long *dst, long def, const tchar *name, ...); DESCRIPTION The cfg(3m) module provides an interface to load and store comments and key/value pairs. A small state machine parser preserves all space tokens and comments in order between loading, manipulating, and storing cfg files. The following is a sample of serialized properties (the cfg file format): # This is a comment addr = 192.168.1.15 !port = 15000 user.1 = miallen user.2 = gchan Lines beginning with the '#' and '!' characters will be interpreted as com- ments. Keys are separated from values with '='. Reserved characters, lead- ing and trailing spaces, and Unicode are supported with '\' escapes. If USE_WCHAR is defined, strings are wchar_t. Otherwise string encoding is locale dependant. See the HTML documentation for the text module. init The cfg_init function initializes a cfg object. The object will have no properties. Memory for all cfg operations will be allocated from the allocator al. It may be necessary to call cfg_deinit to release memory allocated from the allocator al. deinit The cfg_deinit function frees any resources associated with this cfg object. It is not necessary to deinitialize a cfg object if the mem- ory backing it's allocator can be freed separately (e.g. using a suba(3m) allocator backed with stack memory is more efficient). new The cfg_new function allocates memory from the allocator specified by the al parameter, initializes it with cfg_init, and returns a pointer to the new cfg object. The object will have no properties. The allocator specified by the al parameter will be used for all further memory management associated with this object. It may be necessary to call cfg_del to release memory allocated from the allo- cator al. del The cfg_del function frees the cfg object and all properties within it. It is not necessary to delete a cfg object if the memory backing it's allocator can be freed separately (e.g. using a suba(3m) allo- cator backed with stack memory is more efficent). load The cfg_load function loads the properties in filename into the cfg object cfg. load_str The cfg_load_str function loads properties into this cfg object from the character string at src up to but not including the memory at slim. load_env The cfg_load_env function loads the process environment as proper- ties. load_cgi_query_string The cfg_load_cgi_query_string function parses a QUERY_STRING style string like the one below which would result in loading properties 'hl', 'lr', 'ie', 'oe' and 'group' with their respective values. Pa- rameters with no values such as 'lr' will be loaded with an empty string. hl=en&lr=&ie=UTF-8&oe=UTF-8&group=comp.unix.programmer store The cfg_store function serializes the properties of the object cfg and stores them in filename. fwrite The cfg_fwrite function serializes the properties of the object cfg and stores them in filename. iterate, next Enumerate each key in this cfg object. The cfg_iterate function ini- tializes iter with the position of the first property in this cfg. With each subsequent call to cfg_next the key of each property is returned or NULL if all keys have been enumerated. get_str The cfg_get_str function retrieves a property identified by name into the memory spcecified by dst as a string. No more than dn bytes of dst will be written to. If the value is truncated a trailing '\0' will be included. If the named property is not in the list and the string def is not NULL, def will be copied into dst. vget_str The cfg_vget_str function retrieves a property identified by name into the memory spcecified by dst as a string. The name parameter is a format specifier that is parsed by vsprintf(3) before being passed to cfg_get_str. This permits complex keys to be constructed in- situ. To iterate over each element in a list of at most 10 proper- ties named user.0, user.1, user.2, ... the following might be used: for (i = 0; i < 10; i++) if (cfg_vget_str(cfg, buf, BUFSIZ, NULL, "user.%d", idx)) == 0) break; /* end of list */ get_short The cfg_get_short function is a convienence function that retrieves the property identified by name from cfg cfg object, converts it to a short integer with strtol(3), and stores the value in dst. If the named property does not exist, def will be copied to dst. get_int The cfg_get_int function is a convienence function that retrieves the property identified by name from cfg cfg object, converts it to an integer with strtol(3), and stores the value in dst. If the named property does not exist, def will be copied to dst. get_long The cfg_get_long function is a convienence function that retrieves the property identified by name from cfg cfg object, converts it to a long integer with strtol(3), and stores the value in dst. If the named property does not exist, def will be copied to dst. vget_short The cfg_vget_short function is a convienence function that retrieves the property identified by name from cfg cfg object, converts it to a short integer with strtol(3), and stores the value in dst. The name parameter and variable arguments are first reduced using vsprintf(3) permitting complex keys to be constructed. If the named property does not exist, def will be copied to dst. vget_int The cfg_vget_int function is a convienence function that retrieves the property identified by name from cfg cfg object, converts it to an integer with strtol(3), and stores the value in dst. The name parameter and variable arguments are first reduced using vsprintf(3) permitting complex keys to be constructed. If the named property does not exist, def will be copied to dst. vget_long The cfg_vget_long function is a convienence function that retrieves the property identified by name from cfg cfg object, converts it to a long integer with strtol(3), and stores the value in dst. The name parameter and variable arguments are first reduced using vsprintf(3) permitting complex keys to be constructed. If the named property does not exist, def will be copied to dst. RETURNS init The cfg_init function returns -1 and sets errno to an appropriate value if an error occured or 0 if the object was successfully ini- tialized. deinit The cfg_deinit function returns -1 and sets errno to an appropriate value if an error occured or 0 if resources were successfully freed. new The cfg_new function returns a new cfg object if the operation suc- ceeded or NULL if the operation failed in which case errno is set appropriately. del The cfg_del function return 0 if the operation was successful or -1 if it failed in which case errno will be set accordingly. load The cfg_load function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the properties were success- fully loaded. load_env The cfg_load_env function returns -1 and sets errno to an appropri- ate value if the operation failed or 0 if the process environment was successfully loaded. load_cgi_query_string The cfg_load_cgi_query_string function returns 0 if the query string parameters were valid and loaded successfully. Otherwise -1 is re- turned and errno is set appropriately. store The cfg_store function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the properties were success- fully stored. fwrite The cfg_fwrite function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the properties were success- fully written. next The cfg_next function returns the next property in this cfg object or NULL if all keys have been enumerated. get_str If the named property is not found and def is NULL or the operation fails for another reason the cfg_get_str function will return -1 and set errno to an appropriate value. Otherwise 0 is returned to indi- cate the string was successfully copied. vget_str The cfg_vget_str function returns -1 and sets errno to an appropri- ate value if the operation failed or 0 if the string was success- fully copied. get_short The cfg_get_short function returns -1 and sets errno to an appropri- ate value if the operation failed or 0 if the integer was success- fully retrieved. get_int The cfg_get_int function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the integer was successfully retrieved. get_long The cfg_get_long function returns -1 and sets errno to an appropri- ate value if the operation failed or 0 if the integer was success- fully retrieved. vget_short The cfg_vget_short function returns -1 and sets errno to an appro- priate value if the operation failed or 0 if the integer was suc- cessfully retrieved. vget_int The cfg_vget_int function returns -1 and sets errno to an appropri- ate value if the operation failed or 0 if the integer was success- fully retrieved. vget_long The cfg_vget_long function returns -1 and sets errno to an appropri- ate value if the operation failed or 0 if the integer was success- fully retrieved. libmba-0.9.1 Apr 29, 2005 cfg(3m)
NAME | SYNOPSIS | DESCRIPTION | RETURNS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=cfg&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>