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  * Write an element of type config_element.
 220  *
 221  * writer An instance of a configuration writer.
 222  *
 223  * element The config_element instance.
 224  *
 225  * Returns zero if the element could be written.
 226  * Negative values indicate an error.
 227  */
 228 LTTNG_HIDDEN
 229 int config_writer_write_config_element(struct config_writer *writer,
 230                 const struct config_element *element);
 231 /*
 232  * Load session configurations from a file.
 233  *
 234  * path Path to an LTTng session configuration file. All *.lttng files
 235  * will be loaded if path is a directory. If path is NULL, the default
 236  * paths will be searched in the following order:
 237  *      1) $HOME/.lttng/sessions
 238  *      2) /etc/lttng/sessions
 239  *
 240  * session_name Name of the session to load. Will load all
 241  * sessions from path if NULL.
 242  *
 243  * override Override current session configuration if it exists.
 244  * autoload Tell to load the auto session(s).
 245  *
 246  * Returns zero if the session could be loaded successfully. Returns
 247  * a negative LTTNG_ERR code on error.
 248  */
 249 LTTNG_HIDDEN
 250 int config_load_session(const char *path, const char *session_name,
 251                 int override, unsigned int autoload);
 252
 253 /*
 254  * Load session configuration from a document
 255  *
 256  * document The document to be loaded as a configuration
 257  * session_name Name of the session to load. Will load all sessions from the
 258  * passed document if NULL
 259  *
 260  * override Override current session configuration if it exists.
 261  *
 262  * Returns zero if the session could be loaded successfully. Returns
 263  * a negative LTTNG_ERR code on error.
 264  */
 265 LTTNG_HIDDEN
 266 int config_load_configuration_sessions(struct config_document *document,
 267                 const char *session_name, int override);
 268
 269 /*
 270  * Get the document corresponding to the path.
 271  *
 272  * path Path to a configuration file.
 273  * xsd_validation Whether or not to do a xsd validation
 274  *
 275  * Returns an new allocated config_document when successful.
 276  * Returns NULL on error;
 277  *
 278  * The caller is responsible of freeing the document via config_document_free.
 279  */
 280 LTTNG_HIDDEN
 281 struct config_document *config_document_get(const char *path);
 282
 283 /*
 284  * Free an allocated document.
 285  *
 286  * document The document to free.
 287  */
 288 LTTNG_HIDDEN
 289 void config_document_free(struct config_document *document);
 290
 291 /*
 292  * Replace the value of a document element
 293  *
 294  * document The document containing the element to be modified.
 295  * xpath The xpath string to the element.
 296  * value The value to be placed inside the 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_value(struct config_document *document, const char *xpath, const char *value);
 303
 304 /*
 305  * Swap a document node by the passed element.
 306  *
 307  * document The document containing the element to be modified.
 308  * xpath The xpath string to the element.
 309  * element The replacement element.
 310  *
 311  * Returns zero if the session could be loaded successfully. Returns
 312  * a negative LTTNG_ERR code on error.
 313  */
 314 LTTNG_HIDDEN
 315 int config_document_replace_element(struct config_document *document, const char *xpath, const struct config_element *element);
 316
 317 /*
 318  * Get the value of a document element.
 319  *
 320  * document The document to be searched.
 321  * xpath The xpath string to the element.
 322  *
 323  * Return null if multiple values exists or there is no
 324  * value for the passed path.
 325  */
 326 LTTNG_HIDDEN
 327 char *config_document_get_element_value(struct config_document *document, const char *xpath);
 328
 329 /*
 330  * Check if an element exists inside a document.
 331  *
 332  * document The document to be searched.
 333  * xpath The xpath string to the element.
 334  *
 335  * Returns 1 on success and 0 on failure.
 336  */
 337 LTTNG_HIDDEN
 338 int config_document_element_exist(struct config_document *document, const char *xpath);
 339
 340 /*
 341  *
 342  */
 343 LTTNG_HIDDEN
 344 void config_element_free(struct config_element *element);
 345
 346 LTTNG_HIDDEN
 347 struct config_element *config_element_create(const char *name, const char *value);
 348
 349 /*
 350  * Add a child element to an element.
 351  *
 352  * parent The parent element.
 353  * child The element to add as a child.
 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_element_add_child(struct config_element *parent, const struct config_element *child);
 360
 361 /*
 362  * Insert element to an existing document.
 363  *
 364  * document The document to be modified.
 365  * xpath The xpath string to the insertion path.
 366  * element The element to be inserted.
 367  *
 368  * Returns zero if the session could be loaded successfully. Returns
 369  * a negative LTTNG_ERR code on error.
 370  */
 371 LTTNG_HIDDEN
 372 int config_document_insert_element(struct config_document *document, const char *xpath, const struct config_element *element);
 373
 374
 375 #endif /* _CONFIG_H */