Initial import of the snapshot ABI/API in lttng-ctl
[lttng-tools.git] / include / lttng / snapshot.h
1 /*
2 * Copyright (C) 2013 - David Goulet <dgoulet@efficios.com>
3 *
4 * This library is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU Lesser General Public License, version 2.1 only,
6 * as published by the Free Software Foundation.
7 *
8 * This library is distributed in the hope that it will be useful, but WITHOUT
9 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
11 * for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this library; if not, write to the Free Software Foundation,
15 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16 */
17
18 #ifndef LTTNG_SNAPSHOT_H
19 #define LTTNG_SNAPSHOT_H
20
21 #include <limits.h>
22 #include <stdint.h>
23 #include <sys/types.h>
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 /*
30 * Snapshot output object is opaque to the user. Use the helper functions below
31 * to use them.
32 */
33 struct lttng_snapshot_output;
34 struct lttng_snapshot_output_list;
35
36 /*
37 * Return an newly allocated snapshot output object or NULL on error.
38 */
39 struct lttng_snapshot_output *lttng_snapshot_output_create(void);
40
41 /*
42 * Free a given snapshot output object.
43 */
44 void lttng_snapshot_output_destroy(struct lttng_snapshot_output *output);
45
46 /*
47 * Snapshot output getter family functions. They all return the value present
48 * in the object.
49 */
50
51 /* Return snapshot ID. */
52 uint32_t lttng_snapshot_output_get_id(struct lttng_snapshot_output *output);
53 /* Return maximum size of a snapshot. */
54 uint64_t lttng_snapshot_output_get_maxsize(struct lttng_snapshot_output *output);
55 /* Return snapshot name. */
56 const char *lttng_snapshot_output_get_name(struct lttng_snapshot_output *output);
57 /* Return snapshot control URL in a text format. */
58 const char *lttng_snapshot_output_get_ctrl_url(struct lttng_snapshot_output *output);
59 /* Return snapshot data URL in a text format. */
60 const char *lttng_snapshot_output_get_data_url(struct lttng_snapshot_output *output);
61
62 /*
63 * Snapshot output setter family functions.
64 *
65 * For every set* call, 0 is returned on success or else LTTNG_ERR_INVALID is
66 * returned indicating that at least one given parameter is invalid.
67 */
68
69 /* Set a custom ID. */
70 int lttng_snapshot_output_set_id(uint32_t id,
71 struct lttng_snapshot_output *output);
72 /* Set the maximum size. */
73 int lttng_snapshot_output_set_size(uint64_t size,
74 struct lttng_snapshot_output *output);
75 /* Set the snapshot name. */
76 int lttng_snapshot_output_set_name(const char *name,
77 struct lttng_snapshot_output *output);
78 /* Set the control URL. Local and remote URL are supported. */
79 int lttng_snapshot_output_set_ctrl_url(const char *url,
80 struct lttng_snapshot_output *output);
81 /* Set the data URL. Local and remote URL are supported. */
82 int lttng_snapshot_output_set_data_url(const char *url,
83 struct lttng_snapshot_output *output);
84
85 /*
86 * Add an output object to a session identified by name.
87 *
88 * Return 0 on success or else a negative LTTNG_ERR code.
89 */
90 int lttng_snapshot_add_output(const char *session_name,
91 struct lttng_snapshot_output *output);
92
93 /*
94 * Delete an output object to a session identified by name.
95 *
96 * Return 0 on success or else a negative LTTNG_ERR code.
97 */
98 int lttng_snapshot_del_output(const char *session_name,
99 struct lttng_snapshot_output *output);
100
101 /*
102 * List all snapshot output(s) of a session identified by name. The output list
103 * object is populated and can be iterated over with the get_next call below.
104 *
105 * Return 0 on success or else a negative LTTNG_ERR code and the list pointer
106 * is untouched.
107 */
108 int lttng_snapshot_list_output(const char *session_name,
109 struct lttng_snapshot_output_list **list);
110
111 /*
112 * Return the next available snapshot output object in the given list. A list
113 * output command MUST have been done before.
114 *
115 * Return the next object on success or else NULL indicating the end of the
116 * list.
117 */
118 struct lttng_snapshot_output *lttng_snapshot_output_list_get_next(
119 struct lttng_snapshot_output_list *list);
120
121 /*
122 * Free an output list object.
123 */
124 void lttng_snapshot_output_list_destroy(struct lttng_snapshot_output_list *list);
125
126 /*
127 * Snapshot a trace for the given session.
128 *
129 * The output object can be NULL but an add output MUST be done prior to this
130 * call. If it's not NULL, it will be used to snapshot a trace.
131 *
132 * The wait parameter is ignored for now. The snapshot record command will
133 * ALWAYS wait for the snapshot to complete before returning meaning the
134 * snapshot has been written on disk or streamed over the network to a relayd.
135 *
136 * Return 0 on success or else a negative LTTNG_ERR value.
137 */
138 int lttng_snapshot_record(const char *session_name,
139 struct lttng_snapshot_output *output, int wait);
140
141 #ifdef __cplusplus
142 }
143 #endif
144
145 #endif /* LTTNG_SNAPSHOT_H */
This page took 0.050135 seconds and 6 git commands to generate.