include/lttng/rotate.h

   1 /*
   2  * Copyright (C) 2017 - Julien Desfossez <jdesfossez@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_ROTATE_H
  19 #define LTTNG_ROTATE_H
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 /*
  26  * Return codes for lttng_rotate_session_get_output_path.
  27  */
  28 enum lttng_rotate_status {
  29         /*
  30          * After starting a rotation.
  31          */
  32         LTTNG_ROTATE_STARTED = 0,
  33         /*
  34          * When the rotation is complete.
  35          */
  36         LTTNG_ROTATE_COMPLETED = 1,
  37         /*
  38          * If the handle does not match the last rotate command, we cannot
  39          * retrieve the path for the chunk.
  40          */
  41         LTTNG_ROTATE_EXPIRED = 2,
  42         /*
  43          * On error.
  44          */
  45         LTTNG_ROTATE_ERROR = 3,
  46 };
  47
  48 /*
  49  * Input parameter to the lttng_rotate_session command.
  50  * The lttng_rotate_session_attr object is opaque to the user. Use the helper
  51  * functions below to use it.
  52  */
  53 struct lttng_rotate_session_attr;
  54
  55 /*
  56  * Handle used to check the progress of a rotation.
  57  * This object is opaque to the user. Use the helper functions below to use it.
  58  */
  59 struct lttng_rotate_session_handle;
  60
  61 /*
  62  * lttng rotate session command inputs.
  63  */
  64 /*
  65  * Return a newly allocated rotate session attribute object or NULL on error.
  66  */
  67 struct lttng_rotate_session_attr *lttng_rotate_session_attr_create(void);
  68
  69 /*
  70  * Free a given rotate ssession attribute object.
  71  */
  72 void lttng_rotate_session_attr_destroy(struct lttng_rotate_session_attr *attr);
  73
  74 /*
  75  * Set the name of the session to rotate.
  76  */
  77 int lttng_rotate_session_attr_set_session_name(
  78         struct lttng_rotate_session_attr *attr, const char *session_name);
  79
  80 /*
  81  * lttng rotate session handle functions.
  82  */
  83 /*
  84  * Get the status from a handle.
  85  */
  86 enum lttng_rotate_status lttng_rotate_session_get_status(
  87                 struct lttng_rotate_session_handle *rotate_handle);
  88
  89 /*
  90  * If the rotation is complete, returns 0, allocate path and set
  91  * it to the path of the readable chunk, the caller is responsible to free it.
  92  * Otherwise return a negative value.
  93  */
  94 int lttng_rotate_session_get_output_path(
  95                 struct lttng_rotate_session_handle *rotate_handle,
  96                 char **path);
  97
  98 /*
  99  * Destroy a lttng_rotate_session handle allocated by lttng_rotate_session()
 100  */
 101 void lttng_rotate_session_handle_destroy(
 102                 struct lttng_rotate_session_handle *rotate_handle);
 103
 104 /*
 105  * Rotate the output folder of the session
 106  *
 107  * On success, handle is allocated and can be used to monitor the progress
 108  * of the rotation with lttng_rotate_session_pending(). The handle must be freed
 109  * by the caller with lttng_rotate_session_handle_destroy().
 110  *
 111  * Return 0 if the rotate action was successfully launched or a negative
 112  * LTTng error code on error.
 113  */
 114 extern int lttng_rotate_session(struct lttng_rotate_session_attr *attr,
 115                 struct lttng_rotate_session_handle **rotate_handle);
 116
 117 /*
 118  * For a given session name, this call checks if a session rotation is still in
 119  * progress or has completed.
 120  *
 121  * Return 0 if the rotation is complete, in this case, the output path can be
 122  * fetched with lttng_rotate_session_get_output_path().
 123  * Return 1 if the rotate is still pending.
 124  * Return a negative LTTng error code on error (readable with lttng_strerror).
 125  */
 126 extern int lttng_rotate_session_pending(
 127                 struct lttng_rotate_session_handle *rotate_handle);
 128
 129 #ifdef __cplusplus
 130 }
 131 #endif
 132
 133 #endif /* LTTNG_ROTATE_H */