include/lttng/tracker.h

   1 /*
   2  * Copyright (C) 2019 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
   3  * Copyright (C) 2020 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-only
   6  *
   7  */
   8
   9 #ifndef LTTNG_TRACKER_H
  10 #define LTTNG_TRACKER_H
  11
  12 #include <lttng/constant.h>
  13 #include <lttng/domain.h>
  14 #include <lttng/lttng-error.h>
  15 #include <lttng/lttng-export.h>
  16 #include <lttng/session.h>
  17
  18 #include <sys/types.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /*
  25  * Process attribute tracked by a tracker.
  26  */
  27 enum lttng_process_attr {
  28         /* Kernel space domain only. */
  29         LTTNG_PROCESS_ATTR_PROCESS_ID = 0,
  30         /* Kernel and user space domains. */
  31         LTTNG_PROCESS_ATTR_VIRTUAL_PROCESS_ID = 1,
  32         /* Kernel space domain only. */
  33         LTTNG_PROCESS_ATTR_USER_ID = 2,
  34         /* Kernel and user space domains. */
  35         LTTNG_PROCESS_ATTR_VIRTUAL_USER_ID = 3,
  36         /* Kernel space domain only. */
  37         LTTNG_PROCESS_ATTR_GROUP_ID = 4,
  38         /* Kernel and user space domains. */
  39         LTTNG_PROCESS_ATTR_VIRTUAL_GROUP_ID = 5,
  40 };
  41
  42 /*
  43  * Tracking (filtering) policy of a process attribute tracker.
  44  */
  45 enum lttng_tracking_policy {
  46         /*
  47          * Track all possible process attribute value of a given type
  48          * (i.e. no filtering).
  49          * This is the default state of a process attribute tracker.
  50          */
  51         LTTNG_TRACKING_POLICY_INCLUDE_ALL = 0,
  52         /* Exclude all possible process attribute values of a given type. */
  53         LTTNG_TRACKING_POLICY_EXCLUDE_ALL = 1,
  54         /* Track a set of specific process attribute values. */
  55         LTTNG_TRACKING_POLICY_INCLUDE_SET = 2,
  56 };
  57
  58 /*
  59  * Type of a process attribute value.
  60  *
  61  * This allows the use of the matching accessor given the type of a value.
  62  */
  63 enum lttng_process_attr_value_type {
  64         LTTNG_PROCESS_ATTR_VALUE_TYPE_INVALID = -1,
  65         LTTNG_PROCESS_ATTR_VALUE_TYPE_PID = 0,
  66         LTTNG_PROCESS_ATTR_VALUE_TYPE_UID = 1,
  67         LTTNG_PROCESS_ATTR_VALUE_TYPE_USER_NAME = 2,
  68         LTTNG_PROCESS_ATTR_VALUE_TYPE_GID = 3,
  69         LTTNG_PROCESS_ATTR_VALUE_TYPE_GROUP_NAME = 4,
  70 };
  71
  72 enum lttng_process_attr_tracker_handle_status {
  73         LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_GROUP_NOT_FOUND = -7,
  74         LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_USER_NOT_FOUND = -6,
  75         LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID_TRACKING_POLICY = -5,
  76         LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_SESSION_DOES_NOT_EXIST = -4,
  77         LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_ERROR = -3,
  78         LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_COMMUNICATION_ERROR = -2,
  79         LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID = -1,
  80         LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK = 0,
  81         LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_EXISTS = 1,
  82         LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_MISSING = 2,
  83 };
  84
  85 enum lttng_process_attr_values_status {
  86         LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE = -2,
  87         LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID = -1,
  88         LTTNG_PROCESS_ATTR_VALUES_STATUS_OK = 0,
  89 };
  90
  91 /*
  92  * A process attribute tracker handle.
  93  *
  94  * A process attribute tracker is an _inclusion set_ of process
  95  * attribute values. Tracked processes are allowed to emit events,
  96  * provided those events are targeted by enabled event rules.
  97  *
  98  * An LTTng session is created with a number of process attribute
  99  * trackers by default. The process attributes that can be tracked vary by
 100  * domain (see enum lttng_process_attr).
 101  *
 102  * Trackers are per-domain (user and kernel space) and allow the filtering
 103  * of events based on a process's attributes.
 104  */
 105 struct lttng_process_attr_tracker_handle;
 106
 107 /* A set of process attribute values. */
 108 struct lttng_process_attr_values;
 109
 110 /*
 111  * Get a handle to one of the process attribute trackers of a session's domain.
 112  *
 113  * Returns LTTNG_OK and a process attribute tracker handle on success,
 114  * or an lttng_error_code on error.
 115  *
 116  * The tracker's ownership is transfered to the caller. Use
 117  * lttng_process_attr_tracker_handle_destroy() to dispose of it.
 118  */
 119 LTTNG_EXPORT extern enum lttng_error_code
 120 lttng_session_get_tracker_handle(const char *session_name,
 121                                  enum lttng_domain_type domain,
 122                                  enum lttng_process_attr process_attr,
 123                                  struct lttng_process_attr_tracker_handle **out_tracker_handle);
 124
 125 /*
 126  * Destroy a process attribute tracker handle.
 127  */
 128 LTTNG_EXPORT extern void
 129 lttng_process_attr_tracker_handle_destroy(struct lttng_process_attr_tracker_handle *tracker_handle);
 130
 131 /*
 132  * Get the tracking policy of a process attribute tracker.
 133  *
 134  * Returns the LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK and the tracking
 135  * policy of a process attribute tracker on success,
 136  * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID on error.
 137  */
 138 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 139 lttng_process_attr_tracker_handle_get_tracking_policy(
 140         const struct lttng_process_attr_tracker_handle *tracker_handle,
 141         enum lttng_tracking_policy *policy);
 142
 143 /*
 144  * Set the tracking policy of a process attribute tracker.
 145  *
 146  * Setting the tracking policy to the current tracking policy has no effect.
 147  *
 148  * Returns the LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK on success,
 149  * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID on error.
 150  */
 151 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 152 lttng_process_attr_tracker_handle_set_tracking_policy(
 153         const struct lttng_process_attr_tracker_handle *tracker_handle,
 154         enum lttng_tracking_policy policy);
 155
 156 /*
 157  * Add a numerical PID to the process ID process attribute tracker inclusion
 158  * set.
 159  *
 160  * Returns LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK on success,
 161  * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_EXISTS if it was already
 162  * present in the inclusion set, and
 163  * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID if an invalid tracker
 164  * argument was provided.
 165  */
 166 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 167 lttng_process_attr_process_id_tracker_handle_add_pid(
 168         const struct lttng_process_attr_tracker_handle *process_id_tracker, pid_t pid);
 169
 170 /*
 171  * Remove a numerical PID from the process ID process attribute tracker include
 172  * set.
 173  *
 174  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 175  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 176  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 177  * an invalid tracker argument was provided.
 178  */
 179 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 180 lttng_process_attr_process_id_tracker_handle_remove_pid(
 181         const struct lttng_process_attr_tracker_handle *process_id_tracker, pid_t pid);
 182
 183 /*
 184  * Add a numerical PID to the virtual process ID process attribute tracker
 185  * inclusion set.
 186  *
 187  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 188  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 189  * present in the inclusion set, and
 190  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 191  * argument was provided.
 192  */
 193 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 194 lttng_process_attr_virtual_process_id_tracker_handle_add_pid(
 195         const struct lttng_process_attr_tracker_handle *process_id_tracker, pid_t vpid);
 196
 197 /*
 198  * Remove a numerical PID from the virtual process ID process attribute tracker
 199  * inclusion set.
 200  *
 201  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 202  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 203  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 204  * an invalid tracker argument was provided.
 205  */
 206 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 207 lttng_process_attr_virtual_process_id_tracker_handle_remove_pid(
 208         const struct lttng_process_attr_tracker_handle *process_id_tracker, pid_t vpid);
 209
 210 /*
 211  * Add a numerical UID to the user ID process attribute tracker inclusion set.
 212  *
 213  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 214  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 215  * present in the inclusion set, and
 216  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 217  * argument was provided.
 218  */
 219 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 220 lttng_process_attr_user_id_tracker_handle_add_uid(
 221         const struct lttng_process_attr_tracker_handle *user_id_tracker, uid_t uid);
 222
 223 /*
 224  * Remove a numerical UID from the user ID process attribute tracker include
 225  * set.
 226  *
 227  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 228  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 229  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 230  * an invalid tracker argument was provided.
 231  */
 232 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 233 lttng_process_attr_user_id_tracker_handle_remove_uid(
 234         const struct lttng_process_attr_tracker_handle *user_id_tracker, uid_t uid);
 235
 236 /*
 237  * Add a user name to the user ID process attribute tracker inclusion set.
 238  *
 239  * The user name resolution is performed by the session daemon on addition to
 240  * the user ID inclusion set.
 241  *
 242  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 243  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 244  * present in the inclusion set, and
 245  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 246  * argument was provided.
 247  */
 248 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 249 lttng_process_attr_user_id_tracker_handle_add_user_name(
 250         const struct lttng_process_attr_tracker_handle *user_id_tracker, const char *user_name);
 251
 252 /*
 253  * Remove a user name from the user ID process attribute tracker include
 254  * set.
 255  *
 256  * No name resolution is performed; the user name will be matched against the
 257  * names in the inclusion set.
 258  *
 259  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 260  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 261  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 262  * an invalid tracker argument was provided.
 263  */
 264 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 265 lttng_process_attr_user_id_tracker_handle_remove_user_name(
 266         const struct lttng_process_attr_tracker_handle *user_id_tracker, const char *user_name);
 267
 268 /*
 269  * Add a numerical UID to the virtual user ID process attribute tracker
 270  * inclusion set.
 271  *
 272  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 273  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 274  * present in the inclusion set, and
 275  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 276  * argument was provided.
 277  */
 278 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 279 lttng_process_attr_virtual_user_id_tracker_handle_add_uid(
 280         const struct lttng_process_attr_tracker_handle *user_id_tracker, uid_t vuid);
 281
 282 /*
 283  * Remove a numerical UID from the virtual user ID process attribute tracker
 284  * inclusion set.
 285  *
 286  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 287  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 288  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 289  * an invalid tracker argument was provided.
 290  */
 291 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 292 lttng_process_attr_virtual_user_id_tracker_handle_remove_uid(
 293         const struct lttng_process_attr_tracker_handle *user_id_tracker, uid_t vuid);
 294
 295 /*
 296  * Add a user name to the virtual user ID process attribute tracker include
 297  * set.
 298  *
 299  * The user name resolution is performed by the session daemon on addition to
 300  * the virtual user ID inclusion set.
 301  *
 302  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 303  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 304  * present in the inclusion set, and
 305  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 306  * argument was provided.
 307  */
 308 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 309 lttng_process_attr_virtual_user_id_tracker_handle_add_user_name(
 310         const struct lttng_process_attr_tracker_handle *user_id_tracker,
 311         const char *virtual_user_name);
 312
 313 /*
 314  * Remove a user name from the virtual user ID process attribute tracker
 315  * inclusion set.
 316  *
 317  * No name resolution is performed; the user name will be matched against the
 318  * names in the inclusion set.
 319  *
 320  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 321  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 322  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 323  * an invalid tracker argument was provided.
 324  */
 325 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 326 lttng_process_attr_virtual_user_id_tracker_handle_remove_user_name(
 327         const struct lttng_process_attr_tracker_handle *user_id_tracker,
 328         const char *virtual_user_name);
 329
 330 /*
 331  * Add a numerical GID to the group ID process attribute tracker inclusion set.
 332  *
 333  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 334  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 335  * present in the inclusion set, and
 336  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 337  * argument was provided.
 338  */
 339 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 340 lttng_process_attr_group_id_tracker_handle_add_gid(
 341         const struct lttng_process_attr_tracker_handle *group_id_tracker, gid_t gid);
 342
 343 /*
 344  * Remove a numerical GID from the group ID process attribute tracker include
 345  * set.
 346  *
 347  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 348  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 349  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 350  * an invalid tracker argument was provided.
 351  */
 352 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 353 lttng_process_attr_group_id_tracker_handle_remove_gid(
 354         const struct lttng_process_attr_tracker_handle *group_id_tracker, gid_t gid);
 355
 356 /*
 357  * Add a group name to the group ID process attribute tracker inclusion set.
 358  *
 359  * The group name resolution is performed by the session daemon on addition to
 360  * the group ID inclusion set.
 361  *
 362  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 363  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 364  * present in the inclusion set, and
 365  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 366  * argument was provided.
 367  */
 368 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 369 lttng_process_attr_group_id_tracker_handle_add_group_name(
 370         const struct lttng_process_attr_tracker_handle *group_id_tracker, const char *group_name);
 371
 372 /*
 373  * Remove a group name from the group ID process attribute tracker include
 374  * set.
 375  *
 376  * No name resolution is performed; the user name will be matched against the
 377  * names in the inclusion set.
 378  *
 379  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 380  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 381  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 382  * an invalid tracker argument was provided.
 383  */
 384 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 385 lttng_process_attr_group_id_tracker_handle_remove_group_name(
 386         const struct lttng_process_attr_tracker_handle *group_id_tracker, const char *group_name);
 387
 388 /*
 389  * Add a numerical GID to the virtual group ID process attribute tracker
 390  * inclusion set.
 391  *
 392  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 393  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 394  * present in the inclusion set, and
 395  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 396  * argument was provided.
 397  */
 398 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 399 lttng_process_attr_virtual_group_id_tracker_handle_add_gid(
 400         const struct lttng_process_attr_tracker_handle *group_id_tracker, gid_t vgid);
 401
 402 /*
 403  * Remove a numerical GID from the virtual group ID process attribute tracker
 404  * inclusion set.
 405  *
 406  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 407  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 408  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 409  * an invalid tracker argument was provided.
 410  */
 411 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 412 lttng_process_attr_virtual_group_id_tracker_handle_remove_gid(
 413         const struct lttng_process_attr_tracker_handle *group_id_tracker, gid_t vgid);
 414
 415 /*
 416  * Add a group name to the virtual group ID process attribute tracker include
 417  * set.
 418  *
 419  * The group name resolution is performed by the session daemon on addition to
 420  * the virtual group ID inclusion set.
 421  *
 422  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 423  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 424  * present in the inclusion set, and
 425  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 426  * argument was provided.
 427  */
 428 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 429 lttng_process_attr_virtual_group_id_tracker_handle_add_group_name(
 430         const struct lttng_process_attr_tracker_handle *group_id_tracker,
 431         const char *virtual_group_name);
 432
 433 /*
 434  * Remove a group name from the virtual group ID process attribute tracker
 435  * inclusion set.
 436  *
 437  * No name resolution is performed; the user name will be matched against the
 438  * names in the inclusion set.
 439  *
 440  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 441  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 442  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 443  * an invalid tracker argument was provided.
 444  */
 445 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 446 lttng_process_attr_virtual_group_id_tracker_handle_remove_group_name(
 447         const struct lttng_process_attr_tracker_handle *group_id_tracker,
 448         const char *virtual_group_name);
 449
 450 /*
 451  * Get the process attribute values that are part of a tracker's inclusion set.
 452  *
 453  * The values returned are a snapshot of the values that are part of the
 454  * tracker's inclusion set at the moment of the invocation; it is not updated
 455  * as entries are added or removed.
 456  *
 457  * The values remain valid until the tracker is destroyed.
 458  *
 459  * Returns LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK on success,
 460  * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID if the tracker's policy is
 461  * not LTTNG_POLICY_INCLUDE_SET.
 462  */
 463 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 464 lttng_process_attr_tracker_handle_get_inclusion_set(
 465         struct lttng_process_attr_tracker_handle *tracker_handle,
 466         const struct lttng_process_attr_values **values);
 467
 468 /*
 469  * Get the count of values within a set of process attribute values.
 470  *
 471  * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
 472  * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID if an invalid argument is provided.
 473  */
 474 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 475 lttng_process_attr_values_get_count(const struct lttng_process_attr_values *values,
 476                                     unsigned int *count);
 477
 478 /*
 479  * Get the type of a process attribute value at a given index.
 480  *
 481  * Returns a process attribute value type on success,
 482  * LTTNG_PROCESS_ATTR_VALUE_TYPE_INVALID if an invalid argument is provided.
 483  */
 484 LTTNG_EXPORT extern enum lttng_process_attr_value_type
 485 lttng_process_attr_values_get_type_at_index(const struct lttng_process_attr_values *values,
 486                                             unsigned int index);
 487
 488 /*
 489  * Get a process ID process attribute value.
 490  *
 491  * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
 492  * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
 493  * is not a process ID.
 494  */
 495 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 496 lttng_process_attr_values_get_pid_at_index(const struct lttng_process_attr_values *values,
 497                                            unsigned int index,
 498                                            pid_t *pid);
 499
 500 /*
 501  * Get a user ID process attribute value.
 502  *
 503  * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
 504  * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
 505  * is not a user ID.
 506  */
 507 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 508 lttng_process_attr_values_get_uid_at_index(const struct lttng_process_attr_values *values,
 509                                            unsigned int index,
 510                                            uid_t *uid);
 511
 512 /*
 513  * Get a user name process attribute value.
 514  *
 515  * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
 516  * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
 517  * is not a user name.
 518  */
 519 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 520 lttng_process_attr_values_get_user_name_at_index(const struct lttng_process_attr_values *values,
 521                                                  unsigned int index,
 522                                                  const char **user_name);
 523
 524 /*
 525  * Get a group ID process attribute value.
 526  *
 527  * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
 528  * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
 529  * is not a group ID.
 530  */
 531 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 532 lttng_process_attr_values_get_gid_at_index(const struct lttng_process_attr_values *values,
 533                                            unsigned int index,
 534                                            gid_t *gid);
 535
 536 /*
 537  * Get a group name process attribute value.
 538  *
 539  * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
 540  * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
 541  * is not a group name.
 542  */
 543 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 544 lttng_process_attr_values_get_group_name_at_index(const struct lttng_process_attr_values *values,
 545                                                   unsigned int index,
 546                                                   const char **group_name);
 547
 548 /* The following entry points are deprecated. */
 549
 550 /*
 551  * Deprecated: see `lttng_process_attr_tracker_handle_get_inclusion_set` and
 552  * `lttng_process_tracker_handle_get_tracking_policy`.
 553  *
 554  * List tracked PIDs.
 555  *
 556  * `enabled` indicates whether or not the PID tracker is enabled.
 557  *
 558  * `pids` is set to an allocated array of PIDs currently being tracked. On
 559  * success, `pids` must be freed by the caller.
 560  *
 561  * `nr_pids` is set to the number of entries contained in the `pids` array.
 562  *
 563  * Returns 0 on success, else a negative LTTng error code.
 564  */
 565 LTTNG_EXPORT extern int
 566 lttng_list_tracker_pids(struct lttng_handle *handle, int *enabled, int32_t **pids, size_t *nr_pids);
 567
 568 /*
 569  * Deprecated: see `lttng_process_attr_process_id_tracker_handle_add_pid`.
 570  *
 571  * Add PID to session tracker.
 572  *
 573  * A pid argument >= 0 adds the PID to the session's PID tracker.
 574  * A pid argument of -1 means "track all PIDs".
 575  *
 576  * Note on 'real' PIDs vs 'virtual' VPIDs:
 577  *   - With the user space domain specified, this function will add a VPID
 578  *     value to the virtual process ID process attribute tracker's inclusion
 579  *     set.
 580  *   - With the kernel space domain specified, this function will add a PID
 581  *     value to the process ID process attribute tracker's inclusion set.
 582  *
 583  * Returns 0 on success, else a negative LTTng error code.
 584  */
 585 LTTNG_EXPORT extern int lttng_track_pid(struct lttng_handle *handle, int pid);
 586
 587 /*
 588  * Deprecated: see `lttng_process_attr_process_id_tracker_handle_remove_pid`.
 589  *
 590  * Remove PID from session tracker.
 591  *
 592  * A pid argument >= 0 removes the PID from the session's PID tracker.
 593  * A pid argument of -1 means "untrack all PIDs".
 594  *
 595  * Note on 'real' PIDs vs 'virtual' VPIDs:
 596  *   - With the user space domain specified, this function will remove a VPID
 597  *     value from the virtual process ID process attribute tracker's inclusion
 598  *     set.
 599  *   - With the kernel space domain specified, this function will remove a PID
 600  *     value from the process ID process attribute tracker's inclusion set.
 601  *
 602  * Returns 0 on success, else a negative LTTng error code.
 603  */
 604 LTTNG_EXPORT extern int lttng_untrack_pid(struct lttng_handle *handle, int pid);
 605
 606 #ifdef __cplusplus
 607 }
 608 #endif
 609
 610 #endif /* LTTNG_TRACKER_H */