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