Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ZCONFIG(3)			  CZMQ Manual			    ZCONFIG(3)

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

SYNOPSIS
       //  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'.

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.

	   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

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

RESOURCES
       Main web	site:

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

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

NOTES
	1. zeromq-dev@lists.zeromq.org
	   mailto:zeromq-dev@lists.zeromq.org

CZMQ 4.1.1			  08/10/2020			    ZCONFIG(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | AUTHORS | RESOURCES | COPYRIGHT | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zconfig&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help