2 * Copyright (C) 2013 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
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.
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
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.
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 <lttng/event.h>
29 /* section is NULL if the entry is not in a section */
35 /* Instance of a configuration writer. */
38 /* Instance of a configuration document */
39 struct config_document
;
41 /* Instance of a configuration element */
42 struct config_element
;
45 * Return the config string representation of a kernel type.
48 const char *config_get_domain_str(enum lttng_domain_type domain
);
51 * Return the config string representation of a loglevel type.
54 const char *config_get_loglevel_type_string(
55 enum lttng_loglevel_type loglevel_type
);
58 * Return the event_type int value of lttng_event_type enumeration based on the
62 int config_get_event_type(const char *event_type
);
65 * A config_entry_handler_cb receives config_entry structures belonging to the
66 * sections the handler has been registered to.
68 * The config_entry and its members are only valid for the duration of the call
69 * and must not be freed.
71 * config_entry_handler_cb may return negative value to indicate an error in
72 * the configuration file.
74 typedef int (*config_entry_handler_cb
)(const struct config_entry
*, void *);
77 * Read a section's entries in an INI configuration file.
79 * path may be NULL, in which case the following paths will be tried:
80 * 1) $HOME/.lttng/lttng.conf
81 * 2) /etc/lttng/lttng.conf
83 * handler will only be called with entries belonging to the provided section.
84 * If section is NULL, all entries will be relayed to handler. If section is
85 * "", only the global entries are relayed.
87 * Returns 0 on success. Negative values are error codes. If the return value
88 * is positive, it represents the line number on which a parsing error occurred.
91 int config_get_section_entries(const char *path
, const char *section
,
92 config_entry_handler_cb handler
, void *user_data
);
95 * Parse a configuration value.
97 * This function expects either an unsigned integer or a boolean text option.
98 * The following strings are recognized: true, yes, on, false, no and off.
100 * Returns either the value of the parsed integer, or 0/1 if a boolean text
101 * string was recognized. Negative values indicate an error.
104 int config_parse_value(const char *value
);
107 * Create an instance of a configuration writer.
109 * fd_output File to which the XML content must be written. The file will be
110 * closed once the config_writer has been destroyed.
112 * indent If other than 0 the XML will be pretty printed
113 * with indentation and newline.
115 * Returns an instance of a configuration writer on success, NULL on
119 struct config_writer
*config_writer_create(int fd_output
, int indent
);
122 * Destroy an instance of a configuration writer.
124 * writer An instance of a configuration writer.
126 * Returns zero if the XML document could be closed cleanly. Negative values
130 int config_writer_destroy(struct config_writer
*writer
);
133 * Open an element tag.
135 * writer An instance of a configuration writer.
137 * element_name Element tag name.
139 * Returns zero if the XML element could be opened.
140 * Negative values indicate an error.
143 int config_writer_open_element(struct config_writer
*writer
,
144 const char *element_name
);
147 * Write an element tag attribute.
149 * writer An instance of a configuration writer.
151 * name Attribute name.
153 * Returns zero if the XML element's attribute could be written.
154 * Negative values indicate an error.
157 int config_writer_write_attribute(struct config_writer
*writer
,
158 const char *name
, const char *value
);
161 * Close the current element tag.
163 * writer An instance of a configuration writer.
165 * Returns zero if the XML document could be closed cleanly.
166 * Negative values indicate an error.
169 int config_writer_close_element(struct config_writer
*writer
);
172 * Write an element of type unsigned int.
174 * writer An instance of a configuration writer.
176 * element_name Element name.
178 * value Unsigned int value of the element
180 * Returns zero if the element's value could be written.
181 * Negative values indicate an error.
184 int config_writer_write_element_unsigned_int(struct config_writer
*writer
,
185 const char *element_name
, uint64_t value
);
188 * Write an element of type signed int.
190 * writer An instance of a configuration writer.
192 * element_name Element name.
194 * value Signed int value of the element
196 * Returns zero if the element's value could be written.
197 * Negative values indicate an error.
199 int config_writer_write_element_signed_int(struct config_writer
*writer
,
200 const char *element_name
, int64_t value
);
203 * Write an element of type boolean.
205 * writer An instance of a configuration writer.
207 * element_name Element name.
209 * value Boolean value of the element
211 * Returns zero if the element's value could be written.
212 * Negative values indicate an error.
215 int config_writer_write_element_bool(struct config_writer
*writer
,
216 const char *element_name
, int value
);
219 * Write an element of type string.
221 * writer An instance of a configuration writer.
223 * element_name Element name.
225 * value String value of the element
227 * Returns zero if the element's value could be written.
228 * Negative values indicate an error.
231 int config_writer_write_element_string(struct config_writer
*writer
,
232 const char *element_name
, const char *value
);
235 * Write an element of type config_element.
237 * writer An instance of a configuration writer.
239 * element The config_element instance.
241 * Returns zero if the element could be written.
242 * Negative values indicate an error.
245 int config_writer_write_config_element(struct config_writer
*writer
,
246 const struct config_element
*element
);
248 * Load session configurations from a file.
250 * path Path to an LTTng session configuration file. All *.lttng files
251 * will be loaded if path is a directory. If path is NULL, the default
252 * paths will be searched in the following order:
253 * 1) $HOME/.lttng/sessions
254 * 2) /etc/lttng/sessions
256 * session_name Name of the session to load. Will load all
257 * sessions from path if NULL.
259 * override Override current session configuration if it exists.
260 * autoload Tell to load the auto session(s).
262 * Returns zero if the session could be loaded successfully. Returns
263 * a negative LTTNG_ERR code on error.
266 int config_load_session(const char *path
, const char *session_name
,
267 int override
, unsigned int autoload
);
270 * Load session configuration from a document
272 * document The document to be loaded as a configuration
273 * session_name Name of the session to load. Will load all sessions from the
274 * passed document if NULL
276 * override Override current session configuration if it exists.
278 * Returns zero if the session could be loaded successfully. Returns
279 * a negative LTTNG_ERR code on error.
282 int config_load_configuration_sessions(struct config_document
*document
,
283 const char *session_name
, int override
);
286 * Get the document corresponding to the path.
288 * path Path to a configuration file.
289 * xsd_validation Whether or not to do a xsd validation
291 * Returns an new allocated config_document when successful.
292 * Returns NULL on error;
294 * The caller is responsible of freeing the document via config_document_free.
297 struct config_document
*config_document_get(const char *path
, int xsd_validation
);
300 * Free an allocated document.
302 * document The document to free.
305 void config_document_free(struct config_document
*document
);
308 * Replace the value of a document element
310 * document The document containing the element to be modified.
311 * xpath The xpath string to the element.
312 * value The value to be placed inside the element.
314 * Returns zero if the session could be loaded successfully. Returns
315 * a negative LTTNG_ERR code on error.
318 int config_document_replace_element_value(struct config_document
*document
, const char *xpath
, const char *value
);
321 * Swap a document node by the passed element.
323 * document The document containing the element to be modified.
324 * xpath The xpath string to the element.
325 * element The replacement element.
327 * Returns zero if the session could be loaded successfully. Returns
328 * a negative LTTNG_ERR code on error.
331 int config_document_replace_element(struct config_document
*document
, const char *xpath
, const struct config_element
*element
);
334 * Get the value of a document element.
336 * document The document to be searched.
337 * xpath The xpath string to the element.
339 * Return null if multiple values exists or there is no
340 * value for the passed path.
343 char *config_document_get_element_value(struct config_document
*document
, const char *xpath
);
346 * Check if an element exists inside a document.
348 * document The document to be searched.
349 * xpath The xpath string to the element.
351 * Returns 1 on success and 0 on failure.
354 int config_document_element_exist(struct config_document
*document
, const char *xpath
);
357 * Create a configuration element.
359 * name The name of the element
360 * value The value to be assigned to the element. The value can be NULL.
362 * Returns a new configuration element.
364 * The caller is responsible of freeing the allocated element with
365 * config_element_free.
368 struct config_element
*config_element_create(const char *name
, const char *value
);
371 * Free a config_element
373 * element The element to free.
376 void config_element_free(struct config_element
*element
);
379 * Add a child element to an element.
381 * parent The parent element.
382 * child The element to add as a child.
384 * Returns zero if the session could be loaded successfully. Returns
385 * a negative LTTNG_ERR code on error.
388 int config_element_add_child(struct config_element
*parent
, const struct config_element
*child
);
391 * Insert element to an existing document.
393 * document The document to be modified.
394 * xpath The xpath string to the insertion path.
395 * element The element to be inserted.
397 * Returns zero if the session could be loaded successfully. Returns
398 * a negative LTTNG_ERR code on error.
401 int config_document_insert_element(struct config_document
*document
, const char *xpath
, const struct config_element
*element
);
404 * Get an array of elements from a document.
406 * document The source document.
407 * xpath The xpath string matching the elements path.
408 * element_array The resulting array
409 * array_size The resulting array size
411 * element_array is NULL on error.
413 * The caller is responsible of freeing the array with
414 * config_element_free_array.
417 void config_document_get_element_array(const struct config_document
*document
, const char *xpath
, struct config_element
***element_array
, int *array_size
);
420 * Get an array of elements from an element.
422 * element The source element.
423 * xpath The xpath string matching the elements path.
424 * element_array The resulting array
425 * array_size The resulting array size
427 * element_array is NULL on error.
429 * The caller is responsible of freeing the array with
430 * config_element_free_array.
433 void config_element_get_element_array(const struct config_element
*element
, const char *xpath
, struct config_element
***element_array
, int *array_size
);
436 * Free an array of element.
438 * array The array to free
439 * size The size of the array
442 void config_element_free_array(struct config_element
**array
, int size
);
445 * Add an element as a child if a equivalent element is present replace it with
446 * the passed element.
448 * parent The parent element.
449 * child The child to add.
451 * Returns zero if the session could be loaded successfully. Returns
452 * a negative LTTNG_ERR code on error.
455 int config_element_add_or_replace_child(struct config_element
*parent
, struct config_element
*child
);
458 * Get the value of an element under an element.
460 * element The base element.
461 * xpath The xpath string to the element.
463 * Return null if multiple values exists or there is no
464 * value for the passed path.
467 char *config_element_get_element_value(const struct config_element
*element
, const char *xpath
);
470 * Process an element matching an event configuration and try to enable it.
472 * element The element to process
473 * session_name The session name to use for event enabling.
474 * domain_type The domain type to use for event enabling
475 * channel_name The channel name to use for event enabling
476 * A NULL channel name will default to the default domain
479 * Returns zero if the session could be loaded successfully. Returns
480 * a negative LTTNG_ERR code on error.
483 int config_process_event_element(const struct config_element
*element
, const char* session_name
, int domain_type
, const char *channel_name
);
485 #endif /* _CONFIG_H */