'\" t .\" Title: zconfig .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.76.1 .\" Date: 12/31/2016 .\" Manual: CZMQ Manual .\" Source: CZMQ 4.0.2 .\" Language: English .\" .TH "ZCONFIG" "3" "12/31/2016" "CZMQ 4\&.0\&.2" "CZMQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" zconfig \- work with config files written in rfc\&.zeromq\&.org/spec:4/ZPL\&. .SH "SYNOPSIS" .sp .nf // This is a stable class, and may not change except for emergencies\&. It // is provided in stable builds\&. // 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 \*(Aq%\*(Aq, or if it // comes from an insecure source, you must use \*(Aq%s\*(Aq 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); Please add \*(Aq@interface\*(Aq section in \*(Aq\&./\&.\&./src/zconfig\&.c\*(Aq\&. .fi .SH "DESCRIPTION" .sp 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\&. .sp Here is an example ZPL stream and corresponding config structure: .sp .if n \{\ .RS 4 .\} .nf context iothreads = 1 verbose = 1 # Ask for a trace main type = zqueue # ZMQ_DEVICE type frontend option hwm = 1000 swap = 25000000 # 25MB bind = \*(Aqinproc://addr1\*(Aq bind = \*(Aqipc://addr2\*(Aq backend bind = inproc://addr3 .fi .if n \{\ .RE .\} .sp .if n \{\ .RS 4 .\} .nf 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 .fi .if n \{\ .RE .\} .SH "EXAMPLE" .PP \fBFrom zconfig_test method\fR. .sp .if n \{\ .RS 4 .\} .nf // 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@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@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\*(Aqt be saved to a file in a path that doesn\*(Aqt // exist or isn\*(Aqt 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); .fi .if n \{\ .RE .\} .sp .SH "AUTHORS" .sp The czmq manual was written by the authors in the AUTHORS file\&. .SH "RESOURCES" .sp Main web site: \m[blue]\fB\%\fR\m[] .sp Report bugs to the email <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[1]\d\s+2> .SH "COPYRIGHT" .sp 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\&. .SH "NOTES" .IP " 1." 4 zeromq-dev@lists.zeromq.org .RS 4 \%mailto:zeromq-dev@lists.zeromq.org .RE