include/lttng/tracker.h

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