ctdb/common/conf.h

   1 /*
   2    Configuration file handling on top of tini
   3
   4    Copyright (C) Amitay Isaacs  2017
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 #ifndef __CTDB_CONF_H__
  21 #define __CTDB_CONF_H__
  22
  23 #include <stdio.h>
  24 #include <stdbool.h>
  25 #include <talloc.h>
  26
  27 /**
  28  * @file conf.h
  29  *
  30  * @brief Configuration file handling with sections and key-value pairs
  31  *
  32  * CTDB settings can be written in a configuration file ctdb.conf (similar to
  33  * samba's smb.conf).  Various daemons and tools will consult the configuration
  34  * file for runtime settings.
  35  *
  36  * The configuration will be organized in sections depending on various
  37  * components. Each section will have various configuration options in the form
  38  * of key-value pairs.
  39  *
  40  * [section1]
  41  *      key1 = value1
  42  *      ...
  43  *
  44  * [section2]
  45  *      key2 = value2
  46  *      ...
  47  *
  48  * ...
  49  *
  50  */
  51
  52 /**
  53  * @brief Abstract data structure holding the configuration options
  54  */
  55 struct conf_context;
  56
  57 /**
  58  * @brief configuration option update mode
  59  *
  60  * When a value of configuration option is changed, update mode is set
  61  * appropriately.
  62  *
  63  * CONF_MODE_API - value modified using set functions
  64  * CONF_MODE_LOAD - value modified via conf_load
  65  * CONF_MODE_RELOAD - value modified via conf_reload
  66  */
  67 enum conf_update_mode {
  68         CONF_MODE_API,
  69         CONF_MODE_LOAD,
  70         CONF_MODE_RELOAD,
  71 };
  72
  73 /**
  74  * @brief configuration option type
  75  */
  76 enum conf_type {
  77         CONF_STRING,
  78         CONF_INTEGER,
  79         CONF_BOOLEAN,
  80 };
  81
  82 /**
  83  * @brief Configuration section validation function
  84  *
  85  * Check if all the configuration options are consistent with each-other
  86  */
  87 typedef bool (*conf_validate_section_fn)(struct conf_context *conf,
  88                                          const char *section,
  89                                          enum conf_update_mode mode);
  90
  91 /**
  92  * @brief Configuration option validation function for string
  93  *
  94  * Check if a configuration option value is valid
  95  */
  96 typedef bool (*conf_validate_string_option_fn)(const char *key,
  97                                                const char *old_value,
  98                                                const char *new_value,
  99                                                enum conf_update_mode mode);
 100
 101 /**
 102  * @brief Configuration option validation function for integer
 103  *
 104  * Check if a configuration option value is valid
 105  */
 106 typedef bool (*conf_validate_integer_option_fn)(const char *key,
 107                                                 int old_value,
 108                                                 int new_value,
 109                                                 enum conf_update_mode mode);
 110
 111 /**
 112  * @brief Configuration option validation function for boolean
 113  *
 114  * Check if a configuration option value is valid
 115  */
 116 typedef bool (*conf_validate_boolean_option_fn)(const char *key,
 117                                                 bool old_value,
 118                                                 bool new_value,
 119                                                 enum conf_update_mode mode);
 120
 121 /**
 122  * @brief Initialize configuration option database
 123  *
 124  * This return a new configuration options context.  Freeing this context will
 125  * free up all the memory associated with the configuration options.
 126  *
 127  * @param[in] mem_ctx  Talloc memory context
 128  * @param[in] result  The new configuration options context
 129  * @return 0 on success, errno on failure
 130  */
 131 int conf_init(TALLOC_CTX *mem_ctx, struct conf_context **result);
 132
 133 /**
 134  * @brief Define a section for organizing configuration options
 135  *
 136  * This functions creates a section to organize configuration option.  The
 137  * section names are case-insensitive and are always stored in lower case.
 138  *
 139  * @param[in] conf  The configuration options context
 140  * @param[in] section  The name of the section
 141  * @param[in] validate  The validation function for configuration options
 142  */
 143 void conf_define_section(struct conf_context *conf,
 144                          const char *section,
 145                          conf_validate_section_fn validate);
 146
 147 /**
 148  * @brief Define a configuration option which has a string value
 149  *
 150  * This functions adds a new configuration option organized under a given
 151  * section.  Configuration options are case-insensitive and are always stored
 152  * in lower case.
 153  *
 154  * @param[in] conf  The configuration options context
 155  * @param[in] section  The name of the section
 156  * @param[in] key  The name of the configuration option
 157  * @param[in] default_value  The default value for the configuration option
 158  * @param[in] validate  The validation function for the configuration option
 159  */
 160 void conf_define_string(struct conf_context *conf,
 161                         const char *section,
 162                         const char *key,
 163                         const char *default_value,
 164                         conf_validate_string_option_fn validate);
 165
 166 /**
 167  * @brief Define a configuration option which has an integer value
 168  *
 169  * This functions adds a new configuration option organized under a given
 170  * section.  Configuration options are case-insensitive and are always stored
 171  * in lower case.
 172  *
 173  * @param[in] conf  The configuration options context
 174  * @param[in] section  The name of the section
 175  * @param[in] key  The name of the configuration option
 176  * @param[in] default_value  The default value for the configuration option
 177  * @param[in] validate  The validation function for the configuration option
 178  */
 179 void conf_define_integer(struct conf_context *conf,
 180                          const char *section,
 181                          const char *key,
 182                          const int default_value,
 183                          conf_validate_integer_option_fn validate);
 184
 185 /**
 186  * @brief Define a configuration option which has an boolean value
 187  *
 188  * This functions adds a new configuration option organized under a given
 189  * section.  Configuration options are case-insensitive and are always stored
 190  * in lower case.
 191  *
 192  * @param[in] conf  The configuration options context
 193  * @param[in] section  The name of the section
 194  * @param[in] key  The name of the configuration option
 195  * @param[in] default_value  The default value for the configuration option
 196  * @param[in] validate  The validation function for the configuration option
 197  */
 198 void conf_define_boolean(struct conf_context *conf,
 199                          const char *section,
 200                          const char *key,
 201                          const bool default_value,
 202                          conf_validate_boolean_option_fn validate);
 203
 204 /**
 205  * @brief Assign user-accessible pointer for string option
 206  *
 207  * This pointer can be used for accessing the value of configuration option
 208  * directly without requiring a function call.
 209  *
 210  * @param[in] conf  The configuration options context
 211  * @param[in] section  The name of the section
 212  * @param[in] key  The name of the configuration option
 213  * @param[in] ptr  User-accessible pointer to the value
 214  */
 215 void conf_assign_string_pointer(struct conf_context *conf,
 216                                 const char *section,
 217                                 const char *key,
 218                                 const char **ptr);
 219
 220 /**
 221  * @brief Assign user-accessible pointer for integer option
 222  *
 223  * This pointer can be used for accessing the value of configuration option
 224  * directly without requiring a function call.
 225  *
 226  * @param[in] conf  The configuration options context
 227  * @param[in] section  The name of the section
 228  * @param[in] key  The name of the configuration option
 229  * @param[in] ptr  User-accessible pointer to the value
 230  */
 231 void conf_assign_integer_pointer(struct conf_context *conf,
 232                                  const char *section,
 233                                  const char *key,
 234                                  int *ptr);
 235
 236 /**
 237  * @brief Assign user-accessible pointer for boolean option
 238  *
 239  * This pointer can be used for accessing the value of configuration option
 240  * directly without requiring a function call.
 241  *
 242  * @param[in] conf  The configuration options context
 243  * @param[in] section  The name of the section
 244  * @param[in] key  The name of the configuration option
 245  * @param[in] ptr  User-accessible pointer to the value
 246  * @return true on success, false on failure
 247  */
 248 void conf_assign_boolean_pointer(struct conf_context *conf,
 249                                  const char *section,
 250                                  const char *key,
 251                                  bool *ptr);
 252
 253 /**
 254  * @brief Query a configuration option
 255  *
 256  * This function checks if a configuration option is defined or not.
 257  *
 258  * @param[in] conf  The configuration options context
 259  * @param[in] section  The name of the section
 260  * @param[in] key  The name of the configuration option
 261  * @param[out] type  The type of the configuration option
 262  * @return true on success, false if section/option is not defined
 263  */
 264 bool conf_query(struct conf_context *conf,
 265                 const char *section,
 266                 const char *key,
 267                 enum conf_type *type);
 268
 269 /**
 270  * @brief Check if the defined configuration options are valid
 271  *
 272  * This function must be called after creating configuration options
 273  * to confirm that all the option definitions are valid.
 274  *
 275  * @param[in] conf  The configuration options context
 276  * @return true on success, false on failure
 277  */
 278 bool conf_valid(struct conf_context *conf);
 279
 280 /**
 281  * @brief Set the default values for all configuration options
 282  *
 283  * This function resets all the configuration options to their default values.
 284  *
 285  * @param[in] conf  The connfiguration options context
 286  */
 287 void conf_set_defaults(struct conf_context *conf);
 288
 289 /**
 290  * @brief Load the values for configuration option values from a file
 291  *
 292  * This function will update the values of the configuration options from those
 293  * specified in a file.  This function will fail in case it encounters an
 294  * undefined option.  Any sections which are not defined, will be ignored.
 295  *
 296  * This function will call validation function (if specified) before updating
 297  * the value of a configuration option.  After updating all the values for a
 298  * section, the validation for section (if specified) will be called.  If any
 299  * of the validation functions return error, then all the configuration
 300  * options will be reset to their previous values.
 301  *
 302  * @param[in] conf  The configuration options context
 303  * @param[in] filename  The configuration file
 304  * @param[in] skip_unknown  Whether unknown config options should be ignored
 305  * @return 0 on success, errno on failure
 306  */
 307 int conf_load(struct conf_context *conf,
 308               const char *filename,
 309               bool ignore_unknown);
 310
 311 /**
 312  * @brief Reload the values for configuration options
 313  *
 314  * This function will re-load the values of the configuration options.  This
 315  * function can be called only after successful call to conf_load().
 316  *
 317  * @see conf_load
 318  *
 319  * @param[in] conf  The configuration options context
 320  * @return 0 on success, errno on failure.
 321  */
 322 int conf_reload(struct conf_context *conf);
 323
 324 /**
 325  * @brief Set the string value of a configuration option
 326  *
 327  * This function can be used to update the value of a configuration option.
 328  * This will call the validation function for that option (if defined) and
 329  * the section validation function (if defined).
 330  *
 331  * If a user-defined storage pointer is provided, then the value of a
 332  * configuration option should not be changed via that pointer.
 333  *
 334  * @param[in] conf  The configuration options context
 335  * @param[in] section  The name of a section
 336  * @param[in] key  The name of a configuration option
 337  * @param[in] str_val  The string value
 338  * @return 0 on success, errno in case of failure
 339  */
 340 int conf_set_string(struct conf_context *conf,
 341                     const char *section,
 342                     const char *key,
 343                     const char *str_val);
 344
 345 /**
 346  * @brief Set the integer value of a configuration option
 347  *
 348  * This function can be used to update the value of a configuration option.
 349  * This will call the validation function for that option (if defined) and
 350  * the section validation function (if defined).
 351  *
 352  * If a user-defined storage pointer is provided, then the value of a
 353  * configuration option should not be changed via that pointer.
 354  *
 355  * @param[in] conf  The configuration options context
 356  * @param[in] section  The name of a section
 357  * @param[in] key  The name of a configuration option
 358  * @param[in] int_val  The integer value
 359  * @return 0 on success, errno in case of failure
 360  */
 361 int conf_set_integer(struct conf_context *conf,
 362                      const char *section,
 363                      const char *key,
 364                      int int_val);
 365
 366 /**
 367  * @brief Set the boolean value of a configuration option
 368  *
 369  * This function can be used to update the value of a configuration option.
 370  * This will call the validation function for that option (if defined) and
 371  * the section validation function (if defined).
 372  *
 373  * If a user-defined storage pointer is provided, then the value of a
 374  * configuration option should not be changed via that pointer.
 375  *
 376  * @param[in] conf  The configuration options context
 377  * @param[in] section  The name of a section
 378  * @param[in] key  The name of a configuration option
 379  * @param[in] bool_val  The boolean value
 380  * @return 0 on success, errno in case of failure
 381  */
 382 int conf_set_boolean(struct conf_context *conf,
 383                      const char *section,
 384                      const char *key,
 385                      bool bool_val);
 386
 387 /**
 388  * @brief Get the string value of a configuration option
 389  *
 390  * This function can be used to fetch the current value of a configuration
 391  * option.
 392  *
 393  * If a user-defined storage pointer is provided, then the value of a
 394  * configuration option can be accessed directly via that pointer.
 395  *
 396  * @param[in] conf  The configuration options context
 397  * @param[in] section  The name of a section
 398  * @param[in] key  The name of a configuration option
 399  * @param[out] str_val  The string value of the configuration option
 400  * @param[out] is_default  True if the value is default value
 401  * @return 0 on success, errno in case of failure
 402  */
 403 int conf_get_string(struct conf_context *conf,
 404                     const char *section,
 405                     const char *key,
 406                     const char **str_val,
 407                     bool *is_default);
 408
 409 /**
 410  * @brief Get the integer value of a configuration option
 411  *
 412  * This function can be used to fetch the current value of a configuration
 413  * option.
 414  *
 415  * If a user-defined storage pointer is provided, then the value of a
 416  * configuration option can be accessed directly via that pointer.
 417  *
 418  * @param[in] conf  The configuration options context
 419  * @param[in] section  The name of a section
 420  * @param[in] key  The name of a configuration option
 421  * @param[out] int_val  The integer value of the configuration option
 422  * @param[out] is_default  True if the value is default value
 423  * @return 0 on success, errno in case of failure
 424  */
 425 int conf_get_integer(struct conf_context *conf,
 426                      const char *section,
 427                      const char *key,
 428                      int *int_val,
 429                      bool *is_default);
 430
 431 /**
 432  * @brief Get the boolean value of a configuration option
 433  *
 434  * This function can be used to fetch the current value of a configuration
 435  * option.
 436  *
 437  * If a user-defined storage pointer is provided, then the value of a
 438  * configuration option can be accessed directly via that pointer.
 439  *
 440  * @param[in] conf  The configuration options context
 441  * @param[in] section  The name of a section
 442  * @param[in] key  The name of a configuration option
 443  * @param[out] bool_val  The boolean value of the configuration option
 444  * @param[out] is_default  True if the value is default value
 445  * @return 0 on success, errno in case of failure
 446  */
 447 int conf_get_boolean(struct conf_context *conf,
 448                      const char *section,
 449                      const char *key,
 450                      bool *bool_val,
 451                      bool *is_default);
 452
 453 /**
 454  * @brief Dump the configuration in a file
 455  *
 456  * All the configuration options are dumped with their current values.
 457  * If an option has a default value, then it is commented.
 458  *
 459  * Here is a sample output:
 460  *
 461  * [section1]
 462  *      key1 = value1
 463  *      key2 = value2
 464  *      # key3 = default_value3
 465  * [section2]
 466  *      key4 = value4
 467  *
 468  * @param[in] conf  The configuration options context
 469  * @param[in] fp  File pointer
 470  */
 471 void conf_dump(struct conf_context *conf, FILE *fp);
 472
 473 #endif /* __CTDB_CONF_H__ */