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
ZCONFIG(3) CZMQ Manual ZCONFIG(3)

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

//  This is a stable class, and may not change except for emergencies. It
//  is provided in stable builds.
//  This class has draft methods, which may change over time. They are not
//  in stable releases, by default. Use --enable-drafts to enable.
//
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);
// 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);
// Equivalent to zconfig_load, taking a format string instead of a fixed // filename. CZMQ_EXPORT zconfig_t * zconfig_loadf (const char *format, ...) CHECK_PRINTF (1);
// 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, ...) CHECK_PRINTF (3);
// 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, ...) CHECK_PRINTF (2);
// 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, ...) CHECK_PRINTF (2);
// Return comments of config item, as zlist. CZMQ_EXPORT zlist_t * zconfig_comments (zconfig_t *self);
// 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_save, taking a format string instead of a fixed // filename. CZMQ_EXPORT int zconfig_savef (zconfig_t *self, const char *format, ...) CHECK_PRINTF (2);
// 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 // Caller owns return value and must destroy it when done. CZMQ_EXPORT zconfig_t * zconfig_str_load (const char *string);
// Save a config tree to a new null terminated string // Caller owns return value and must destroy it when done. 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 properties of object CZMQ_EXPORT void zconfig_print (zconfig_t *self);
// Self test of this class CZMQ_EXPORT void zconfig_test (bool verbose);
#ifdef CZMQ_BUILD_DRAFT_API // *** Draft method, for development use, may change without warning *** // Destroy subtree (all children) CZMQ_EXPORT void zconfig_remove_subtree (zconfig_t *self);
// *** Draft method, for development use, may change without warning *** // Destroy node and subtree (all children) CZMQ_EXPORT void zconfig_remove (zconfig_t **self_p);
#endif // CZMQ_BUILD_DRAFT_API Please add '@interface' section in './../src/zconfig.c'.

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

