·

zconfig (3) Linux Manual Page

ByLinux Manual Posted on

zconfig – work with config files written in rfc.zeromq.org/spec:4/ZPL.

Synopsis

// Function that executes config
typedef int (zconfig_fct) (zconfig_t *self, void *arg, int level);
// Create new config item
CZMQ_EXPORT zconfig_t *
 zconfig_new (const char *name, zconfig_t *parent);
// Destroy a config item and all its children
CZMQ_EXPORT void
 zconfig_destroy (zconfig_t **self_p);
// Return name of config item
CZMQ_EXPORT char *
 zconfig_name (zconfig_t *self);
// Return value of config item
CZMQ_EXPORT char *
 zconfig_value (zconfig_t *self);
// Insert or update configuration key with value
CZMQ_EXPORT void
 zconfig_put (zconfig_t *self, const char *path, const char *value);
// Equivalent to zconfig_put, accepting a format specifier and variable
// argument list, instead of a single string value.
CZMQ_EXPORT void
 zconfig_putf (zconfig_t *self, const char *path, const char *format, ...);
// Get value for config item into a string value; leading slash is optional
// and ignored.
CZMQ_EXPORT char *
 zconfig_get (zconfig_t *self, const char *path, const char *default_value);
// Set config item name, name may be NULL
CZMQ_EXPORT void
 zconfig_set_name (zconfig_t *self, const char *name);
// Set new value for config item. The new value may be a string, a printf
// format, or NULL. Note that if string may possibly contain '%', or if it
// comes from an insecure source, you must use '%s' as the format, followed
// by the string.
CZMQ_EXPORT void
 zconfig_set_value (zconfig_t *self, const char *format, ...);
// Find our first child, if any
CZMQ_EXPORT zconfig_t *
 zconfig_child (zconfig_t *self);
// Find our first sibling, if any
CZMQ_EXPORT zconfig_t *
 zconfig_next (zconfig_t *self);
// Find a config item along a path; leading slash is optional and ignored.
CZMQ_EXPORT zconfig_t *
 zconfig_locate (zconfig_t *self, const char *path);
// Locate the last config item at a specified depth
CZMQ_EXPORT zconfig_t *
 zconfig_at_depth (zconfig_t *self, int level);
// Execute a callback for each config item in the tree; returns zero if
// successful, else -1.
CZMQ_EXPORT int
 zconfig_execute (zconfig_t *self, zconfig_fct handler, void *arg);
// Add comment to config item before saving to disk. You can add as many
// comment lines as you like. If you use a null format, all comments are
// deleted.
CZMQ_EXPORT void
 zconfig_set_comment (zconfig_t *self, const char *format, ...);
// Return comments of config item, as zlist.
CZMQ_EXPORT zlist_t *
 zconfig_comments (zconfig_t *self);
// Load a config tree from a specified ZPL text file; returns a zconfig_t
// reference for the root, if the file exists and is readable. Returns NULL
// if the file does not exist.
CZMQ_EXPORT zconfig_t *
 zconfig_load (const char *filename);
// Save a config tree to a specified ZPL text file, where a filename
// "-" means dump to standard output.
CZMQ_EXPORT int
 zconfig_save (zconfig_t *self, const char *filename);
// Equivalent to zconfig_load, taking a format string instead of a fixed
// filename.
CZMQ_EXPORT zconfig_t *
 zconfig_loadf (const char *format, ...);
// Equivalent to zconfig_save, taking a format string instead of a fixed
// filename.
CZMQ_EXPORT int
 zconfig_savef (zconfig_t *self, const char *format, ...);
// Report filename used during zconfig_load, or NULL if none
CZMQ_EXPORT const char *
 zconfig_filename (zconfig_t *self);
// Reload config tree from same file that it was previously loaded from.
// Returns 0 if OK, -1 if there was an error (and then does not change
// existing data).
CZMQ_EXPORT int
 zconfig_reload (zconfig_t **self_p);
// Load a config tree from a memory chunk
CZMQ_EXPORT zconfig_t *
 zconfig_chunk_load (zchunk_t *chunk);
// Save a config tree to a new memory chunk
CZMQ_EXPORT zchunk_t *
 zconfig_chunk_save (zconfig_t *self);
// Load a config tree from a null-terminated string
CZMQ_EXPORT zconfig_t *
 zconfig_str_load (const char *string);
// Save a config tree to a new null terminated string
CZMQ_EXPORT char *
 zconfig_str_save (zconfig_t *self);
// Return true if a configuration tree was loaded from a file and that
// file has changed in since the tree was loaded.
CZMQ_EXPORT bool
 zconfig_has_changed (zconfig_t *self);
