GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  PARSE_CONFIG (3)

NAME

figpar, parse_config, get_config_option - configuration file parsing library

CONTENTS

Library
Synopsis
Description
See Also
History
Authors
Bugs

LIBRARY


.Lb libfigpar

SYNOPSIS


.In figpar.h int
.Fo parse_config struct figpar_config options[], const char *path int lp]*unknownrp]lp]struct figpar_config *option, uint32_t line char *directive, char *valuerp], uint8_t processing_options
.Fc struct figpar_config *
.Fo get_config_option struct figpar_config options[], const char *directive
.Fc
.In string_m.h int
.Fo replaceall char *source, const char *find, const char *replace
.Fc unsigned int
.Fo strcount const char *source, const char *find
.Fc void
.Fo strexpand char *source
.Fc void
.Fo strexpandnl char *source
.Fc void
.Fo strtolower char *source
.Fc

DESCRIPTION

The figpar library provides a light-weight, portable framework for parsing configuration files. The library uses open(2), read(2), and lseek(2) within the file pointed to by path to find directives and values which are then made available to the application.

Due to the fact that configuration files may have basic syntax differences, the library does not attempt to impose any structure on the data but instead provides raw data to a set of callback functions. These callback functions can in-turn initiate abort through their return value, allowing custom syntax validation during parsing.

Configuration directives, types, and callback functions are provided through data structures defined in
.In figpar.h :

struct figpar_config {
    enum figpar_cfgtype         type;           /* value type */
    const char                  *directive;     /* keyword */
    union figpar_cfgvalue       value;          /* value */

/* Pointer to function used when directive is found */ int (*action)(struct figpar_config *option, uint32_t line, char *directive, char *value); };

enum figpar_cfgtype { FIGPAR_TYPE_NONE = 0x0000, /* directives with no value */ FIGPAR_TYPE_BOOL = 0x0001, /* boolean */ FIGPAR_TYPE_INT = 0x0002, /* signed 32 bit integer */ FIGPAR_TYPE_UINT = 0x0004, /* unsigned 32 bit integer */ FIGPAR_TYPE_STR = 0x0008, /* string pointer */ FIGPAR_TYPE_STRARRAY = 0x0010, /* string array pointer */ FIGPAR_TYPE_DATA1 = 0x0020, /* void data type-1 (open) */ FIGPAR_TYPE_DATA2 = 0x0040, /* void data type-2 (open) */ FIGPAR_TYPE_DATA3 = 0x0080, /* void data type-3 (open) */ FIGPAR_TYPE_RESERVED1 = 0x0100, /* reserved data type-1 */ FIGPAR_TYPE_RESERVED2 = 0x0200, /* reserved data type-2 */ FIGPAR_TYPE_RESERVED3 = 0x0400, /* reserved data type-3 */ };

union figpar_cfgvalue { void        *data; /* Pointer to NUL-terminated string */ char        *str; /* Pointer to NUL-terminated string */ char        **strarray; /* Pointer to an array of strings */ int32_t     num; /* Signed 32-bit integer value */ uint32_t    u_num; /* Unsigned 32-bit integer value */ uint32_t    boolean:1; /* Boolean integer value (0 or 1) */ };

The processing_options argument to parse_config is a mask of bit fields which indicate various processing options. The possible flags are as follows:
FIGPAR_BREAK_ON_EQUALS An equals sign (‘=’) is normally considered part of the directive. This flag enables terminating the directive at the equals sign. Also makes equals sign optional and transient.
FIGPAR_BREAK_ON_SEMICOLON
  A semicolon (‘\;’) is normally considered part of the value. This flag enables terminating the value at the semicolon. Also allows multiple statements on a single line separated by semicolon.
FIGPAR_CASE_SENSITIVE Normally directives are matched case insensitively using fnmatch(3). This flag enables directive matching to be case sensitive.
FIGPAR_REQUIRE_EQUALS If a directive is not followed by an equals, processing is aborted.
FIGPAR_STRICT_EQUALS Equals must be part of the directive to be considered a delimiter between directive and value.

The options struct array pointer can be NULL and every directive will invoke the unknown function argument.

The directive for each figpar_config item in the parse_config options argument is matched against each parsed directive using fnmatch(3) until a match is found. If a match is found, the action function for that figpar_config directive is invoked with the line number, directive, and value. Otherwise if no match, the unknown function is invoked (with the same arguments).

If either action or unknown return non-zero, parse_config aborts reading the file and returns the error value to its caller.

get_config_option traverses the options-array and returns the option that matches via strcmp(3), or if no match a pointer to a static dummy struct is returned (whose values are all zero or NULL).

The use of struct figpar_config is entirely optional as-is the use of enum figpar_cfgtype or union figpar_cfgvalue. For example, you could choose to pass a NULL pointer to parse_config for the first argument and then provide a simple unknown function based on queue(3) that populates a singly-linked list of your own struct containing the directive and value.

In addition, the following miscellaneous string manipulation routines are provided by
.In string_m.h :
replaceall Replace all occurrences of find in source with replace.
strcount Count the number of occurrences of one string that appear in the source string. Return value is the total count. An example use would be if you need to know how large a block of memory needs to be for a replaceall series.
strexpand Expand escape sequences in a buffer pointed to by source.
strexpandnl Expand only the escaped newlines in a buffer pointed to by source.
strtolower Convert a string to lower case.

SEE ALSO

queue(3)

HISTORY

The figpar library first appeared in
.Fx 10.2 .

AUTHORS


.An Devin Teske Aq dteske@FreeBSD.org

BUGS

This is the first implementation of the library, and the interface may be subject to refinement.
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.