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