src/common/config/session-config.h

   1 /*
   2  * Copyright (C) 2013 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * This program is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU General Public License, version 2 only, as
   6  * published by the Free Software Foundation.
   7  *
   8  * This program is distributed in the hope that it will be useful, but WITHOUT
   9  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  11  * more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along with
  14  * this program; if not, write to the Free Software Foundation, Inc., 51
  15  * Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  16  */
  17
  18 #ifndef _CONFIG_H
  19 #define _CONFIG_H
  20
  21 #include <common/config/ini.h>
  22 #include <common/config/config-session-abi.h>
  23 #include <common/macros.h>
  24 #include <stdint.h>
  25
  26 struct config_entry {
  27         /* section is NULL if the entry is not in a section */
  28         const char *section;
  29         const char *name;
  30         const char *value;
  31 };
  32
  33 /* Instance of a configuration writer. */
  34 struct config_writer;
  35
  36 /* Instance of a configuration document */
  37 struct config_document;
  38
  39 struct config_element;
  40
  41 /*
  42  * A config_entry_handler_cb receives config_entry structures belonging to the
  43  * sections the handler has been registered to.
  44  *
  45  * The config_entry and its members are only valid for the duration of the call
  46  * and must not be freed.
  47  *
  48  * config_entry_handler_cb may return negative value to indicate an error in
  49  * the configuration file.
  50  */
  51 typedef int (*config_entry_handler_cb)(const struct config_entry *, void *);
  52
  53 /*
  54  * Read a section's entries in an INI configuration file.
  55  *
  56  * path may be NULL, in which case the following paths will be tried:
  57  *      1) $HOME/.lttng/lttng.conf
  58  *      2) /etc/lttng/lttng.conf
  59  *
  60  * handler will only be called with entries belonging to the provided section.
  61  * If section is NULL, all entries will be relayed to handler. If section is
  62  * "", only the global entries are relayed.
  63  *
  64  * Returns 0 on success. Negative values are error codes. If the return value
  65  * is positive, it represents the line number on which a parsing error occurred.
  66  */
  67 LTTNG_HIDDEN
  68 int config_get_section_entries(const char *path, const char *section,
  69                 config_entry_handler_cb handler, void *user_data);
  70
  71 /*
  72  * Parse a configuration value.
  73  *
  74  * This function expects either an unsigned integer or a boolean text option.
  75  * The following strings are recognized: true, yes, on, false, no and off.
  76  *
  77  * Returns either the value of the parsed integer, or 0/1 if a boolean text
  78  * string was recognized. Negative values indicate an error.
  79  */
  80 LTTNG_HIDDEN
  81 int config_parse_value(const char *value);
  82
  83 /*
  84  * Create an instance of a configuration writer.
  85  *
  86  * fd_output File to which the XML content must be written. The file will be
  87  * closed once the config_writer has been destroyed.
  88  *
  89  * indent If other than 0 the XML will be pretty printed
  90  * with indentation and newline.
  91  *
  92  * Returns an instance of a configuration writer on success, NULL on
  93  * error.
  94  */
  95 LTTNG_HIDDEN
  96 struct config_writer *config_writer_create(int fd_output, int indent);
  97
  98 /*
  99  * Destroy an instance of a configuration writer.
 100  *
 101  * writer An instance of a configuration writer.
 102  *
 103  * Returns zero if the XML document could be closed cleanly. Negative values
 104  * indicate an error.
 105  */
 106 LTTNG_HIDDEN
 107 int config_writer_destroy(struct config_writer *writer);
 108
 109 /*
 110  * Open an element tag.
 111  *
 112  * writer An instance of a configuration writer.
 113  *
 114  * element_name Element tag name.
 115  *
 116  * Returns zero if the XML element could be opened.
 117  * Negative values indicate an error.
 118  */
 119 LTTNG_HIDDEN
 120 int config_writer_open_element(struct config_writer *writer,
 121                 const char *element_name);
 122
 123 /*
 124  * Write an element tag attribute.
 125  *
 126  * writer An instance of a configuration writer.
 127  *
 128  * name Attribute name.
 129  *
 130  * Returns zero if the XML element's attribute could be written.
 131  * Negative values indicate an error.
 132  */
 133 LTTNG_HIDDEN
 134 int config_writer_write_attribute(struct config_writer *writer,
 135                 const char *name, const char *value);
 136
 137 /*
 138  * Close the current element tag.
 139  *
 140  * writer An instance of a configuration writer.
 141  *
 142  * Returns zero if the XML document could be closed cleanly.
 143  * Negative values indicate an error.
 144  */
 145 LTTNG_HIDDEN
 146 int config_writer_close_element(struct config_writer *writer);
 147
 148 /*
 149  * Write an element of type unsigned int.
 150  *
 151  * writer An instance of a configuration writer.
 152  *
 153  * element_name Element name.
 154  *
 155  * value Unsigned int value of the element
 156  *
 157  * Returns zero if the element's value could be written.
 158  * Negative values indicate an error.
 159  */
 160 LTTNG_HIDDEN
 161 int config_writer_write_element_unsigned_int(struct config_writer *writer,
 162                 const char *element_name, uint64_t value);
 163
 164 /*
 165  * Write an element of type signed int.
 166  *
 167  * writer An instance of a configuration writer.
 168  *
 169  * element_name Element name.
 170  *
 171  * value Signed int value of the element
 172  *
 173  * Returns zero if the element's value could be written.
 174  * Negative values indicate an error.
 175  */LTTNG_HIDDEN
 176 int config_writer_write_element_signed_int(struct config_writer *writer,
 177                 const char *element_name, int64_t value);
 178
 179 /*
 180  * Write an element of type boolean.
 181  *
 182  * writer An instance of a configuration writer.
 183  *
 184  * element_name Element name.
 185  *
 186  * value Boolean value of the element
 187  *
 188  * Returns zero if the element's value could be written.
 189  * Negative values indicate an error.
 190  */
 191 LTTNG_HIDDEN
 192 int config_writer_write_element_bool(struct config_writer *writer,
 193                 const char *element_name, int value);
 194
 195 /*
 196  * Write an element of type string.
 197  *
 198  * writer An instance of a configuration writer.
 199  *
 200  * element_name Element name.
 201  *
 202  * value String value of the element
 203  *
 204  * Returns zero if the element's value could be written.
 205  * Negative values indicate an error.
 206  */
 207 LTTNG_HIDDEN
 208 int config_writer_write_element_string(struct config_writer *writer,
 209                 const char *element_name, const char *value);
 210
 211 /*
 212  * Load session configurations from a file.
 213  *
 214  * path Path to an LTTng session configuration file. All *.lttng files
 215  * will be loaded if path is a directory. If path is NULL, the default
 216  * paths will be searched in the following order:
 217  *      1) $HOME/.lttng/sessions
 218  *      2) /etc/lttng/sessions
 219  *
 220  * session_name Name of the session to load. Will load all
 221  * sessions from path if NULL.
 222  *
 223  * override Override current session configuration if it exists.
 224  * autoload Tell to load the auto session(s).
 225  *
 226  * Returns zero if the session could be loaded successfully. Returns
 227  * a negative LTTNG_ERR code on error.
 228  */
 229 LTTNG_HIDDEN
 230 int config_load_session(const char *path, const char *session_name,
 231                 int override, unsigned int autoload);
 232
 233 /*
 234  * Load session configuration from a document
 235  *
 236  * document The document to be loaded as a configuration
 237  * session_name Name of the session to load. Will load all sessions from the
 238  * passed document if NULL
 239  *
 240  * override Override current session configuration if it exists.
 241  *
 242  * Returns zero if the session could be loaded successfully. Returns
 243  * a negative LTTNG_ERR code on error.
 244  */
 245 LTTNG_HIDDEN
 246 int config_load_configuration_sessions(struct config_document *document,
 247                 const char *session_name, int override);
 248
 249 /*
 250  * Get the document corresponding to the path.
 251  *
 252  * path Path to a configuration file.
 253  * xsd_validation Whether or not to do a xsd validation
 254  *
 255  * Returns an new allocated config_document when successful.
 256  * Returns NULL on error;
 257  *
 258  * The caller is responsible of freeing the document via config_document_free.
 259  */
 260 LTTNG_HIDDEN
 261 struct config_document *config_document_get(const char *path);
 262
 263 /*
 264  * Free an allocated document.
 265  *
 266  * document The document to free.
 267  */
 268 LTTNG_HIDDEN
 269 void config_document_free(struct config_document *document);
 270
 271 /*
 272  * Replace the value of a document element
 273  *
 274  * document The document containing the element to be modified.
 275  * xpath The xpath string to the element.
 276  * value The value to be placed inside the element.
 277  *
 278  * Returns zero if the session could be loaded successfully. Returns
 279  * a negative LTTNG_ERR code on error.
 280  * */
 281 LTTNG_HIDDEN
 282 int config_document_replace_element_value(struct config_document *document, const char *xpath, const char *value);
 283
 284 /*
 285  * Swap a document node by the passed element.
 286  *
 287  * document The document containing the element to be modified.
 288  * xpath The xpath string to the element.
 289  * element The replacement element.
 290  *
 291  * Returns zero if the session could be loaded successfully. Returns
 292  * a negative LTTNG_ERR code on error.
 293  */
 294 LTTNG_HIDDEN
 295 int config_document_replace_element(struct config_document *document, const char *xpath, const struct config_element *element);
 296
 297 /*
 298  * Get the value of a document element.
 299  *
 300  * document The document to be searched.
 301  * xpath The xpath string to the element.
 302  *
 303  * Return null if multiple values exists or there is no
 304  * value for the passed path.
 305  */
 306 LTTNG_HIDDEN
 307 char *config_document_get_element_value(struct config_document *document, const char *xpath);
 308
 309 /*
 310  * Check if an element exists inside a document.
 311  *
 312  * document The document to be searched.
 313  * xpath The xpath string to the element.
 314  *
 315  * Returns 1 on success and 0 on failure.
 316  */
 317 LTTNG_HIDDEN
 318 int config_document_element_exist(struct config_document *document, const char *xpath);
 319
 320 /*
 321  *
 322  */
 323 LTTNG_HIDDEN
 324 void config_element_free(struct config_element *element);
 325
 326 LTTNG_HIDDEN
 327 struct config_element *config_element_create(const char *name, const char *value);
 328
 329 /*
 330  * Add a child element to an element.
 331  *
 332  * parent The parent element.
 333  * child The element to add as a child.
 334  *
 335  * Returns zero if the session could be loaded successfully. Returns
 336  * a negative LTTNG_ERR code on error.
 337  */
 338 LTTNG_HIDDEN
 339 int config_element_add_child(struct config_element *parent, const struct config_element *child);
 340
 341 /*
 342  * Insert element to an existing document.
 343  *
 344  * document The document to be modified.
 345  * xpath The xpath string to the insertion path.
 346  * element The element to be inserted.
 347  *
 348  * Returns zero if the session could be loaded successfully. Returns
 349  * a negative LTTNG_ERR code on error.
 350  */
 351 LTTNG_HIDDEN
 352 int config_document_insert_element(struct config_document *document, const char *xpath, const struct config_element *element);
 353
 354
 355 #endif /* _CONFIG_H */