include/lttng/tracker.h

   1 /*
   2  * Copyright (C) 2019 - Jonathan Rajotte-Julien <jonathan.rajotte-julien@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_TRACKER_H
  19 #define LTTNG_TRACKER_H
  20
  21 #include <lttng/constant.h>
  22 #include <common/macros.h>
  23 #include <lttng/session.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 enum lttng_tracker_type {
  30         LTTNG_TRACKER_PID = 0,
  31         LTTNG_TRACKER_VPID = 1,
  32         LTTNG_TRACKER_UID = 2,
  33         LTTNG_TRACKER_GID = 3,
  34         LTTNG_TRACKER_VUID = 4,
  35         LTTNG_TRACKER_VGID = 5,
  36 };
  37
  38 enum lttng_tracker_id_type {
  39         LTTNG_ID_UNKNOWN = -1,
  40         LTTNG_ID_ALL = 0,
  41         LTTNG_ID_VALUE = 1,
  42         LTTNG_ID_STRING = 2,
  43 };
  44
  45 enum lttng_tracker_id_status {
  46         /* Invalid tracker id parameter. */
  47         LTTNG_TRACKER_ID_STATUS_INVALID = -1,
  48         LTTNG_TRACKER_ID_STATUS_OK = 0,
  49         /* Tracker id parameter is unset. */
  50         LTTNG_TRACKER_ID_STATUS_UNSET = 1,
  51 };
  52
  53 /*
  54  * A tracker id.
  55  */
  56 struct lttng_tracker_id;
  57
  58 /*
  59  * A collection of tracker id.
  60  */
  61 struct lttng_tracker_ids;
  62
  63 /*
  64  * Create a tracker id for the passed tracker type.
  65  * Users must set the tracker id using the matching API call.
  66  *
  67  * On success, the caller is responsible for calling lttng_tracker_id_destroy.
  68  * On error, return NULL.
  69  */
  70 extern struct lttng_tracker_id *lttng_tracker_id_create(void);
  71
  72 /*
  73  * Configure the tracker id using the numerical representation of the resource
  74  * to be tracked/untracked.
  75  *
  76  * If the tracker id was already configured, calling this function will replace
  77  * the previous configuration and free memory as necessary.
  78  *
  79  * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
  80  * LTTNG_TRACKER_ID_STATUS_INVALID is the passed parameter is invalid.
  81  */
  82 extern enum lttng_tracker_id_status lttng_tracker_id_set_value(
  83                 struct lttng_tracker_id *id, int value);
  84
  85 /*
  86  * Configure the tracker id using the string representation of the resource to
  87  * be tracked/untracked.
  88  *
  89  * If the tracker id was already configured, calling this function will replace
  90  * the previous configuration and free memory as necessary.
  91  *
  92  * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
  93  * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
  94  */
  95 extern enum lttng_tracker_id_status lttng_tracker_id_set_string(
  96                 struct lttng_tracker_id *id, const char *value);
  97
  98 /*
  99  * Configure the tracker id to track/untrack all resources for the tracker type.
 100  *
 101  * If the tracker id was already configured, calling this function will replace
 102  * the previous configuration and free memory as necessary.
 103  *
 104  * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
 105  * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
 106  */
 107 extern enum lttng_tracker_id_status lttng_tracker_id_set_all(
 108                 struct lttng_tracker_id *id);
 109
 110 /*
 111  * Destroy a tracker id.
 112  */
 113 extern void lttng_tracker_id_destroy(struct lttng_tracker_id *id);
 114
 115 /*
 116  * Get the type of a tracker id.
 117  */
 118 extern enum lttng_tracker_id_type lttng_tracker_id_get_type(
 119                 const struct lttng_tracker_id *id);
 120
 121 /*
 122  * Get the value of a tracker id.
 123  *
 124  * Returns LTTNG_TRACKER_ID_OK on success,
 125  * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
 126  * LTTNG_ID_VALUE,
 127  * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
 128  */
 129 extern enum lttng_tracker_id_status lttng_tracker_id_get_value(
 130                 const struct lttng_tracker_id *id, int *value);
 131
 132 /*
 133  * Get the string representation of the tracker id.
 134  *
 135  * Returns LTTNG_TRACKER_ID_OK on success,
 136  * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
 137  * LTTNG_ID_STRING,
 138  * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
 139  */
 140 extern enum lttng_tracker_id_status lttng_tracker_id_get_string(
 141                 const struct lttng_tracker_id *id, const char **value);
 142
 143 /*
 144  * Add ID to session tracker.
 145  *
 146  * tracker_type is the type of tracker.
 147  * id is the lttng_tracker_type to track.
 148  *
 149  * Returns 0 on success else a negative LTTng error code.
 150  */
 151 extern int lttng_track_id(struct lttng_handle *handle,
 152                 enum lttng_tracker_type tracker_type,
 153                 const struct lttng_tracker_id *id);
 154
 155 /*
 156  * Remove ID from session tracker.
 157  *
 158  * tracker_type is the type of tracker.
 159  * id is the lttng_tracker_type to untrack.
 160  * Returns 0 on success else a negative LTTng error code.
 161  */
 162 extern int lttng_untrack_id(struct lttng_handle *handle,
 163                 enum lttng_tracker_type tracker_type,
 164                 const struct lttng_tracker_id *id);
 165
 166 /*
 167  * List IDs of a tracker.
 168  *
 169  * On success, ids is allocated.
 170  * The ids collection must be freed by the caller with lttng_destroy_ids().
 171  *
 172  * Returns 0 on success, else a negative LTTng error code.
 173  */
 174 extern int lttng_list_tracker_ids(struct lttng_handle *handle,
 175                 enum lttng_tracker_type tracker_type,
 176                 struct lttng_tracker_ids **ids);
 177
 178 /*
 179  * Backward compatibility.
 180  * Add PID to session tracker.
 181  *
 182  * A pid argument >= 0 adds the PID to the session tracker.
 183  * A pid argument of -1 means "track all PIDs".
 184  *
 185  * Returns 0 on success else a negative LTTng error code.
 186  */
 187 extern int lttng_track_pid(struct lttng_handle *handle, int pid);
 188
 189 /*
 190  * Backward compatibility.
 191  * Remove PID from session tracker.
 192  *
 193  * A pid argument >= 0 removes the PID from the session tracker.
 194  * A pid argument of -1 means "untrack all PIDs".
 195  *
 196  * Returns 0 on success else a negative LTTng error code.
 197  */
 198 extern int lttng_untrack_pid(struct lttng_handle *handle, int pid);
 199
 200 /*
 201  * Backward compatibility
 202  * List PIDs in the tracker.
 203  *
 204  * enabled is set to whether the PID tracker is enabled.
 205  * pids is set to an allocated array of PIDs currently tracked. On
 206  * success, pids must be freed by the caller.
 207  * nr_pids is set to the number of entries contained by the pids array.
 208  *
 209  * Returns 0 on success, else a negative LTTng error code.
 210  */
 211 extern int lttng_list_tracker_pids(struct lttng_handle *handle,
 212                 int *enabled,
 213                 int32_t **pids,
 214                 size_t *nr_pids);
 215
 216 /*
 217  * Get a tracker id from the list at a given index.
 218  *
 219  * Note that the list maintains the ownership of the returned tracker id.
 220  * It must not be destroyed by the user, nor should it be held beyond the
 221  * lifetime of the tracker id list.
 222  *
 223  * Returns a tracker id, or NULL on error.
 224  */
 225 extern const struct lttng_tracker_id *lttng_tracker_ids_get_at_index(
 226                 const struct lttng_tracker_ids *ids, unsigned int index);
 227
 228 /*
 229  * Get the number of tracker id in a tracker id list.
 230  *
 231  * Return LTTNG_TRACKER_ID_STATUS on sucess,
 232  * LTTNG_TRACKER_ID_STATUS_INVALID when passed invalid parameters.
 233  */
 234 extern enum lttng_tracker_id_status lttng_tracker_ids_get_count(
 235                 const struct lttng_tracker_ids *ids, unsigned int *count);
 236
 237 /*
 238  * Destroy a tracker id list.
 239  */
 240 extern void lttng_tracker_ids_destroy(struct lttng_tracker_ids *ids);
 241
 242 #ifdef __cplusplus
 243 }
 244 #endif
 245
 246 #endif /* LTTNG_TRACKER_H */