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          * Nothing to rotate, it happens on the first rotation when tracing
  44          * only in user-space and no app was started.
  45          */
  46         LTTNG_ROTATE_EMPTY = 3,
  47         /*
  48          * On error.
  49          */
  50         LTTNG_ROTATE_ERROR = 4,
  51 };
  52
  53 /*
  54  * Input parameter to the lttng_rotate_session command.
  55  * The lttng_rotate_session_attr object is opaque to the user. Use the helper
  56  * functions below to use it.
  57  */
  58 struct lttng_rotate_session_attr;
  59
  60 /*
  61  * Handle used to check the progress of a rotation.
  62  * This object is opaque to the user. Use the helper functions below to use it.
  63  */
  64 struct lttng_rotate_session_handle;
  65
  66 /*
  67  * lttng rotate session command inputs.
  68  */
  69 /*
  70  * Return a newly allocated rotate session attribute object or NULL on error.
  71  */
  72 struct lttng_rotate_session_attr *lttng_rotate_session_attr_create(void);
  73
  74 /*
  75  * Free a given rotate ssession attribute object.
  76  */
  77 void lttng_rotate_session_attr_destroy(struct lttng_rotate_session_attr *attr);
  78
  79 /*
  80  * Set the name of the session to rotate.
  81  */
  82 int lttng_rotate_session_attr_set_session_name(
  83         struct lttng_rotate_session_attr *attr, const char *session_name);
  84
  85 /*
  86  * lttng rotate session handle functions.
  87  */
  88 /*
  89  * Get the status from a handle.
  90  */
  91 enum lttng_rotate_status lttng_rotate_session_get_status(
  92                 struct lttng_rotate_session_handle *rotate_handle);
  93
  94 /*
  95  * If the rotation is complete, returns 0, allocate path and set
  96  * it to the path of the readable chunk, the caller is responsible to free it.
  97  * Otherwise return a negative value.
  98  */
  99 int lttng_rotate_session_get_output_path(
 100                 struct lttng_rotate_session_handle *rotate_handle,
 101                 char **path);
 102
 103 /*
 104  * Destroy a lttng_rotate_session handle allocated by lttng_rotate_session()
 105  */
 106 void lttng_rotate_session_handle_destroy(
 107                 struct lttng_rotate_session_handle *rotate_handle);
 108
 109 /*
 110  * Rotate the output folder of the session
 111  *
 112  * On success, handle is allocated and can be used to monitor the progress
 113  * of the rotation with lttng_rotate_session_pending(). The handle must be freed
 114  * by the caller with lttng_rotate_session_handle_destroy().
 115  *
 116  * Return 0 if the rotate action was successfully launched or a negative
 117  * LTTng error code on error.
 118  */
 119 extern int lttng_rotate_session(struct lttng_rotate_session_attr *attr,
 120                 struct lttng_rotate_session_handle **rotate_handle);
 121
 122 /*
 123  * For a given session name, this call checks if a session rotation is still in
 124  * progress or has completed.
 125  *
 126  * Return 0 if the rotation is complete, in this case, the output path can be
 127  * fetched with lttng_rotate_session_get_output_path().
 128  * Return 1 if the rotate is still pending.
 129  * Return a negative LTTng error code on error (readable with lttng_strerror).
 130  */
 131 extern int lttng_rotate_session_pending(
 132                 struct lttng_rotate_session_handle *rotate_handle);
 133
 134 #ifdef __cplusplus
 135 }
 136 #endif
 137
 138 #endif /* LTTNG_ROTATE_H */