1ZCONFIG(3) CZMQ Manual ZCONFIG(3)
2
6 zconfig - work with config files written in rfc.zeromq.org/spec:4/ZPL.
7
9 // This is a stable class, and may not change except for emergencies. It
10 // is provided in stable builds.
11 //
12 typedef int (zconfig_fct) (
13 zconfig_t *self, void *arg, int level);
14 // Create new config item
16 CZMQ_EXPORT zconfig_t *
17 zconfig_new (const char *name, zconfig_t *parent);
18 // Load a config tree from a specified ZPL text file; returns a zconfig_t
20 // reference for the root, if the file exists and is readable. Returns NULL
21 // if the file does not exist.
22 CZMQ_EXPORT zconfig_t *
23 zconfig_load (const char *filename);
24 // Equivalent to zconfig_load, taking a format string instead of a fixed
26 // filename.
27 CZMQ_EXPORT zconfig_t *
28 zconfig_loadf (const char *format, ...) CHECK_PRINTF (1);
29 // Destroy a config item and all its children
31 CZMQ_EXPORT void
32 zconfig_destroy (zconfig_t **self_p);
33 // Return name of config item
35 CZMQ_EXPORT char *
36 zconfig_name (zconfig_t *self);
37 // Return value of config item
39 CZMQ_EXPORT char *
40 zconfig_value (zconfig_t *self);
41 // Insert or update configuration key with value
43 CZMQ_EXPORT void
44 zconfig_put (zconfig_t *self, const char *path, const char *value);
45 // Equivalent to zconfig_put, accepting a format specifier and variable
47 // argument list, instead of a single string value.
48 CZMQ_EXPORT void
49 zconfig_putf (zconfig_t *self, const char *path, const char *format, ...) CHECK_PRINTF (3);
50 // Get value for config item into a string value; leading slash is optional
52 // and ignored.
53 CZMQ_EXPORT char *
54 zconfig_get (zconfig_t *self, const char *path, const char *default_value);
55 // Set config item name, name may be NULL
57 CZMQ_EXPORT void
58 zconfig_set_name (zconfig_t *self, const char *name);
59 // Set new value for config item. The new value may be a string, a printf
61 // format, or NULL. Note that if string may possibly contain '%', or if it
62 // comes from an insecure source, you must use '%s' as the format, followed
63 // by the string.
64 CZMQ_EXPORT void
65 zconfig_set_value (zconfig_t *self, const char *format, ...) CHECK_PRINTF (2);
66 // Find our first child, if any
68 CZMQ_EXPORT zconfig_t *
69 zconfig_child (zconfig_t *self);
70 // Find our first sibling, if any
72 CZMQ_EXPORT zconfig_t *
73 zconfig_next (zconfig_t *self);
74 // Find a config item along a path; leading slash is optional and ignored.
76 CZMQ_EXPORT zconfig_t *
77 zconfig_locate (zconfig_t *self, const char *path);
78 // Locate the last config item at a specified depth
80 CZMQ_EXPORT zconfig_t *
81 zconfig_at_depth (zconfig_t *self, int level);
82 // Execute a callback for each config item in the tree; returns zero if
84 // successful, else -1.
85 CZMQ_EXPORT int
86 zconfig_execute (zconfig_t *self, zconfig_fct handler, void *arg);
87 // Add comment to config item before saving to disk. You can add as many
89 // comment lines as you like. If you use a null format, all comments are
90 // deleted.
91 CZMQ_EXPORT void
92 zconfig_set_comment (zconfig_t *self, const char *format, ...) CHECK_PRINTF (2);
93 // Return comments of config item, as zlist.
95 CZMQ_EXPORT zlist_t *
96 zconfig_comments (zconfig_t *self);
97 // Save a config tree to a specified ZPL text file, where a filename
99 // "-" means dump to standard output.
100 CZMQ_EXPORT int
101 zconfig_save (zconfig_t *self, const char *filename);
102 // Equivalent to zconfig_save, taking a format string instead of a fixed
104 // filename.
105 CZMQ_EXPORT int
106 zconfig_savef (zconfig_t *self, const char *format, ...) CHECK_PRINTF (2);
107 // Report filename used during zconfig_load, or NULL if none
109 CZMQ_EXPORT const char *
110 zconfig_filename (zconfig_t *self);
111 // Reload config tree from same file that it was previously loaded from.
113 // Returns 0 if OK, -1 if there was an error (and then does not change
114 // existing data).
115 CZMQ_EXPORT int
116 zconfig_reload (zconfig_t **self_p);
117 // Load a config tree from a memory chunk
119 CZMQ_EXPORT zconfig_t *
120 zconfig_chunk_load (zchunk_t *chunk);
121 // Save a config tree to a new memory chunk
123 CZMQ_EXPORT zchunk_t *
124 zconfig_chunk_save (zconfig_t *self);
125 // Load a config tree from a null-terminated string
127 // Caller owns return value and must destroy it when done.
128 CZMQ_EXPORT zconfig_t *
129 zconfig_str_load (const char *string);
130 // Save a config tree to a new null terminated string
132 // Caller owns return value and must destroy it when done.
133 CZMQ_EXPORT char *
134 zconfig_str_save (zconfig_t *self);
135 // Return true if a configuration tree was loaded from a file and that
137 // file has changed in since the tree was loaded.
138 CZMQ_EXPORT bool
139 zconfig_has_changed (zconfig_t *self);
140 // Print the config file to open stream
142 CZMQ_EXPORT void
143 zconfig_fprint (zconfig_t *self, FILE *file);
144 // Print properties of object
146 CZMQ_EXPORT void
147 zconfig_print (zconfig_t *self);
148 // Self test of this class
150 CZMQ_EXPORT void
151 zconfig_test (bool verbose);
152 Please add '@interface' section in './../src/zconfig.c'.
154
156 Lets applications load, work with, and save configuration files. This
157 implements rfc.zeromq.org/spec:4/ZPL, which is a simple structured text
158 format for configuration files.
159 Here is an example ZPL stream and corresponding config structure:
161 context
163 iothreads = 1
164 verbose = 1 # Ask for a trace
165 main
166 type = zqueue # ZMQ_DEVICE type
167 frontend
168 option
169 hwm = 1000
170 swap = 25000000 # 25MB
171 bind = 'inproc://addr1'
172 bind = 'ipc://addr2'
173 backend
174 bind = inproc://addr3
175 root Down = child
177 | Across = next
178 v
179 context-->main
180 | |
181 | v
182 | type=queue-->frontend-->backend
183 | | |
184 | | v
185 | | bind=inproc://addr3
186 | v
187 | option-->bind=inproc://addr1-->bind=ipc://addr2
188 | |
189 | v
190 | hwm=1000-->swap=25000000
191 v
192 iothreads=1-->verbose=false
193
195 From zconfig_test method.
196 // Create temporary directory for test files
198 # define TESTDIR ".test_zconfig"
199 zsys_dir_create (TESTDIR);
200 zconfig_t *root = zconfig_new ("root", NULL);
202 assert (root);
203 zconfig_t *section, *item;
204 section = zconfig_new ("headers", root);
206 assert (section);
207 item = zconfig_new ("email", section);
208 assert (item);
209 zconfig_set_value (item, "some@random.com");
210 item = zconfig_new ("name", section);
211 assert (item);
212 zconfig_set_value (item, "Justin Kayce");
213 zconfig_putf (root, "/curve/secret-key", "%s", "Top Secret");
214 zconfig_set_comment (root, " CURVE certificate");
215 zconfig_set_comment (root, " -----------------");
216 assert (zconfig_comments (root));
217 zconfig_save (root, TESTDIR "/test.cfg");
218 zconfig_destroy (&root);
219 root = zconfig_load (TESTDIR "/test.cfg");
220 if (verbose)
221 zconfig_save (root, "-");
222 assert (streq (zconfig_filename (root), TESTDIR "/test.cfg"));
223 char *email = zconfig_get (root, "/headers/email", NULL);
225 assert (email);
226 assert (streq (email, "some@random.com"));
227 char *passwd = zconfig_get (root, "/curve/secret-key", NULL);
228 assert (passwd);
229 assert (streq (passwd, "Top Secret"));
230 zconfig_savef (root, "%s/%s", TESTDIR, "test.cfg");
232 assert (!zconfig_has_changed (root));
233 int rc = zconfig_reload (&root);
234 assert (rc == 0);
235 assert (!zconfig_has_changed (root));
236 zconfig_destroy (&root);
237 // Test chunk load/save
239 root = zconfig_new ("root", NULL);
240 assert (root);
241 section = zconfig_new ("section", root);
242 assert (section);
243 item = zconfig_new ("value", section);
244 assert (item);
245 zconfig_set_value (item, "somevalue");
246 zconfig_t *search = zconfig_locate (root, "section/value");
247 assert (search == item);
248 zchunk_t *chunk = zconfig_chunk_save (root);
249 assert (strlen ((char *) zchunk_data (chunk)) == 32);
250 char *string = zconfig_str_save (root);
251 assert (string);
252 assert (streq (string, (char *) zchunk_data (chunk)));
253 free (string);
254 assert (chunk);
255 zconfig_destroy (&root);
256 root = zconfig_chunk_load (chunk);
258 assert (root);
259 char *value = zconfig_get (root, "/section/value", NULL);
260 assert (value);
261 assert (streq (value, "somevalue"));
262 // Test config can't be saved to a file in a path that doesn't
264 // exist or isn't writable
265 rc = zconfig_savef (root, "%s/path/that/doesnt/exist/%s", TESTDIR, "test.cfg");
266 assert (rc == -1);
267 zconfig_destroy (&root);
269 zchunk_destroy (&chunk);
270 // Delete all test files
272 zdir_t *dir = zdir_new (TESTDIR, NULL);
273 assert (dir);
274 zdir_remove (dir, true);
275 zdir_destroy (&dir);
276
279 The czmq manual was written by the authors in the AUTHORS file.
280
282 Main web site:
283 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
285
287 Copyright (c) the Contributors as noted in the AUTHORS file. This file
288 is part of CZMQ, the high-level C binding for 0MQ:
289 http://czmq.zeromq.org. This Source Code Form is subject to the terms
290 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
291 distributed with this file, You can obtain one at
292 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
293 distribution.
294
296 1. zeromq-dev@lists.zeromq.org
297 mailto:zeromq-dev@lists.zeromq.org
298CZMQ 4.0.2 12/31/2016 ZCONFIG(3)