include/lttng/tracker.h

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