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