2 * Copyright (C) 2017 - Julien Desfossez <jdesfossez@efficios.com>
3 * Copyright (C) 2018 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
5 * This library is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU Lesser General Public License, version 2.1 only,
7 * as published by the Free Software Foundation.
9 * This library is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library; if not, write to the Free Software Foundation,
16 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 #ifndef LTTNG_ROTATION_H
20 #define LTTNG_ROTATION_H
29 * Return codes for lttng_rotation_handle_get_state()
31 enum lttng_rotation_state
{
33 * Rotation is ongoing, but has not been completed yet.
35 LTTNG_ROTATION_STATE_ONGOING
= 0,
37 * Rotation has been completed and the resulting chunk
38 * can now safely be read.
40 LTTNG_ROTATION_STATE_COMPLETED
= 1,
42 * The rotation has expired.
44 * The information associated with a given rotation is eventually
45 * purged by the session daemon. In such a case, the attributes of
46 * the rotation, such as its path, may no longer be available.
48 * Note that this state does not guarantee the the rotation was
49 * completed successfully.
51 LTTNG_ROTATION_STATE_EXPIRED
= 2,
53 * The rotation could not be completed due to an error.
55 LTTNG_ROTATION_STATE_ERROR
= 3,
58 enum lttng_rotation_status
{
59 LTTNG_ROTATION_STATUS_OK
= 0,
60 /* Information not available. */
61 LTTNG_ROTATION_STATUS_UNAVAILABLE
= 1,
63 LTTNG_ROTATION_STATUS_ERROR
= -1,
64 /* Invalid parameters provided. */
65 LTTNG_ROTATION_STATUS_INVALID
= -2,
69 * Input parameter to the lttng_rotate_session command.
71 * An immediate rotation is performed as soon as possible by the tracers.
73 * The lttng_rotation_immediate_attr object is opaque to the user. Use the
74 * helper functions below to access it.
76 struct lttng_rotation_immediate_attr
;
79 * Handle used to represent a specific rotation.
81 * This object is opaque to the user. Use the helper functions below to access
84 struct lttng_rotation_handle
;
87 * Return a newly allocated immediate session rotation descriptor object or NULL
90 extern struct lttng_rotation_immediate_attr
*
91 lttng_rotation_immediate_attr_create(void);
94 * Destroy a given immediate session rotation descriptor object.
96 extern void lttng_rotation_immediate_attr_destroy(
97 struct lttng_rotation_immediate_attr
*attr
);
100 * Set the name of the session to rotate immediately.
102 * The session_name parameter is copied to the immediate session rotation
105 extern enum lttng_rotation_status
lttng_rotation_immediate_attr_set_session_name(
106 struct lttng_rotation_immediate_attr
*attr
,
107 const char *session_name
);
110 * Get the current state of the rotation referenced by the handle.
112 * This will issue a request to the session daemon on every call. Hence,
113 * the result of this call may change over time.
115 extern enum lttng_rotation_status
lttng_rotation_handle_get_state(
116 struct lttng_rotation_handle
*rotation_handle
,
117 enum lttng_rotation_state
*rotation_state
);
120 * Get the location of the rotation's resulting archive.
122 * The rotation must be completed in order for this call to succeed.
123 * The path returned is owned by the rotation handle.
125 * Note that path will not be set in case of error, or if the session
126 * rotation has expired.
128 * FIXME: Return an lttng_location object instead of a path.
130 extern enum lttng_rotation_status
lttng_rotation_handle_get_completed_archive_location(
131 struct lttng_rotation_handle
*rotation_handle
,
135 * Destroy an lttng_rotate_session handle.
137 extern void lttng_rotation_handle_destroy(
138 struct lttng_rotation_handle
*rotation_handle
);
141 * Rotate the output folder of the session
143 * On success, handle is allocated and can be used to monitor the progress
144 * of the rotation with lttng_rotation_get_state(). The handle must be freed
145 * by the caller with lttng_rotation_handle_destroy().
147 * Return 0 if the rotate action was successfully launched or a negative
148 * LTTng error code on error.
150 extern int lttng_rotate_session(struct lttng_rotation_immediate_attr
*attr
,
151 struct lttng_rotation_handle
**rotation_handle
);
157 #endif /* LTTNG_ROTATION_H */