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 */