include/lttng/snapshot.h

   1 /*
   2  * Copyright (C) 2013 David Goulet <dgoulet@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_SNAPSHOT_H
   9 #define LTTNG_SNAPSHOT_H
  10
  11 #include <lttng/lttng-export.h>
  12
  13 #include <limits.h>
  14 #include <stdint.h>
  15 #include <sys/types.h>
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 /*
  22  * Snapshot output object is opaque to the user. Use the helper functions below
  23  * to use them.
  24  */
  25 struct lttng_snapshot_output;
  26 struct lttng_snapshot_output_list;
  27
  28 /*
  29  * Return an newly allocated snapshot output object or NULL on error.
  30  */
  31 LTTNG_EXPORT extern struct lttng_snapshot_output *lttng_snapshot_output_create(void);
  32
  33 /*
  34  * Free a given snapshot output object.
  35  */
  36 LTTNG_EXPORT extern void lttng_snapshot_output_destroy(struct lttng_snapshot_output *output);
  37
  38 /*
  39  * Snapshot output getter family functions. They all return the value present
  40  * in the object.
  41  */
  42
  43 /* Return snapshot ID. */
  44 LTTNG_EXPORT extern uint32_t
  45 lttng_snapshot_output_get_id(const struct lttng_snapshot_output *output);
  46 /* Return maximum size of a snapshot. */
  47 LTTNG_EXPORT extern uint64_t
  48 lttng_snapshot_output_get_maxsize(const struct lttng_snapshot_output *output);
  49 /* Return snapshot name. */
  50 LTTNG_EXPORT extern const char *
  51 lttng_snapshot_output_get_name(const struct lttng_snapshot_output *output);
  52 /* Return snapshot control URL in a text format. */
  53 LTTNG_EXPORT extern const char *
  54 lttng_snapshot_output_get_ctrl_url(const struct lttng_snapshot_output *output);
  55 /* Return snapshot data URL in a text format. */
  56 LTTNG_EXPORT extern const char *
  57 lttng_snapshot_output_get_data_url(const struct lttng_snapshot_output *output);
  58
  59 /*
  60  * Snapshot output setter family functions.
  61  *
  62  * For every set* call, 0 is returned on success or else -LTTNG_ERR_INVALID is
  63  * returned indicating that at least one given parameter is invalid.
  64  */
  65
  66 /* Set a custom ID. */
  67 LTTNG_EXPORT extern int lttng_snapshot_output_set_id(uint32_t id,
  68                                                      struct lttng_snapshot_output *output);
  69 /* Set the maximum size. */
  70 LTTNG_EXPORT extern int lttng_snapshot_output_set_size(uint64_t size,
  71                                                        struct lttng_snapshot_output *output);
  72 /* Set the snapshot name. */
  73 LTTNG_EXPORT extern int lttng_snapshot_output_set_name(const char *name,
  74                                                        struct lttng_snapshot_output *output);
  75
  76 /*
  77  * Set the output destination to be a path on the local filesystem.
  78  *
  79  * The path must be absolute. It can optionally begin with `file://`.
  80  *
  81  * Return 0 on success or else a negative LTTNG_ERR code.
  82  */
  83 LTTNG_EXPORT extern int lttng_snapshot_output_set_local_path(const char *path,
  84                                                              struct lttng_snapshot_output *output);
  85
  86 /*
  87  * Set the output destination to be the network from a combined control/data
  88  * URL.
  89  *
  90  * `url` must start with `net://` or `net6://`.
  91  *
  92  * Return 0 on success or else a negative LTTNG_ERR code.
  93  */
  94 LTTNG_EXPORT extern int lttng_snapshot_output_set_network_url(const char *url,
  95                                                               struct lttng_snapshot_output *output);
  96
  97 /*
  98  * Set the output destination to be the network using separate URLs for control
  99  * and data.
 100  *
 101  * Both ctrl_url and data_url must be non-null.
 102  *
 103  * `ctrl_url` and `data_url` must start with `tcp://` or `tcp6://`.
 104  *
 105  * Return 0 on success or else a negative LTTNG_ERR code.
 106  */
 107 LTTNG_EXPORT extern int lttng_snapshot_output_set_network_urls(
 108         const char *ctrl_url, const char *data_url, struct lttng_snapshot_output *output);
 109
 110 /* Set the control URL. Local and remote URL are supported. */
 111 LTTNG_EXPORT extern int lttng_snapshot_output_set_ctrl_url(const char *url,
 112                                                            struct lttng_snapshot_output *output);
 113 /* Set the data URL. Local and remote URL are supported. */
 114 LTTNG_EXPORT extern int lttng_snapshot_output_set_data_url(const char *url,
 115                                                            struct lttng_snapshot_output *output);
 116
 117 /*
 118  * Add an output object to a session identified by name.
 119  *
 120  * Return 0 on success or else a negative LTTNG_ERR code.
 121  */
 122 LTTNG_EXPORT extern int lttng_snapshot_add_output(const char *session_name,
 123                                                   struct lttng_snapshot_output *output);
 124
 125 /*
 126  * Delete an output object to a session identified by name.
 127  *
 128  * Return 0 on success or else a negative LTTNG_ERR code.
 129  */
 130 LTTNG_EXPORT extern int lttng_snapshot_del_output(const char *session_name,
 131                                                   struct lttng_snapshot_output *output);
 132
 133 /*
 134  * List all snapshot output(s) of a session identified by name. The output list
 135  * object is populated and can be iterated over with the get_next call below.
 136  *
 137  * Return 0 on success or else a negative LTTNG_ERR code and the list pointer
 138  * is untouched.
 139  */
 140 LTTNG_EXPORT extern int lttng_snapshot_list_output(const char *session_name,
 141                                                    struct lttng_snapshot_output_list **list);
 142
 143 /*
 144  * Return the next available snapshot output object in the given list. A list
 145  * output command MUST have been done before.
 146  *
 147  * Return the next object on success or else NULL indicating the end of the
 148  * list.
 149  */
 150 LTTNG_EXPORT extern struct lttng_snapshot_output *
 151 lttng_snapshot_output_list_get_next(struct lttng_snapshot_output_list *list);
 152
 153 /*
 154  * Free an output list object.
 155  */
 156 LTTNG_EXPORT extern void
 157 lttng_snapshot_output_list_destroy(struct lttng_snapshot_output_list *list);
 158
 159 /*
 160  * Snapshot a trace for the given session.
 161  *
 162  * The output object can be NULL but an add output MUST be done prior to this
 163  * call. If it's not NULL, it will be used to snapshot a trace.
 164  *
 165  * The wait parameter is ignored for now. The snapshot record command will
 166  * ALWAYS wait for the snapshot to complete before returning meaning the
 167  * snapshot has been written on disk or streamed over the network to a relayd.
 168  *
 169  * Return 0 on success or else a negative LTTNG_ERR value.
 170  */
 171 LTTNG_EXPORT extern int
 172 lttng_snapshot_record(const char *session_name, struct lttng_snapshot_output *output, int wait);
 173
 174 #ifdef __cplusplus
 175 }
 176 #endif
 177
 178 #endif /* LTTNG_SNAPSHOT_H */