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