X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Fconf.h;h=50dbddc1712ea109b7c9fc24357e91a825d7b0e8;hb=bfca2c42bc0e749f8611339568be502f22ac5e9c;hp=dc1d14549d133a1d351b0be6d55c41e602a68e48;hpb=b83e720d8c576a0052de02f89e97b89ba52060da;p=libucw.git

diff --git a/ucw/conf.h b/ucw/conf.h
index dc1d1454..50dbddc1 100644
--- a/ucw/conf.h
+++ b/ucw/conf.h
@@ -132,7 +132,7 @@ struct cf_section {			/** A section. **/
  *     uns value;
  *   };
  *
- *   struct clist nodes;
+ *   static struct clist nodes;
  *
  *   static struct cf_section node = {
  *     CF_TYPE(struct list_node),
@@ -148,7 +148,7 @@ struct cf_section {			/** A section. **/
  *     CF_END
  *   };
  *
- * You could use <<def_CF_STATIC,`def_CF_STATIC`>> or <<def_CF_DYNAMIC,`def_CF_DYNAMIC`>>
+ * You could use <<def_CF_STATIC,`CF_STATIC`>> or <<def_CF_DYNAMIC,`CF_DYNAMIC`>>
  * macros to create arrays.
  */
 #define CF_TYPE(s)	.size = sizeof(s)
@@ -215,17 +215,17 @@ struct cf_section {			/** A section. **/
  * * @c -- count.
  **/
 #define CF_INT(n,p)		CF_STATIC(n,p,INT,int,1)		/** Single `int` value. **/
-#define CF_INT_ARY(n,p,c)	CF_STATIC(n,p,INT,int,c)		/** Static array of `int` s. **/
-#define CF_INT_DYN(n,p,c)	CF_DYNAMIC(n,p,INT,int,c)		/** Dynamic array of `int` s. **/
+#define CF_INT_ARY(n,p,c)	CF_STATIC(n,p,INT,int,c)		/** Static array of integers. **/
+#define CF_INT_DYN(n,p,c)	CF_DYNAMIC(n,p,INT,int,c)		/** Dynamic array of integers. **/
 #define CF_UNS(n,p)		CF_STATIC(n,p,INT,uns,1)		/** Single `uns` (`unsigned`) value. **/
-#define CF_UNS_ARY(n,p,c)	CF_STATIC(n,p,INT,uns,c)		/** Static array of `uns` es. **/
-#define CF_UNS_DYN(n,p,c)	CF_DYNAMIC(n,p,INT,uns,c)		/** Dynamic array of `uns` es. **/
+#define CF_UNS_ARY(n,p,c)	CF_STATIC(n,p,INT,uns,c)		/** Static array of unsigned integers. **/
+#define CF_UNS_DYN(n,p,c)	CF_DYNAMIC(n,p,INT,uns,c)		/** Dynamic array of unsigned integers. **/
 #define CF_U64(n,p)		CF_STATIC(n,p,U64,u64,1)		/** Single unsigned 64bit integer (`u64`). **/
-#define CF_U64_ARY(n,p,c)	CF_STATIC(n,p,U64,u64,c)		/** Static array of `u64` s. **/
-#define CF_U64_DYN(n,p,c)	CF_DYNAMIC(n,p,U64,u64,c)		/** Dynamic array of `u64` s. **/
+#define CF_U64_ARY(n,p,c)	CF_STATIC(n,p,U64,u64,c)		/** Static array of u64s. **/
+#define CF_U64_DYN(n,p,c)	CF_DYNAMIC(n,p,U64,u64,c)		/** Dynamic array of u64s. **/
 #define CF_DOUBLE(n,p)		CF_STATIC(n,p,DOUBLE,double,1)		/** Single instance of `double`. **/
-#define CF_DOUBLE_ARY(n,p,c)	CF_STATIC(n,p,DOUBLE,double,c)		/** Static array of `double` s. **/
-#define CF_DOUBLE_DYN(n,p,c)	CF_DYNAMIC(n,p,DOUBLE,double,c)		/** Dynamic array of `double` s. **/
+#define CF_DOUBLE_ARY(n,p,c)	CF_STATIC(n,p,DOUBLE,double,c)		/** Static array of doubles. **/
+#define CF_DOUBLE_DYN(n,p,c)	CF_DYNAMIC(n,p,DOUBLE,double,c)		/** Dynamic array of doubles. **/
 #define CF_IP(n,p)		CF_STATIC(n,p,IP,u32,1)			/** Single IPv4 address. **/
 #define CF_IP_ARY(n,p,c)	CF_STATIC(n,p,IP,u32,c)			/** Static array of IP addresses. **/.
 #define CF_IP_DYN(n,p,c)	CF_DYNAMIC(n,p,IP,u32,c)		/** Dynamic array of IP addresses. **/
@@ -277,17 +277,17 @@ struct cf_section {			/** A section. **/
  **/
 #define CF_LOOKUP_DYN(n,p,t,c)	{ .cls = CC_DYNAMIC, .type = CT_LOOKUP, .name = n, .number = c, .ptr = CHECK_PTR_TYPE(p,int**), .u.lookup = t }
 /**
- * A user defined type.
+ * A user-defined type.
  * See <<custom_parser,creating custom parsers>> section if you want to know more.
  **/
 #define CF_USER(n,p,t)		{ .cls = CC_STATIC, .type = CT_USER, .name = n, .number = 1, .ptr = p, .u.utype = t }
 /**
- * Static array of user defined types (all of the same type).
+ * Static array of user-defined types (all of the same type).
  * See <<custom_parser,creating custom parsers>> section.
  **/
 #define CF_USER_ARY(n,p,t,c)	{ .cls = CC_STATIC, .type = CT_USER, .name = n, .number = c, .ptr = p, .u.utype = t }
 /**
- * Dynamic array of user defined types.
+ * Dynamic array of user-defined types.
  * See <<custom_parser,creating custom parsers>> section.
  **/
 #define CF_USER_DYN(n,p,t,c)	{ .cls = CC_DYNAMIC, .type = CT_USER, .name = n, .number = c, .ptr = p, .u.utype = t }
@@ -310,8 +310,14 @@ struct cf_section {			/** A section. **/
  * You should use these routines when implementing custom parsers.
  ***/
 struct mempool;
-extern struct mempool *cf_pool;	/** A <<mempool:type_mempool,memory pool>> for configuration parser needs. **/
-void *cf_malloc(uns size);	/** Returns @size bytes of memory. **/
+/**
+ * A <<mempool:type_mempool,memory pool>> for configuration parser needs.
+ * Memory allocated from here is valid as long as the current config is loaded
+ * (if you allocate some memory and rollback the transaction or you load some
+ * other configuration, it gets lost).
+ **/
+extern struct mempool *cf_pool;
+void *cf_malloc(uns size);	/** Returns @size bytes of memory. Allocates from <<var_cf_pool,`cf_pool`>>. **/
 void *cf_malloc_zero(uns size);	/** Like @cf_malloc(), but zeroes the memory. **/
 char *cf_strdup(const char *s);	/** Copy a string into @cf_malloc()ed memory. **/
 char *cf_printf(const char *fmt, ...) FORMAT_CHECK(printf,1,2); /** printf() into @cf_malloc()ed memory. **/
@@ -321,17 +327,53 @@ char *cf_printf(const char *fmt, ...) FORMAT_CHECK(printf,1,2); /** printf() int
  * Undo journal
  * ~~~~~~~~~~~~
  *
- * For error recovery
+ * For error recovery when <<reload,reloading configuration>>.
  ***/
-extern uns cf_need_journal;
+extern uns cf_need_journal;	/** Is the journal needed? If you do not reload configuration, you set this to 0 and gain a little more performance and free memory. **/
+/**
+ * When a block of memory is about to be changed, put the old value
+ * into journal with this function. You need to call it from a <<hooks,commit hook>>
+ * if you change anything. It is used internally by low-level parsers.
+ * <<custom_parser,Custom parsers>> do not need to call it, it is called
+ * before them.
+ **/
 void cf_journal_block(void *ptr, uns len);
-#define CF_JOURNAL_VAR(var) cf_journal_block(&(var), sizeof(var))
+#define CF_JOURNAL_VAR(var) cf_journal_block(&(var), sizeof(var))	// Store single value into journal.
 
-/* Declaration: conf-section.c */
+/***
+ * [[declare]]
+ * Section declaration
+ * ~~~~~~~~~~~~~~~~~~~
+ **/
+
+/**
+ * Plug another top-level section into the configuration system.
+ * @name is the name in the configuration file,
+ * @sec is pointer to the section description.
+ * If @allow_unknown is set to 0 and a variable not described in @sec
+ * is found in the configuration file, it produces an error.
+ * If you set it to 1, all such variables are ignored.
+ **/
 void cf_declare_section(const char *name, struct cf_section *sec, uns allow_unknown);
+/**
+ * If you have a section in a structure and you want to initialize it
+ * (eg. if you want a copy of default values outside the configuration),
+ * you can use this. It initializes it recursively.
+ *
+ * This is used mostly internally. You probably do not need it.
+ **/
 void cf_init_section(const char *name, struct cf_section *sec, void *ptr, uns do_bzero);
 
-/*** === Parsers for basic types [[bparser]] ***/
+/***
+ * [[bparser]]
+ * Parsers for basic types
+ * ~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * Each of them gets a string to parse and pointer to store the value.
+ * It returns either NULL or error message.
+ *
+ * The parsers support units. See <<config:units,their list>>.
+ ***/
 char *cf_parse_int(const char *str, int *ptr);		/** Parser for integers. **/
 char *cf_parse_u64(const char *str, u64 *ptr);		/** Parser for 64 unsigned integers. **/
 char *cf_parse_double(const char *str, double *ptr);	/** Parser for doubles. **/