From zconfig_test method.
const char *SELFTEST_DIR_RW = "src/selftest-rw";
const char *testbasedir = ".test_zconfig"; const char *testfile = "test.cfg"; char *basedirpath = NULL; // subdir in a test, under SELFTEST_DIR_RW char *filepath = NULL; // pathname to testfile in a test, in dirpath
basedirpath = zsys_sprintf ("%s/%s", SELFTEST_DIR_RW, testbasedir); assert (basedirpath); filepath = zsys_sprintf ("%s/%s", basedirpath, testfile); assert (filepath);
// Make sure old aborted tests do not hinder us zdir_t *dir = zdir_new (basedirpath, NULL); if (dir) { zdir_remove (dir, true); zdir_destroy (&dir); } zsys_file_delete (filepath); zsys_dir_delete (basedirpath);
// Create temporary directory for test files zsys_dir_create (basedirpath);
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@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, filepath); zconfig_destroy (&root); root = zconfig_load (filepath); if (verbose) zconfig_save (root, "-"); assert (streq (zconfig_filename (root), filepath));
char *email = zconfig_get (root, "/headers/email", NULL); assert (email); assert (streq (email, "some@random.com")); char *passwd = zconfig_get (root, "/curve/secret-key", NULL); assert (passwd); assert (streq (passwd, "Top Secret"));
zconfig_savef (root, "%s/%s", basedirpath, testfile); 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))); freen (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", basedirpath, testfile); assert (rc == -1);
zconfig_destroy (&root); zchunk_destroy (&chunk);
// Test str_load zconfig_t *config = zconfig_str_load ( "malamute\n" " endpoint = ipc://@/malamute\n" " producer = STREAM\n" " consumer\n" " STREAM2 = .*\n" " STREAM3 = HAM\n" "server\n" " verbose = true\n" ); assert (config); assert (streq (zconfig_get (config, "malamute/endpoint", NULL), "ipc://@/malamute")); assert (streq (zconfig_get (config, "malamute/producer", NULL), "STREAM")); assert (zconfig_locate (config, "malamute/consumer"));
zconfig_t *c = zconfig_child (zconfig_locate (config, "malamute/consumer")); assert (c); assert (streq (zconfig_name (c), "STREAM2")); assert (streq (zconfig_value (c), ".*"));
c = zconfig_next (c); assert (c); assert (streq (zconfig_name (c), "STREAM3")); assert (streq (zconfig_value (c), "HAM"));
c = zconfig_next (c); assert (!c);
assert (streq (zconfig_get (config, "server/verbose", NULL), "true"));
zconfig_destroy (&config);
// Test subtree removal { zconfig_t *root = zconfig_str_load ( "context\n" " iothreads = 1\n" " verbose = 1 # Ask for a trace\n" "main\n" " type = zqueue # ZMQ_DEVICE type\n" " frontend\n" " option\n" " hwm = 1000\n" " swap = 25000000 # 25MB\n" " bind = 'inproc://addr1'\n" " bind = 'ipc://addr2'\n" " backend\n" " bind = inproc://addr3\n" );
// no subtree zconfig_t *to_delete = zconfig_locate (root, "context/iothreads"); assert (to_delete);
zconfig_remove_subtree (to_delete);
zconfig_t *check = zconfig_locate (root, "context/iothreads"); assert (check); assert (streq (zconfig_value (check), "1"));
check = zconfig_locate (root, "context/verbose"); assert (check); assert (streq (zconfig_value (check), "1"));
// existing subtree to_delete = zconfig_locate (root, "main/frontend/option"); assert (to_delete);
zconfig_remove_subtree (to_delete);
check = zconfig_locate (root, "main/frontend/option/hwm"); assert (check == NULL); check = zconfig_locate (root, "main/frontend/option/swap"); assert (check == NULL); check = zconfig_locate (root, "main/frontend/option"); assert (check); assert (streq (zconfig_value (check), "")); check = zconfig_next (check); assert (check); assert (streq (zconfig_name (check), "bind")); assert (streq (zconfig_value (check), "inproc://addr1")); check = zconfig_next (check); assert (check); assert (streq (zconfig_name (check), "bind")); assert (streq (zconfig_value (check), "ipc://addr2")); assert (zconfig_next (check) == NULL);
to_delete = zconfig_locate (root, "main/frontend"); assert (to_delete);
zconfig_remove_subtree (to_delete);
check = zconfig_locate (root, "main/frontend/option/hwm"); assert (check == NULL); check = zconfig_locate (root, "main/frontend/option/swap"); assert (check == NULL); check = zconfig_locate (root, "main/frontend/option"); assert (check == NULL); check = zconfig_locate (root, "main/frontend/bind"); assert (check == NULL); check = zconfig_locate (root, "main/frontend"); assert (check); assert (streq (zconfig_value (check), "")); assert (zconfig_child (check) == NULL); check = zconfig_next (check); assert (check); assert (streq (zconfig_name (check), "backend")); assert (streq (zconfig_value (check), ""));
to_delete = zconfig_locate (root, "main"); assert (to_delete);
zconfig_remove_subtree (to_delete);
check = zconfig_locate (root, "main/type"); assert (check == NULL); check = zconfig_locate (root, "main/frontend"); assert (check == NULL); check = zconfig_locate (root, "main/backend"); assert (check == NULL); check = zconfig_locate (root, "main"); assert (check);
// root zconfig_remove_subtree (root);
assert (root); assert (zconfig_child (root) == NULL); check = zconfig_locate (root, "main"); assert (check == NULL); check = zconfig_locate (root, "context"); assert (check == NULL);
zconfig_destroy (&root); }
// Test node and subtree removal { zconfig_t *root = zconfig_str_load ( "A1 = abc\n" " x\n" " 1\n" " 2\n" " y = 1 # Ask for a trace\n" "A2\n" " B1 = zqueue # ZMQ_DEVICE type\n" " B2\n" " C1\n" " hwm = 1000\n" " swap = 25000000 # 25MB\n" " C2 = 50\n" " C3\n" " bind = addr3\n" " B3\n" " bind = inproc://addr4\n" " B4 = Ignac\n" " z = 5\n" "A3\n" "A4\n" );
zconfig_t *to_delete = zconfig_locate (root, "A2/B2/C3"); assert (to_delete);
zconfig_remove (&to_delete);
zconfig_t *check = zconfig_locate (root, "A2/B2/C2"); assert (check); assert (streq (zconfig_value (check), "50")); assert (zconfig_next (check) == NULL); assert (zconfig_locate (root, "A2/B2/C3/bind") == NULL); assert (zconfig_locate (root, "A2/B2/C3") == NULL);
to_delete = zconfig_locate (root, "A2/B2"); assert (to_delete);
zconfig_remove (&to_delete);
check = zconfig_locate (root, "A2"); assert (check); check = zconfig_child (check); assert (check); assert (streq (zconfig_name (check), "B1")); assert (streq (zconfig_value (check), "zqueue")); check = zconfig_next (check); assert (check); assert (streq (zconfig_name (check), "B3")); assert (streq (zconfig_value (check), "")); assert (zconfig_locate (root, "A2/B2/C1") == NULL); assert (zconfig_locate (root, "A2/B2/C2") == NULL); assert (zconfig_locate (root, "A2/B2") == NULL); assert (zconfig_locate (root, "A2/B4"));
to_delete = zconfig_locate (root, "A2/B1"); assert (to_delete);
zconfig_remove (&to_delete);
check = zconfig_locate (root, "A2"); assert (check); check = zconfig_child (check); assert (check); assert (streq (zconfig_name (check), "B3")); assert (streq (zconfig_value (check), "")); check = zconfig_next (check); assert (check); assert (streq (zconfig_name (check), "B4")); assert (streq (zconfig_value (check), "Ignac")); assert (zconfig_next (check) == NULL); assert (zconfig_locate (root, "A2/B1") == NULL); assert (zconfig_locate (root, "A2/B2") == NULL);
to_delete = zconfig_locate (root, "A2/B3"); assert (to_delete);
zconfig_remove (&to_delete);
check = zconfig_locate (root, "A2"); assert (check); check = zconfig_child (check); assert (check); assert (streq (zconfig_name (check), "B4")); assert (streq (zconfig_value (check), "Ignac")); assert (zconfig_next (check) == NULL);
to_delete = zconfig_locate (root, "A2"); assert (to_delete);
zconfig_remove (&to_delete);
check = zconfig_locate (root, "A1"); assert (check); check = zconfig_next (check); assert (check); assert (streq (zconfig_name (check), "A3")); assert (zconfig_locate (root, "A2/B4") == NULL); assert (zconfig_locate (root, "A2") == NULL);
to_delete = zconfig_locate (root, "A1"); assert (to_delete);
zconfig_remove (&to_delete);
check = zconfig_child (root); assert (check); assert (streq (zconfig_name (check), "A3")); assert (zconfig_locate (root, "A1/x/1") == NULL); assert (zconfig_locate (root, "A1/x") == NULL); assert (zconfig_locate (root, "A1/y") == NULL); assert (zconfig_locate (root, "A3")); assert (zconfig_locate (root, "A4"));
// called on root should be equivalent to zconfig_destroy (&root) zconfig_remove (&root); }
// Delete all test files dir = zdir_new (basedirpath, NULL); assert (dir); zdir_remove (dir, true); zdir_destroy (&dir);
zstr_free (&basedirpath); zstr_free (&filepath);
#if defined (__WINDOWS__) zsys_shutdown(); #endif

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

Main web site:
Report bugs to the email < zeromq-dev@lists.zeromq.org[1]>

Copyright (c) the 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.

1.
zeromq-dev@lists.zeromq.org
mailto:zeromq-dev@lists.zeromq.org
01/02/2019 CZMQ 4.1.1

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 ManDoc.