Version 10.0.2
WT_CONFIG_PARSER Struct Reference

A handle that can be used to search and traverse configuration strings compatible with WiredTiger APIs. More...

Public Member Functions

int close (WT_CONFIG_PARSER *config_parser)
 Close the configuration scanner releasing any resources. More...
 
int next (WT_CONFIG_PARSER *config_parser, WT_CONFIG_ITEM *key, WT_CONFIG_ITEM *value)
 Return the next key/value pair. More...
 
int get (WT_CONFIG_PARSER *config_parser, const char *key, WT_CONFIG_ITEM *value)
 Return the value of an item in the configuration string. More...
 

Detailed Description

A handle that can be used to search and traverse configuration strings compatible with WiredTiger APIs.

To parse the contents of a list or nested configuration string use a new configuration parser handle based on the content of the WT_CONFIG_ITEM retrieved from the parent configuration string.

Configuration String Parsing examples

This could be used in C to create a configuration parser as follows:

const char *config_string = "path=/dev/loop,page_size=1024,log=(file_max=20MB,remove=true)";
error_check(
wiredtiger_config_parser_open(NULL, config_string, strlen(config_string), &parser));
error_check(parser->close(parser));

Once the parser has been created the content can be queried directly:

int64_t my_page_size;
/*
* Retrieve the value of the integer configuration string "page_size".
*/
error_check(parser->get(parser, "page_size", &v));
my_page_size = v.val;

Or the content can be traversed linearly:

/*
* Retrieve and print the values of the configuration strings.
*/
while ((ret = parser->next(parser, &k, &v)) == 0) {
printf("%.*s:", (int)k.len, k.str);
if (v.type == WT_CONFIG_ITEM_NUM)
printf("%" PRId64 "\n", v.val);
else
printf("%.*s\n", (int)v.len, v.str);
}
scan_end_check(ret == WT_NOTFOUND);

Nested configuration values can be queried using a shorthand notation:

/*
* Retrieve the value of the nested log file_max configuration string using dot shorthand.
* Utilize the configuration parsing automatic conversion of value strings into an integer.
*/
v.type = WT_CONFIG_ITEM_NUM;
error_check(parser->get(parser, "log.file_max", &v));
printf("log file max: %" PRId64 "\n", v.val);

Nested configuration values can be traversed using multiple WT_CONFIG_PARSER handles:

{
WT_CONFIG_PARSER *sub_parser;
while ((ret = parser->next(parser, &k, &v)) == 0) {
if (v.type == WT_CONFIG_ITEM_STRUCT) {
printf("Found nested configuration: %.*s\n", (int)k.len, k.str);
error_check(wiredtiger_config_parser_open(NULL, v.str, v.len, &sub_parser));
while ((ret = sub_parser->next(sub_parser, &k, &v)) == 0)
printf("\t%.*s\n", (int)k.len, k.str);
scan_end_check(ret == WT_NOTFOUND);
error_check(sub_parser->close(sub_parser));
}
}
scan_end_check(ret == WT_NOTFOUND);
Examples
ex_file_system.c.

Member Function Documentation

◆ close()

int WT_CONFIG_PARSER::close ( WT_CONFIG_PARSER config_parser)

Close the configuration scanner releasing any resources.

Parameters
config_parserthe configuration parser handle
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_file_system.c.

◆ get()

int WT_CONFIG_PARSER::get ( WT_CONFIG_PARSER config_parser,
const char *  key,
WT_CONFIG_ITEM value 
)

Return the value of an item in the configuration string.

Parameters
config_parserthe configuration parser handle
keyconfiguration key string
valuethe returned value
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ next()

int WT_CONFIG_PARSER::next ( WT_CONFIG_PARSER config_parser,
WT_CONFIG_ITEM key,
WT_CONFIG_ITEM value 
)

Return the next key/value pair.

If an item has no explicitly assigned value, the item will be returned in key and the value will be set to the boolean "true" value.

Parameters
config_parserthe configuration parser handle
keythe returned key
valuethe returned value
Returns
zero on success and a non-zero error code on failure. See Error handling for details. When iteration would pass the end of the configuration string WT_NOTFOUND will be returned.
Examples
ex_file_system.c.
WT_CONFIG_ITEM::val
int64_t val
The numeric value of a configuration boolean or integer.
Definition: wiredtiger.in:3535
WT_CONFIG_ITEM::type
enum WT_CONFIG_ITEM::@0 type
Permitted values of the type field.
WT_CONFIG_PARSER::close
int close(WT_CONFIG_PARSER *config_parser)
Close the configuration scanner releasing any resources.
WT_CONFIG_ITEM::str
const char * str
The value of a configuration string.
Definition: wiredtiger.in:3520
WT_CONFIG_PARSER
A handle that can be used to search and traverse configuration strings compatible with WiredTiger API...
Definition: wiredtiger.in:3636
WT_CONFIG_PARSER::next
int next(WT_CONFIG_PARSER *config_parser, WT_CONFIG_ITEM *key, WT_CONFIG_ITEM *value)
Return the next key/value pair.
WT_CONFIG_ITEM::len
size_t len
The number of bytes in the value referenced by str.
Definition: wiredtiger.in:3523
WT_CONFIG_PARSER::get
int get(WT_CONFIG_PARSER *config_parser, const char *key, WT_CONFIG_ITEM *value)
Return the value of an item in the configuration string.
wiredtiger_config_parser_open
int wiredtiger_config_parser_open(WT_SESSION *session, const char *config, size_t len, WT_CONFIG_PARSER **config_parserp)
Create a handle that can be used to parse or create configuration strings compatible with WiredTiger ...
WT_NOTFOUND
#define WT_NOTFOUND
Item not found.
Definition: wiredtiger.in:3798
WT_CONFIG_ITEM
The configuration information returned by the WiredTiger configuration parsing functions in the WT_EX...
Definition: wiredtiger.in:3509