Commit | Line | Data |
---|---|---|
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 | ||
4bd69c5f | 11 | #include <lttng/lttng-export.h> |
28f23191 JG |
12 | |
13 | #include <limits.h> | |
da3c9ec1 DG |
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 | */ | |
4bd69c5f | 31 | LTTNG_EXPORT extern struct lttng_snapshot_output *lttng_snapshot_output_create(void); |
da3c9ec1 DG |
32 | |
33 | /* | |
34 | * Free a given snapshot output object. | |
35 | */ | |
4bd69c5f | 36 | LTTNG_EXPORT extern void lttng_snapshot_output_destroy(struct lttng_snapshot_output *output); |
da3c9ec1 DG |
37 | |
38 | /* | |
39 | * Snapshot output getter family functions. They all return the value present | |
40 | * in the object. | |
41 | */ | |
42 | ||
43 | /* Return snapshot ID. */ | |
28f23191 JG |
44 | LTTNG_EXPORT extern uint32_t |
45 | lttng_snapshot_output_get_id(const struct lttng_snapshot_output *output); | |
da3c9ec1 | 46 | /* Return maximum size of a snapshot. */ |
28f23191 JG |
47 | LTTNG_EXPORT extern uint64_t |
48 | lttng_snapshot_output_get_maxsize(const struct lttng_snapshot_output *output); | |
da3c9ec1 | 49 | /* Return snapshot name. */ |
28f23191 JG |
50 | LTTNG_EXPORT extern const char * |
51 | lttng_snapshot_output_get_name(const struct lttng_snapshot_output *output); | |
da3c9ec1 | 52 | /* Return snapshot control URL in a text format. */ |
28f23191 JG |
53 | LTTNG_EXPORT extern const char * |
54 | lttng_snapshot_output_get_ctrl_url(const struct lttng_snapshot_output *output); | |
da3c9ec1 | 55 | /* Return snapshot data URL in a text format. */ |
28f23191 JG |
56 | LTTNG_EXPORT extern const char * |
57 | lttng_snapshot_output_get_data_url(const struct lttng_snapshot_output *output); | |
da3c9ec1 DG |
58 | |
59 | /* | |
60 | * Snapshot output setter family functions. | |
61 | * | |
eef7781f | 62 | * For every set* call, 0 is returned on success or else -LTTNG_ERR_INVALID is |
da3c9ec1 DG |
63 | * returned indicating that at least one given parameter is invalid. |
64 | */ | |
65 | ||
66 | /* Set a custom ID. */ | |
4bd69c5f | 67 | LTTNG_EXPORT extern int lttng_snapshot_output_set_id(uint32_t id, |
28f23191 | 68 | struct lttng_snapshot_output *output); |
da3c9ec1 | 69 | /* Set the maximum size. */ |
4bd69c5f | 70 | LTTNG_EXPORT extern int lttng_snapshot_output_set_size(uint64_t size, |
28f23191 | 71 | struct lttng_snapshot_output *output); |
da3c9ec1 | 72 | /* Set the snapshot name. */ |
4bd69c5f | 73 | LTTNG_EXPORT extern int lttng_snapshot_output_set_name(const char *name, |
28f23191 | 74 | struct lttng_snapshot_output *output); |
b30fa191 JR |
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 | */ | |
4bd69c5f | 83 | LTTNG_EXPORT extern int lttng_snapshot_output_set_local_path(const char *path, |
28f23191 | 84 | struct lttng_snapshot_output *output); |
b30fa191 JR |
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 | */ | |
4bd69c5f | 94 | LTTNG_EXPORT extern int lttng_snapshot_output_set_network_url(const char *url, |
28f23191 | 95 | struct lttng_snapshot_output *output); |
b30fa191 JR |
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 | */ | |
4bd69c5f | 107 | LTTNG_EXPORT extern int lttng_snapshot_output_set_network_urls( |
28f23191 | 108 | const char *ctrl_url, const char *data_url, struct lttng_snapshot_output *output); |
b30fa191 | 109 | |
da3c9ec1 | 110 | /* Set the control URL. Local and remote URL are supported. */ |
4bd69c5f | 111 | LTTNG_EXPORT extern int lttng_snapshot_output_set_ctrl_url(const char *url, |
28f23191 | 112 | struct lttng_snapshot_output *output); |
da3c9ec1 | 113 | /* Set the data URL. Local and remote URL are supported. */ |
4bd69c5f | 114 | LTTNG_EXPORT extern int lttng_snapshot_output_set_data_url(const char *url, |
28f23191 | 115 | struct lttng_snapshot_output *output); |
da3c9ec1 DG |
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 | */ | |
4bd69c5f | 122 | LTTNG_EXPORT extern int lttng_snapshot_add_output(const char *session_name, |
28f23191 | 123 | struct lttng_snapshot_output *output); |
da3c9ec1 DG |
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 | */ | |
4bd69c5f | 130 | LTTNG_EXPORT extern int lttng_snapshot_del_output(const char *session_name, |
28f23191 | 131 | struct lttng_snapshot_output *output); |
da3c9ec1 DG |
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 | */ | |
4bd69c5f | 140 | LTTNG_EXPORT extern int lttng_snapshot_list_output(const char *session_name, |
28f23191 | 141 | struct lttng_snapshot_output_list **list); |
da3c9ec1 DG |
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 | */ | |
28f23191 JG |
150 | LTTNG_EXPORT extern struct lttng_snapshot_output * |
151 | lttng_snapshot_output_list_get_next(struct lttng_snapshot_output_list *list); | |
da3c9ec1 DG |
152 | |
153 | /* | |
154 | * Free an output list object. | |
155 | */ | |
28f23191 JG |
156 | LTTNG_EXPORT extern void |
157 | lttng_snapshot_output_list_destroy(struct lttng_snapshot_output_list *list); | |
da3c9ec1 DG |
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 | */ | |
28f23191 JG |
171 | LTTNG_EXPORT extern int |
172 | lttng_snapshot_record(const char *session_name, struct lttng_snapshot_output *output, int wait); | |
da3c9ec1 DG |
173 | |
174 | #ifdef __cplusplus | |
175 | } | |
176 | #endif | |
177 | ||
178 | #endif /* LTTNG_SNAPSHOT_H */ |