You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
343 lines
11 KiB
343 lines
11 KiB
5 years ago
|
'\" t
|
||
|
|
.\" Title: zconfig
|
||
|
|
.\" Author: [see the "AUTHORS" section]
|
||
|
|
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
|
||
|
|
.\" 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
|