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