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 lttng_session_get_tracker_handle(
 120                 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 lttng_process_attr_tracker_handle_destroy(
 129                 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
 169                                 *process_id_tracker,
 170                 pid_t pid);
 171
 172 /*
 173  * Remove a numerical PID from the process ID process attribute tracker include
 174  * set.
 175  *
 176  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 177  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 178  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 179  * an invalid tracker argument was provided.
 180  */
 181 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 182 lttng_process_attr_process_id_tracker_handle_remove_pid(
 183                 const struct lttng_process_attr_tracker_handle
 184                                 *process_id_tracker,
 185                 pid_t pid);
 186
 187 /*
 188  * Add a numerical PID to the virtual process ID process attribute tracker
 189  * inclusion set.
 190  *
 191  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 192  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 193  * present in the inclusion set, and
 194  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 195  * argument was provided.
 196  */
 197 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 198 lttng_process_attr_virtual_process_id_tracker_handle_add_pid(
 199                 const struct lttng_process_attr_tracker_handle
 200                                 *process_id_tracker,
 201                 pid_t vpid);
 202
 203 /*
 204  * Remove a numerical PID from the virtual process ID process attribute tracker
 205  * inclusion set.
 206  *
 207  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 208  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 209  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 210  * an invalid tracker argument was provided.
 211  */
 212 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 213 lttng_process_attr_virtual_process_id_tracker_handle_remove_pid(
 214                 const struct lttng_process_attr_tracker_handle
 215                                 *process_id_tracker,
 216                 pid_t vpid);
 217
 218 /*
 219  * Add a numerical UID to the user ID process attribute tracker inclusion set.
 220  *
 221  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 222  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 223  * present in the inclusion set, and
 224  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 225  * argument was provided.
 226  */
 227 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 228 lttng_process_attr_user_id_tracker_handle_add_uid(
 229                 const struct lttng_process_attr_tracker_handle *user_id_tracker,
 230                 uid_t uid);
 231
 232 /*
 233  * Remove a numerical UID from the user ID process attribute tracker include
 234  * set.
 235  *
 236  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 237  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 238  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 239  * an invalid tracker argument was provided.
 240  */
 241 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 242 lttng_process_attr_user_id_tracker_handle_remove_uid(
 243                 const struct lttng_process_attr_tracker_handle *user_id_tracker,
 244                 uid_t uid);
 245
 246 /*
 247  * Add a user name to the user ID process attribute tracker inclusion set.
 248  *
 249  * The user name resolution is performed by the session daemon on addition to
 250  * the user ID inclusion set.
 251  *
 252  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 253  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 254  * present in the inclusion set, and
 255  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 256  * argument was provided.
 257  */
 258 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 259 lttng_process_attr_user_id_tracker_handle_add_user_name(
 260                 const struct lttng_process_attr_tracker_handle *user_id_tracker,
 261                 const char *user_name);
 262
 263 /*
 264  * Remove a user name from the user ID process attribute tracker include
 265  * set.
 266  *
 267  * No name resolution is performed; the user name will be matched against the
 268  * names in the inclusion set.
 269  *
 270  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 271  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 272  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 273  * an invalid tracker argument was provided.
 274  */
 275 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 276 lttng_process_attr_user_id_tracker_handle_remove_user_name(
 277                 const struct lttng_process_attr_tracker_handle *user_id_tracker,
 278                 const char *user_name);
 279
 280 /*
 281  * Add a numerical UID to the virtual user ID process attribute tracker
 282  * inclusion set.
 283  *
 284  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 285  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 286  * present in the inclusion set, and
 287  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 288  * argument was provided.
 289  */
 290 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 291 lttng_process_attr_virtual_user_id_tracker_handle_add_uid(
 292                 const struct lttng_process_attr_tracker_handle *user_id_tracker,
 293                 uid_t vuid);
 294
 295 /*
 296  * Remove a numerical UID from the virtual user ID process attribute tracker
 297  * inclusion set.
 298  *
 299  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 300  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 301  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 302  * an invalid tracker argument was provided.
 303  */
 304 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 305 lttng_process_attr_virtual_user_id_tracker_handle_remove_uid(
 306                 const struct lttng_process_attr_tracker_handle *user_id_tracker,
 307                 uid_t vuid);
 308
 309 /*
 310  * Add a user name to the virtual user ID process attribute tracker include
 311  * set.
 312  *
 313  * The user name resolution is performed by the session daemon on addition to
 314  * the virtual user ID inclusion set.
 315  *
 316  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 317  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 318  * present in the inclusion set, and
 319  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 320  * argument was provided.
 321  */
 322 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 323 lttng_process_attr_virtual_user_id_tracker_handle_add_user_name(
 324                 const struct lttng_process_attr_tracker_handle *user_id_tracker,
 325                 const char *virtual_user_name);
 326
 327 /*
 328  * Remove a user name from the virtual user ID process attribute tracker
 329  * inclusion set.
 330  *
 331  * No name resolution is performed; the user name will be matched against the
 332  * names in the inclusion set.
 333  *
 334  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 335  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 336  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 337  * an invalid tracker argument was provided.
 338  */
 339 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 340 lttng_process_attr_virtual_user_id_tracker_handle_remove_user_name(
 341                 const struct lttng_process_attr_tracker_handle *user_id_tracker,
 342                 const char *virtual_user_name);
 343
 344 /*
 345  * Add a numerical GID to the group ID process attribute tracker inclusion set.
 346  *
 347  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 348  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 349  * present in the inclusion set, and
 350  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 351  * argument was provided.
 352  */
 353 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 354 lttng_process_attr_group_id_tracker_handle_add_gid(
 355                 const struct lttng_process_attr_tracker_handle *group_id_tracker,
 356                 gid_t gid);
 357
 358 /*
 359  * Remove a numerical GID from the group ID process attribute tracker include
 360  * set.
 361  *
 362  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 363  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 364  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 365  * an invalid tracker argument was provided.
 366  */
 367 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 368 lttng_process_attr_group_id_tracker_handle_remove_gid(
 369                 const struct lttng_process_attr_tracker_handle *group_id_tracker,
 370                 gid_t gid);
 371
 372 /*
 373  * Add a group name to the group ID process attribute tracker inclusion set.
 374  *
 375  * The group name resolution is performed by the session daemon on addition to
 376  * the group ID inclusion set.
 377  *
 378  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 379  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 380  * present in the inclusion set, and
 381  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 382  * argument was provided.
 383  */
 384 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 385 lttng_process_attr_group_id_tracker_handle_add_group_name(
 386                 const struct lttng_process_attr_tracker_handle *group_id_tracker,
 387                 const char *group_name);
 388
 389 /*
 390  * Remove a group name from the group ID process attribute tracker include
 391  * set.
 392  *
 393  * No name resolution is performed; the user name will be matched against the
 394  * names in the inclusion set.
 395  *
 396  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 397  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 398  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 399  * an invalid tracker argument was provided.
 400  */
 401 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 402 lttng_process_attr_group_id_tracker_handle_remove_group_name(
 403                 const struct lttng_process_attr_tracker_handle *group_id_tracker,
 404                 const char *group_name);
 405
 406 /*
 407  * Add a numerical GID to the virtual group ID process attribute tracker
 408  * inclusion set.
 409  *
 410  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 411  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 412  * present in the inclusion set, and
 413  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 414  * argument was provided.
 415  */
 416 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 417 lttng_process_attr_virtual_group_id_tracker_handle_add_gid(
 418                 const struct lttng_process_attr_tracker_handle *group_id_tracker,
 419                 gid_t vgid);
 420
 421 /*
 422  * Remove a numerical GID from the virtual group ID process attribute tracker
 423  * inclusion set.
 424  *
 425  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 426  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 427  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 428  * an invalid tracker argument was provided.
 429  */
 430 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 431 lttng_process_attr_virtual_group_id_tracker_handle_remove_gid(
 432                 const struct lttng_process_attr_tracker_handle *group_id_tracker,
 433                 gid_t vgid);
 434
 435 /*
 436  * Add a group name to the virtual group ID process attribute tracker include
 437  * set.
 438  *
 439  * The group name resolution is performed by the session daemon on addition to
 440  * the virtual group ID inclusion set.
 441  *
 442  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 443  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
 444  * present in the inclusion set, and
 445  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
 446  * argument was provided.
 447  */
 448 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 449 lttng_process_attr_virtual_group_id_tracker_handle_add_group_name(
 450                 const struct lttng_process_attr_tracker_handle *group_id_tracker,
 451                 const char *virtual_group_name);
 452
 453 /*
 454  * Remove a group name from the virtual group ID process attribute tracker
 455  * inclusion set.
 456  *
 457  * No name resolution is performed; the user name will be matched against the
 458  * names in the inclusion set.
 459  *
 460  * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
 461  * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
 462  * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
 463  * an invalid tracker argument was provided.
 464  */
 465 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 466 lttng_process_attr_virtual_group_id_tracker_handle_remove_group_name(
 467                 const struct lttng_process_attr_tracker_handle *group_id_tracker,
 468                 const char *virtual_group_name);
 469
 470 /*
 471  * Get the process attribute values that are part of a tracker's inclusion set.
 472  *
 473  * The values returned are a snapshot of the values that are part of the
 474  * tracker's inclusion set at the moment of the invocation; it is not updated
 475  * as entries are added or removed.
 476  *
 477  * The values remain valid until the tracker is destroyed.
 478  *
 479  * Returns LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK on success,
 480  * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID if the tracker's policy is
 481  * not LTTNG_POLICY_INCLUDE_SET.
 482  */
 483 LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status
 484 lttng_process_attr_tracker_handle_get_inclusion_set(
 485                 struct lttng_process_attr_tracker_handle *tracker_handle,
 486                 const struct lttng_process_attr_values **values);
 487
 488 /*
 489  * Get the count of values within a set of process attribute values.
 490  *
 491  * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
 492  * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID if an invalid argument is provided.
 493  */
 494 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 495 lttng_process_attr_values_get_count(
 496                 const struct lttng_process_attr_values *values,
 497                 unsigned int *count);
 498
 499 /*
 500  * Get the type of a process attribute value at a given index.
 501  *
 502  * Returns a process attribute value type on success,
 503  * LTTNG_PROCESS_ATTR_VALUE_TYPE_INVALID if an invalid argument is provided.
 504  */
 505 LTTNG_EXPORT extern enum lttng_process_attr_value_type
 506 lttng_process_attr_values_get_type_at_index(
 507                 const struct lttng_process_attr_values *values,
 508                 unsigned int index);
 509
 510 /*
 511  * Get a process ID process attribute value.
 512  *
 513  * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
 514  * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
 515  * is not a process ID.
 516  */
 517 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 518 lttng_process_attr_values_get_pid_at_index(
 519                 const struct lttng_process_attr_values *values,
 520                 unsigned int index,
 521                 pid_t *pid);
 522
 523 /*
 524  * Get a user ID process attribute value.
 525  *
 526  * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
 527  * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
 528  * is not a user ID.
 529  */
 530 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 531 lttng_process_attr_values_get_uid_at_index(
 532                 const struct lttng_process_attr_values *values,
 533                 unsigned int index,
 534                 uid_t *uid);
 535
 536 /*
 537  * Get a user 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 user name.
 542  */
 543 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 544 lttng_process_attr_values_get_user_name_at_index(
 545                 const struct lttng_process_attr_values *values,
 546                 unsigned int index,
 547                 const char **user_name);
 548
 549 /*
 550  * Get a group ID process attribute value.
 551  *
 552  * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
 553  * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
 554  * is not a group ID.
 555  */
 556 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 557 lttng_process_attr_values_get_gid_at_index(
 558                 const struct lttng_process_attr_values *values,
 559                 unsigned int index,
 560                 gid_t *gid);
 561
 562 /*
 563  * Get a group name process attribute value.
 564  *
 565  * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
 566  * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
 567  * is not a group name.
 568  */
 569 LTTNG_EXPORT extern enum lttng_process_attr_values_status
 570 lttng_process_attr_values_get_group_name_at_index(
 571                 const struct lttng_process_attr_values *values,
 572                 unsigned int index,
 573                 const char **group_name);
 574
 575 /* The following entry points are deprecated. */
 576
 577 /*
 578  * Deprecated: see `lttng_process_attr_tracker_handle_get_inclusion_set` and
 579  * `lttng_process_tracker_handle_get_tracking_policy`.
 580  *
 581  * List tracked PIDs.
 582  *
 583  * `enabled` indicates whether or not the PID tracker is enabled.
 584  *
 585  * `pids` is set to an allocated array of PIDs currently being tracked. On
 586  * success, `pids` must be freed by the caller.
 587  *
 588  * `nr_pids` is set to the number of entries contained in the `pids` array.
 589  *
 590  * Returns 0 on success, else a negative LTTng error code.
 591  */
 592 LTTNG_EXPORT extern int lttng_list_tracker_pids(struct lttng_handle *handle,
 593                 int *enabled,
 594                 int32_t **pids,
 595                 size_t *nr_pids);
 596
 597 /*
 598  * Deprecated: see `lttng_process_attr_process_id_tracker_handle_add_pid`.
 599  *
 600  * Add PID to session tracker.
 601  *
 602  * A pid argument >= 0 adds the PID to the session's PID tracker.
 603  * A pid argument of -1 means "track all PIDs".
 604  *
 605  * Note on 'real' PIDs vs 'virtual' VPIDs:
 606  *   - With the user space domain specified, this function will add a VPID
 607  *     value to the virtual process ID process attribute tracker's inclusion
 608  *     set.
 609  *   - With the kernel space domain specified, this function will add a PID
 610  *     value to the process ID process attribute tracker's inclusion set.
 611  *
 612  * Returns 0 on success, else a negative LTTng error code.
 613  */
 614 LTTNG_EXPORT extern int lttng_track_pid(struct lttng_handle *handle, int pid);
 615
 616 /*
 617  * Deprecated: see `lttng_process_attr_process_id_tracker_handle_remove_pid`.
 618  *
 619  * Remove PID from session tracker.
 620  *
 621  * A pid argument >= 0 removes the PID from the session's PID tracker.
 622  * A pid argument of -1 means "untrack all PIDs".
 623  *
 624  * Note on 'real' PIDs vs 'virtual' VPIDs:
 625  *   - With the user space domain specified, this function will remove a VPID
 626  *     value from the virtual process ID process attribute tracker's inclusion
 627  *     set.
 628  *   - With the kernel space domain specified, this function will remove a PID
 629  *     value from the process ID process attribute tracker's inclusion set.
 630  *
 631  * Returns 0 on success, else a negative LTTng error code.
 632  */
 633 LTTNG_EXPORT extern int lttng_untrack_pid(struct lttng_handle *handle, int pid);
 634
 635 #ifdef __cplusplus
 636 }
 637 #endif
 638
 639 #endif /* LTTNG_TRACKER_H */