SoW-2020-0002: Trace Hit Counters: trigger error reporting integration
[lttng-tools.git] / include / lttng / snapshot.h
CommitLineData
da3c9ec1 1/*
ab5be9fa 2 * Copyright (C) 2013 David Goulet <dgoulet@efficios.com>
da3c9ec1 3 *
ab5be9fa 4 * SPDX-License-Identifier: LGPL-2.1-only
da3c9ec1 5 *
da3c9ec1
DG
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
16extern "C" {
17#endif
18
19/*
20 * Snapshot output object is opaque to the user. Use the helper functions below
21 * to use them.
22 */
23struct lttng_snapshot_output;
24struct lttng_snapshot_output_list;
25
26/*
27 * Return an newly allocated snapshot output object or NULL on error.
28 */
29struct lttng_snapshot_output *lttng_snapshot_output_create(void);
30
31/*
32 * Free a given snapshot output object.
33 */
34void 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. */
2463b787 42uint32_t lttng_snapshot_output_get_id(const struct lttng_snapshot_output *output);
da3c9ec1 43/* Return maximum size of a snapshot. */
2463b787 44uint64_t lttng_snapshot_output_get_maxsize(const struct lttng_snapshot_output *output);
da3c9ec1 45/* Return snapshot name. */
2463b787 46const char *lttng_snapshot_output_get_name(const struct lttng_snapshot_output *output);
da3c9ec1 47/* Return snapshot control URL in a text format. */
2463b787 48const char *lttng_snapshot_output_get_ctrl_url(const struct lttng_snapshot_output *output);
da3c9ec1 49/* Return snapshot data URL in a text format. */
2463b787 50const char *lttng_snapshot_output_get_data_url(const struct lttng_snapshot_output *output);
da3c9ec1
DG
51
52/*
53 * Snapshot output setter family functions.
54 *
eef7781f 55 * For every set* call, 0 is returned on success or else -LTTNG_ERR_INVALID is
da3c9ec1
DG
56 * returned indicating that at least one given parameter is invalid.
57 */
58
59/* Set a custom ID. */
60int lttng_snapshot_output_set_id(uint32_t id,
61 struct lttng_snapshot_output *output);
62/* Set the maximum size. */
63int lttng_snapshot_output_set_size(uint64_t size,
64 struct lttng_snapshot_output *output);
65/* Set the snapshot name. */
66int lttng_snapshot_output_set_name(const char *name,
67 struct lttng_snapshot_output *output);
b30fa191
JR
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 */
76int 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 */
87int 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 */
100int lttng_snapshot_output_set_network_urls(
101 const char *ctrl_url, const char *data_url,
102 struct lttng_snapshot_output *output);
103
da3c9ec1
DG
104/* Set the control URL. Local and remote URL are supported. */
105int 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. */
108int 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 */
116int 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 */
124int 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 */
134int 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 */
144struct 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 */
150void 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 */
164int 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 */
This page took 0.084872 seconds and 5 git commands to generate.