2 * Copyright (C) 2013 David Goulet <dgoulet@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_SNAPSHOT_H
9 #define LTTNG_SNAPSHOT_H
13 #include <sys/types.h>
20 * Snapshot output object is opaque to the user. Use the helper functions below
23 struct lttng_snapshot_output
;
24 struct lttng_snapshot_output_list
;
27 * Return an newly allocated snapshot output object or NULL on error.
29 struct lttng_snapshot_output
*lttng_snapshot_output_create(void);
32 * Free a given snapshot output object.
34 void lttng_snapshot_output_destroy(struct lttng_snapshot_output
*output
);
37 * Snapshot output getter family functions. They all return the value present
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
);
53 * Snapshot output setter family functions.
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.
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
);
70 * Set the output destination to be a path on the local filesystem.
72 * The path must be absolute. It can optionally begin with `file://`.
74 * Return 0 on success or else a negative LTTNG_ERR code.
76 int lttng_snapshot_output_set_local_path(const char *path
,
77 struct lttng_snapshot_output
*output
);
80 * Set the output destination to be the network from a combined control/data
83 * `url` must start with `net://` or `net6://`.
85 * Return 0 on success or else a negative LTTNG_ERR code.
87 int lttng_snapshot_output_set_network_url(const char *url
,
88 struct lttng_snapshot_output
*output
);
91 * Set the output destination to be the network using separate URLs for control
94 * Both ctrl_url and data_url must be non-null.
96 * `ctrl_url` and `data_url` must start with `tcp://` or `tcp6://`.
98 * Return 0 on success or else a negative LTTNG_ERR code.
100 int lttng_snapshot_output_set_network_urls(
101 const char *ctrl_url
, const char *data_url
,
102 struct lttng_snapshot_output
*output
);
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
);
112 * Add an output object to a session identified by name.
114 * Return 0 on success or else a negative LTTNG_ERR code.
116 int lttng_snapshot_add_output(const char *session_name
,
117 struct lttng_snapshot_output
*output
);
120 * Delete an output object to a session identified by name.
122 * Return 0 on success or else a negative LTTNG_ERR code.
124 int lttng_snapshot_del_output(const char *session_name
,
125 struct lttng_snapshot_output
*output
);
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.
131 * Return 0 on success or else a negative LTTNG_ERR code and the list pointer
134 int lttng_snapshot_list_output(const char *session_name
,
135 struct lttng_snapshot_output_list
**list
);
138 * Return the next available snapshot output object in the given list. A list
139 * output command MUST have been done before.
141 * Return the next object on success or else NULL indicating the end of the
144 struct lttng_snapshot_output
*lttng_snapshot_output_list_get_next(
145 struct lttng_snapshot_output_list
*list
);
148 * Free an output list object.
150 void lttng_snapshot_output_list_destroy(struct lttng_snapshot_output_list
*list
);
153 * Snapshot a trace for the given session.
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.
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.
162 * Return 0 on success or else a negative LTTNG_ERR value.
164 int lttng_snapshot_record(const char *session_name
,
165 struct lttng_snapshot_output
*output
, int wait
);
171 #endif /* LTTNG_SNAPSHOT_H */