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