// Print the config file to open stream
CZMQ_EXPORT void
 zconfig_fprint (zconfig_t *self, FILE *file);
// Print the config file to stdout
CZMQ_EXPORT void
 zconfig_print (zconfig_t *self);

Description

Lets applications load, work with, and save configuration files. This implements rfc.zeromq.org/spec:4/ZPL, which is a simple structured text format for configuration files.

Here is an example ZPL stream and corresponding config structure: 

context
 iothreads = 1
 verbose = 1 # Ask for a trace
main
 type = zqueue # ZMQ_DEVICE type
 frontend
 option
 hwm = 1000
 swap = 25000000 # 25MB
 bind = 'inproc://addr1'
 bind = 'ipc://addr2'
 backend
 bind = inproc://addr3
root Down = child
| Across = next
v
context-->main
| |
| v
| type=queue-->frontend-->backend
| | |
| | v
| | bind=inproc://addr3
| v
| option-->bind=inproc://addr1-->bind=ipc://addr2
| |
| v
| hwm=1000-->swap=25000000
v
iothreads=1-->verbose=false

Example

From zconfig_test method. 

//  Create temporary directory for test files
#define TESTDIR ".test_zconfig"
zsys_dir_create(TESTDIR);

zconfig_t *root = zconfig_new("root", NULL);
assert(root);
zconfig_t *section, *item;

section = zconfig_new("headers", root);
assert(section);
item = zconfig_new("email", section);
assert(item);
zconfig_set_value(item, "some [at] random.com");
item = zconfig_new("name", section);
assert(item);
zconfig_set_value(item, "Justin Kayce");
zconfig_putf(root, "/curve/secret-key", "%s", "Top Secret");
zconfig_set_comment(root, "   CURVE certificate");
zconfig_set_comment(root, "   -----------------");
assert(zconfig_comments(root));
zconfig_save(root, TESTDIR "/test.cfg");
zconfig_destroy(&root);
root = zconfig_load(TESTDIR "/test.cfg");
if (verbose)
    zconfig_save(root, "-");
assert(streq(zconfig_filename(root), TESTDIR "/test.cfg"));

char *email = zconfig_get(root, "/headers/email", NULL);
assert(email);
assert(streq(email, "some [at] random.com"));
char *passwd = zconfig_get(root, "/curve/secret-key", NULL);
assert(passwd);
assert(streq(passwd, "Top Secret"));

zconfig_savef(root, "%s/%s", TESTDIR, "test.cfg");
assert(!zconfig_has_changed(root));
int rc = zconfig_reload(&root);
assert(rc == 0);
assert(!zconfig_has_changed(root));
zconfig_destroy(&root);

//  Test chunk load/save
root = zconfig_new("root", NULL);
assert(root);
section = zconfig_new("section", root);
assert(section);
item = zconfig_new("value", section);
assert(item);
zconfig_set_value(item, "somevalue");
zconfig_t *search = zconfig_locate(root, "section/value");
assert(search == item);
zchunk_t *chunk = zconfig_chunk_save(root);
assert(strlen((char *)zchunk_data(chunk)) == 32);
char *string = zconfig_str_save(root);
assert(string);
assert(streq(string, (char *)zchunk_data(chunk)));
free(string);
assert(chunk);
zconfig_destroy(&root);

root = zconfig_chunk_load(chunk);
assert(root);
char *value = zconfig_get(root, "/section/value", NULL);
assert(value);
assert(streq(value, "somevalue"));

//  Test config can't be saved to a file in a path that doesn't
//  exist or isn't writable
rc = zconfig_savef(root, "%s/path/that/doesnt/exist/%s", TESTDIR, "test.cfg");
assert(rc == -1);

zconfig_destroy(&root);
zchunk_destroy(&chunk);

//  Delete all test files
zdir_t *dir = zdir_new(TESTDIR, NULL);
assert(dir);
zdir_remove(dir, true);
zdir_destroy(&dir);

Authors

The czmq manual was written by the authors in the AUTHORS file.

Resources

Main web site: m[blue]m[]

Report bugs to the email <m[blue]zeromq-dev [at] lists.zeromq.orgm[][1]>

Copyright

Copyright (c) 1991-2012 iMatix Corporation — http://www.imatix.com Copyright other contributors as noted in the AUTHORS file. This file is part of CZMQ, the high-level C binding for 0MQ: http://czmq.zeromq.org This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. LICENSE included with the czmq distribution.

Notes

1.

zeromq-dev [at] lists.zeromq.org

mailto:zeromq-dev [at] lists.zeromq.org

Leave a Reply

Your email address will not be published. Required fields are marked *