include/lttng/load.h

   1 /*
   2  * Copyright (C) 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  * Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-only
   6  *
   7  */
   8
   9 #ifndef LTTNG_LOAD_H
  10 #define LTTNG_LOAD_H
  11
  12 #include <lttng/lttng-export.h>
  13
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 /*
  19  * The lttng_load_session_attr object is opaque to the user. Use the helper
  20  * functions below to use it.
  21  */
  22 struct lttng_load_session_attr;
  23
  24 /*
  25  * Return a newly allocated load session attribute object or NULL on error.
  26  */
  27 LTTNG_EXPORT extern struct lttng_load_session_attr *lttng_load_session_attr_create(void);
  28
  29 /*
  30  * Free a given load session attribute object.
  31  */
  32 LTTNG_EXPORT extern void lttng_load_session_attr_destroy(struct lttng_load_session_attr *attr);
  33
  34
  35 /*
  36  * Load session attribute getter family of functions.
  37  */
  38
  39 /* Return session name. NULL indicates all sessions must be loaded. */
  40 LTTNG_EXPORT extern const char *lttng_load_session_attr_get_session_name(
  41         struct lttng_load_session_attr *attr);
  42 /*
  43  * Return input URL. A NULL value indicates the default session
  44  * configuration location. The URL format used is documented in lttng-create(1).
  45  * NULL indicates that the default session configuration path is used.
  46  */
  47 LTTNG_EXPORT extern const char *lttng_load_session_attr_get_input_url(
  48         struct lttng_load_session_attr *attr);
  49
  50 /*
  51  * Return the configuration overwrite attribute. This attribute indicates
  52  * whether or not the loaded session should be loaded even if a session with the
  53  * same name already exists. If such a session exists, it is destroyed before
  54  * the replacement is loaded.
  55  */
  56 LTTNG_EXPORT extern int lttng_load_session_attr_get_overwrite(
  57         struct lttng_load_session_attr *attr);
  58
  59 /*
  60  * Return the destination URL configuration override attribute. This attribute
  61  * indicates a destination URL override to be applied during the loading of the
  62  * configuration.
  63  *
  64  * NULL indicates no override will be applied on configuration load.
  65  */
  66 LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_url(
  67         struct lttng_load_session_attr *attr);
  68
  69 /*
  70  * Return the configuration override control URL attribute. This attribute
  71  * indicates a control URL override to be applied during the loading of the
  72  * configuration(s).
  73  *
  74  * NULL indicates no control URL override will be applied on configuration load.
  75  */
  76 LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_ctrl_url(
  77         struct lttng_load_session_attr *attr);
  78
  79 /*
  80  * Return the configuration override data URL attribute. This attribute
  81  * indicates a data URL override to be applied during the loading of the
  82  * configuration(s).
  83  *
  84  * NULL indicates no data URL override will be applied on configuration load.
  85  */
  86 LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_data_url(
  87         struct lttng_load_session_attr *attr);
  88
  89 /*
  90  * Return the configuration override session name attribute.
  91  * This attribute indicates a session name override to be applied during
  92  * the loading of the configuration(s).
  93  *
  94  * NULL indicates no session name override will be applied on configuration
  95  * load.
  96  */
  97 LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_session_name(
  98         struct lttng_load_session_attr *attr);
  99
 100 /*
 101  * Load session attribute setter family of functions.
 102  *
 103  * For every set* call, 0 is returned on success or else -LTTNG_ERR_INVALID is
 104  * returned indicating that at least one given parameter is invalid.
 105  */
 106
 107 /*
 108  * Set the name of the session to load. A NULL name means all sessions
 109  * found at the input URL will be loaded.
 110  */
 111 LTTNG_EXPORT extern int lttng_load_session_attr_set_session_name(
 112         struct lttng_load_session_attr *attr, const char *session_name);
 113
 114 /*
 115  * Set the URL of the session configuration to load. A NULL value indicates the
 116  * use of the default session configuration location.
 117  *
 118  * Note that file:// is the only supported URL format.
 119  */
 120 LTTNG_EXPORT extern int lttng_load_session_attr_set_input_url(
 121         struct lttng_load_session_attr *attr, const char *url);
 122
 123 /*
 124  * Set the overwrite attribute. If set to true, current sessions matching the
 125  * loaded sessions will be destroyed and be replaced by the session(s) being
 126  * loaded.
 127  */
 128 LTTNG_EXPORT extern int lttng_load_session_attr_set_overwrite(
 129         struct lttng_load_session_attr *attr, int overwrite);
 130
 131 /*
 132  * The following setter are for overriding sessions attributes during the
 133  * loading of a configuration files. Those attributes prevail upon those
 134  * specified in the loaded configuration file.
 135  * */
 136
 137 /*
 138  * Set the url override attribute.
 139  *
 140  * Supported format:
 141  *    file://TRACEPATH
 142  *    NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH]
 143  *
 144  *     Where NETPROTO is one of {tcp, tcp6}
 145  *
 146  * See lttng-create(1) for more detail.
 147  */
 148 LTTNG_EXPORT extern int lttng_load_session_attr_set_override_url(
 149         struct lttng_load_session_attr *attr, const char *url);
 150
 151 /*
 152  * Set the control url override attribute.
 153  *
 154  * Supported format:
 155  *     NETPROTO://(HOST | IPADDR)[:PORT][/TRACEPATH]
 156  *
 157  *     Where NETPROTO is one of {tcp, tcp6}
 158  *
 159  * See lttng-create(1) for more detail.
 160  */
 161 LTTNG_EXPORT extern int lttng_load_session_attr_set_override_ctrl_url(
 162         struct lttng_load_session_attr *attr, const char *url);
 163
 164 /*
 165  * Set the data url override attribute.
 166  *
 167  * Supported format:
 168  *     NETPROTO://(HOST | IPADDR)[:PORT][/TRACEPATH]
 169  *
 170  *     Where NETPROTO is one of {tcp, tcp6}
 171  *
 172  * See lttng-create(1) for more detail.
 173  */
 174 LTTNG_EXPORT extern int lttng_load_session_attr_set_override_data_url(
 175         struct lttng_load_session_attr *attr, const char *url);
 176
 177 /*
 178  * Set the session name override attribute.
 179  *
 180  * Loading a configuration file defining multiple sessions will fail if a
 181  * session name is provided.
 182  */
 183 LTTNG_EXPORT extern int lttng_load_session_attr_set_override_session_name(
 184         struct lttng_load_session_attr *attr, const char *session_name);
 185
 186 /*
 187  * Load session configuration(s).
 188  *
 189  * The lttng_load_session_attr object must not be NULL. No ownership of the
 190  * object is kept by the function; it must be released by the caller.
 191  *
 192  * Returns 0 on success or a negative LTTNG_ERR value on error.
 193  */
 194 LTTNG_EXPORT extern int lttng_load_session(struct lttng_load_session_attr *attr);
 195
 196 #ifdef __cplusplus
 197 }
 198 #endif
 199
 200 #endif /* LTTNG_LOAD_H */