/*
- * Copyright (C) 2019 Jonathan Rajotte-Julien <jonathan.rajotte-julien@efficios.com>
+ * Copyright (C) 2019 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
+ * Copyright (C) 2020 Jérémie Galarneau <jeremie.galarneau@efficios.com>
*
* SPDX-License-Identifier: LGPL-2.1-only
*
#define LTTNG_TRACKER_H
#include <lttng/constant.h>
-#include <common/macros.h>
+#include <lttng/domain.h>
+#include <lttng/lttng-error.h>
#include <lttng/session.h>
+#include <sys/types.h>
+
#ifdef __cplusplus
extern "C" {
#endif
-enum lttng_tracker_type {
- LTTNG_TRACKER_PID = 0,
- LTTNG_TRACKER_VPID = 1,
- LTTNG_TRACKER_UID = 2,
- LTTNG_TRACKER_GID = 3,
- LTTNG_TRACKER_VUID = 4,
- LTTNG_TRACKER_VGID = 5,
+/*
+ * Process attribute tracked by a tracker.
+ */
+enum lttng_process_attr {
+ /* Kernel space domain only. */
+ LTTNG_PROCESS_ATTR_PROCESS_ID = 0,
+ /* Kernel and user space domains. */
+ LTTNG_PROCESS_ATTR_VIRTUAL_PROCESS_ID = 1,
+ /* Kernel space domain only. */
+ LTTNG_PROCESS_ATTR_USER_ID = 2,
+ /* Kernel and user space domains. */
+ LTTNG_PROCESS_ATTR_VIRTUAL_USER_ID = 3,
+ /* Kernel space domain only. */
+ LTTNG_PROCESS_ATTR_GROUP_ID = 4,
+ /* Kernel and user space domains. */
+ LTTNG_PROCESS_ATTR_VIRTUAL_GROUP_ID = 5,
+};
+
+/*
+ * Tracking (filtering) policy of a process attribute tracker.
+ */
+enum lttng_tracking_policy {
+ /*
+ * Track all possible process attribute value of a given type
+ * (i.e. no filtering).
+ * This is the default state of a process attribute tracker.
+ */
+ LTTNG_TRACKING_POLICY_INCLUDE_ALL = 0,
+ /* Exclude all possible process attribute values of a given type. */
+ LTTNG_TRACKING_POLICY_EXCLUDE_ALL = 1,
+ /* Track a set of specific process attribute values. */
+ LTTNG_TRACKING_POLICY_INCLUDE_SET = 2,
+};
+
+/*
+ * Type of a process attribute value.
+ *
+ * This allows the use of the matching accessor given the type of a value.
+ */
+enum lttng_process_attr_value_type {
+ LTTNG_PROCESS_ATTR_VALUE_TYPE_INVALID = -1,
+ LTTNG_PROCESS_ATTR_VALUE_TYPE_PID = 0,
+ LTTNG_PROCESS_ATTR_VALUE_TYPE_UID = 1,
+ LTTNG_PROCESS_ATTR_VALUE_TYPE_USER_NAME = 2,
+ LTTNG_PROCESS_ATTR_VALUE_TYPE_GID = 3,
+ LTTNG_PROCESS_ATTR_VALUE_TYPE_GROUP_NAME = 4,
};
-enum lttng_tracker_id_type {
- LTTNG_ID_UNKNOWN = -1,
- LTTNG_ID_ALL = 0,
- LTTNG_ID_VALUE = 1,
- LTTNG_ID_STRING = 2,
+enum lttng_process_attr_tracker_handle_status {
+ LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_GROUP_NOT_FOUND = -7,
+ LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_USER_NOT_FOUND = -6,
+ LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID_TRACKING_POLICY = -5,
+ LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_SESSION_DOES_NOT_EXIST = -4,
+ LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_ERROR = -3,
+ LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_COMMUNICATION_ERROR = -2,
+ LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID = -1,
+ LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK = 0,
+ LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_EXISTS = 1,
+ LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_MISSING = 2,
};
-enum lttng_tracker_id_status {
- /* Invalid tracker id parameter. */
- LTTNG_TRACKER_ID_STATUS_INVALID = -1,
- LTTNG_TRACKER_ID_STATUS_OK = 0,
- /* Tracker id parameter is unset. */
- LTTNG_TRACKER_ID_STATUS_UNSET = 1,
+enum lttng_process_attr_values_status {
+ LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE = -2,
+ LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID = -1,
+ LTTNG_PROCESS_ATTR_VALUES_STATUS_OK = 0,
};
/*
- * A tracker id.
+ * A process attribute tracker handle.
+ *
+ * A process attribute tracker is an _inclusion set_ of process
+ * attribute values. Tracked processes are allowed to emit events,
+ * provided those events are targeted by enabled event rules.
+ *
+ * An LTTng session is created with a number of process attribute
+ * trackers by default. The process attributes that can be tracked vary by
+ * domain (see enum lttng_process_attr).
+ *
+ * Trackers are per-domain (user and kernel space) and allow the filtering
+ * of events based on a process's attributes.
*/
-struct lttng_tracker_id;
+struct lttng_process_attr_tracker_handle;
+
+/* A set of process attribute values. */
+struct lttng_process_attr_values;
/*
- * A collection of tracker id.
+ * Get a handle to one of the process attribute trackers of a session's domain.
+ *
+ * Returns LTTNG_OK and a process attribute tracker handle on success,
+ * or an lttng_error_code on error.
+ *
+ * The tracker's ownership is transfered to the caller. Use
+ * lttng_process_attr_tracker_handle_destroy() to dispose of it.
+ */
+extern enum lttng_error_code lttng_session_get_tracker_handle(
+ const char *session_name,
+ enum lttng_domain_type domain,
+ enum lttng_process_attr process_attr,
+ struct lttng_process_attr_tracker_handle **out_tracker_handle);
+
+/*
+ * Destroy a process attribute tracker handle.
*/
-struct lttng_tracker_ids;
+extern void lttng_process_attr_tracker_handle_destroy(
+ struct lttng_process_attr_tracker_handle *tracker_handle);
/*
- * Create a tracker id for the passed tracker type.
- * Users must set the tracker id using the matching API call.
+ * Get the tracking policy of a process attribute tracker.
*
- * On success, the caller is responsible for calling lttng_tracker_id_destroy.
- * On error, return NULL.
+ * Returns the LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK and the tracking
+ * policy of a process attribute tracker on success,
+ * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID on error.
*/
-extern struct lttng_tracker_id *lttng_tracker_id_create(void);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_tracker_handle_get_tracking_policy(
+ const struct lttng_process_attr_tracker_handle *tracker_handle,
+ enum lttng_tracking_policy *policy);
/*
- * Configure the tracker id using the numerical representation of the resource
- * to be tracked/untracked.
+ * Set the tracking policy of a process attribute tracker.
*
- * If the tracker id was already configured, calling this function will replace
- * the previous configuration and free memory as necessary.
+ * Setting the tracking policy to the current tracking policy has no effect.
*
- * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
- * LTTNG_TRACKER_ID_STATUS_INVALID is the passed parameter is invalid.
+ * Returns the LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID on error.
*/
-extern enum lttng_tracker_id_status lttng_tracker_id_set_value(
- struct lttng_tracker_id *id, int value);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_tracker_handle_set_tracking_policy(
+ const struct lttng_process_attr_tracker_handle *tracker_handle,
+ enum lttng_tracking_policy policy);
/*
- * Configure the tracker id using the string representation of the resource to
- * be tracked/untracked.
+ * Add a numerical PID to the process ID process attribute tracker inclusion
+ * set.
*
- * If the tracker id was already configured, calling this function will replace
- * the previous configuration and free memory as necessary.
+ * Returns LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_EXISTS if it was already
+ * present in the inclusion set, and
+ * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID if an invalid tracker
+ * argument was provided.
+ */
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_process_id_tracker_handle_add_pid(
+ const struct lttng_process_attr_tracker_handle
+ *process_id_tracker,
+ pid_t pid);
+
+/*
+ * Remove a numerical PID from the process ID process attribute tracker include
+ * set.
*
- * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
- * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
+ * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
+ * an invalid tracker argument was provided.
*/
-extern enum lttng_tracker_id_status lttng_tracker_id_set_string(
- struct lttng_tracker_id *id, const char *value);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_process_id_tracker_handle_remove_pid(
+ const struct lttng_process_attr_tracker_handle
+ *process_id_tracker,
+ pid_t pid);
/*
- * Configure the tracker id to track/untrack all resources for the tracker type.
+ * Add a numerical PID to the virtual process ID process attribute tracker
+ * inclusion set.
*
- * If the tracker id was already configured, calling this function will replace
- * the previous configuration and free memory as necessary.
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
+ * present in the inclusion set, and
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
+ * argument was provided.
+ */
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_virtual_process_id_tracker_handle_add_pid(
+ const struct lttng_process_attr_tracker_handle
+ *process_id_tracker,
+ pid_t vpid);
+
+/*
+ * Remove a numerical PID from the virtual process ID process attribute tracker
+ * inclusion set.
*
- * Returns LTTNG_TRACKER_ID_STATUS_OK on success,
- * LTTNG_TRACKER_ID_STATUS_INVALID if the passed parameter is invalid.
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
+ * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
+ * an invalid tracker argument was provided.
*/
-extern enum lttng_tracker_id_status lttng_tracker_id_set_all(
- struct lttng_tracker_id *id);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_virtual_process_id_tracker_handle_remove_pid(
+ const struct lttng_process_attr_tracker_handle
+ *process_id_tracker,
+ pid_t vpid);
/*
- * Destroy a tracker id.
+ * Add a numerical UID to the user ID process attribute tracker inclusion set.
+ *
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
+ * present in the inclusion set, and
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
+ * argument was provided.
*/
-extern void lttng_tracker_id_destroy(struct lttng_tracker_id *id);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_user_id_tracker_handle_add_uid(
+ const struct lttng_process_attr_tracker_handle *user_id_tracker,
+ uid_t uid);
/*
- * Get the type of a tracker id.
+ * Remove a numerical UID from the user ID process attribute tracker include
+ * set.
+ *
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
+ * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
+ * an invalid tracker argument was provided.
*/
-extern enum lttng_tracker_id_type lttng_tracker_id_get_type(
- const struct lttng_tracker_id *id);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_user_id_tracker_handle_remove_uid(
+ const struct lttng_process_attr_tracker_handle *user_id_tracker,
+ uid_t uid);
/*
- * Get the value of a tracker id.
+ * Add a user name to the user ID process attribute tracker inclusion set.
+ *
+ * The user name resolution is performed by the session daemon on addition to
+ * the user ID inclusion set.
*
- * Returns LTTNG_TRACKER_ID_OK on success,
- * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
- * LTTNG_ID_VALUE,
- * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
+ * present in the inclusion set, and
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
+ * argument was provided.
*/
-extern enum lttng_tracker_id_status lttng_tracker_id_get_value(
- const struct lttng_tracker_id *id, int *value);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_user_id_tracker_handle_add_user_name(
+ const struct lttng_process_attr_tracker_handle *user_id_tracker,
+ const char *user_name);
/*
- * Get the string representation of the tracker id.
+ * Remove a user name from the user ID process attribute tracker include
+ * set.
+ *
+ * No name resolution is performed; the user name will be matched against the
+ * names in the inclusion set.
*
- * Returns LTTNG_TRACKER_ID_OK on success,
- * LTTNG_TRACKER_ID_STATUS_INVALID when the tracker is not of type
- * LTTNG_ID_STRING,
- * LTTNG_TRACKER_ID_STATUS_UNSET when the tracker is not set.
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
+ * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
+ * an invalid tracker argument was provided.
*/
-extern enum lttng_tracker_id_status lttng_tracker_id_get_string(
- const struct lttng_tracker_id *id, const char **value);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_user_id_tracker_handle_remove_user_name(
+ const struct lttng_process_attr_tracker_handle *user_id_tracker,
+ const char *user_name);
/*
- * Add ID to session tracker.
+ * Add a numerical UID to the virtual user ID process attribute tracker
+ * inclusion set.
*
- * tracker_type is the type of tracker.
- * id is the lttng_tracker_type to track.
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
+ * present in the inclusion set, and
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
+ * argument was provided.
+ */
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_virtual_user_id_tracker_handle_add_uid(
+ const struct lttng_process_attr_tracker_handle *user_id_tracker,
+ uid_t vuid);
+
+/*
+ * Remove a numerical UID from the virtual user ID process attribute tracker
+ * inclusion set.
*
- * Returns 0 on success else a negative LTTng error code.
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
+ * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
+ * an invalid tracker argument was provided.
*/
-extern int lttng_track_id(struct lttng_handle *handle,
- enum lttng_tracker_type tracker_type,
- const struct lttng_tracker_id *id);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_virtual_user_id_tracker_handle_remove_uid(
+ const struct lttng_process_attr_tracker_handle *user_id_tracker,
+ uid_t vuid);
/*
- * Remove ID from session tracker.
+ * Add a user name to the virtual user ID process attribute tracker include
+ * set.
+ *
+ * The user name resolution is performed by the session daemon on addition to
+ * the virtual user ID inclusion set.
*
- * tracker_type is the type of tracker.
- * id is the lttng_tracker_type to untrack.
- * Returns 0 on success else a negative LTTng error code.
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
+ * present in the inclusion set, and
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
+ * argument was provided.
*/
-extern int lttng_untrack_id(struct lttng_handle *handle,
- enum lttng_tracker_type tracker_type,
- const struct lttng_tracker_id *id);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_virtual_user_id_tracker_handle_add_user_name(
+ const struct lttng_process_attr_tracker_handle *user_id_tracker,
+ const char *virtual_user_name);
/*
- * List IDs of a tracker.
+ * Remove a user name from the virtual user ID process attribute tracker
+ * inclusion set.
*
- * On success, ids is allocated.
- * The ids collection must be freed by the caller with lttng_destroy_ids().
+ * No name resolution is performed; the user name will be matched against the
+ * names in the inclusion set.
*
- * Returns 0 on success, else a negative LTTng error code.
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
+ * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
+ * an invalid tracker argument was provided.
*/
-extern int lttng_list_tracker_ids(struct lttng_handle *handle,
- enum lttng_tracker_type tracker_type,
- struct lttng_tracker_ids **ids);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_virtual_user_id_tracker_handle_remove_user_name(
+ const struct lttng_process_attr_tracker_handle *user_id_tracker,
+ const char *virtual_user_name);
/*
- * Backward compatibility.
- * Add PID to session tracker.
+ * Add a numerical GID to the group ID process attribute tracker inclusion set.
*
- * A pid argument >= 0 adds the PID to the session tracker.
- * A pid argument of -1 means "track all PIDs".
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
+ * present in the inclusion set, and
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
+ * argument was provided.
+ */
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_group_id_tracker_handle_add_gid(
+ const struct lttng_process_attr_tracker_handle *group_id_tracker,
+ gid_t gid);
+
+/*
+ * Remove a numerical GID from the group ID process attribute tracker include
+ * set.
*
- * Returns 0 on success else a negative LTTng error code.
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
+ * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
+ * an invalid tracker argument was provided.
*/
-extern int lttng_track_pid(struct lttng_handle *handle, int pid);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_group_id_tracker_handle_remove_gid(
+ const struct lttng_process_attr_tracker_handle *group_id_tracker,
+ gid_t gid);
/*
- * Backward compatibility.
- * Remove PID from session tracker.
+ * Add a group name to the group ID process attribute tracker inclusion set.
*
- * A pid argument >= 0 removes the PID from the session tracker.
- * A pid argument of -1 means "untrack all PIDs".
+ * The group name resolution is performed by the session daemon on addition to
+ * the group ID inclusion set.
*
- * Returns 0 on success else a negative LTTng error code.
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
+ * present in the inclusion set, and
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
+ * argument was provided.
*/
-extern int lttng_untrack_pid(struct lttng_handle *handle, int pid);
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_group_id_tracker_handle_add_group_name(
+ const struct lttng_process_attr_tracker_handle *group_id_tracker,
+ const char *group_name);
+
+/*
+ * Remove a group name from the group ID process attribute tracker include
+ * set.
+ *
+ * No name resolution is performed; the user name will be matched against the
+ * names in the inclusion set.
+ *
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
+ * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
+ * an invalid tracker argument was provided.
+ */
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_group_id_tracker_handle_remove_group_name(
+ const struct lttng_process_attr_tracker_handle *group_id_tracker,
+ const char *group_name);
+
+/*
+ * Add a numerical GID to the virtual group ID process attribute tracker
+ * inclusion set.
+ *
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
+ * present in the inclusion set, and
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
+ * argument was provided.
+ */
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_virtual_group_id_tracker_handle_add_gid(
+ const struct lttng_process_attr_tracker_handle *group_id_tracker,
+ gid_t vgid);
+
+/*
+ * Remove a numerical GID from the virtual group ID process attribute tracker
+ * inclusion set.
+ *
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
+ * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
+ * an invalid tracker argument was provided.
+ */
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_virtual_group_id_tracker_handle_remove_gid(
+ const struct lttng_process_attr_tracker_handle *group_id_tracker,
+ gid_t vgid);
+
+/*
+ * Add a group name to the virtual group ID process attribute tracker include
+ * set.
+ *
+ * The group name resolution is performed by the session daemon on addition to
+ * the virtual group ID inclusion set.
+ *
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_EXISTS if it was already
+ * present in the inclusion set, and
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if an invalid tracker
+ * argument was provided.
+ */
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_virtual_group_id_tracker_handle_add_group_name(
+ const struct lttng_process_attr_tracker_handle *group_id_tracker,
+ const char *virtual_group_name);
+
+/*
+ * Remove a group name from the virtual group ID process attribute tracker
+ * inclusion set.
+ *
+ * No name resolution is performed; the user name will be matched against the
+ * names in the inclusion set.
+ *
+ * Returns LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_MISSING if it was not present
+ * in the inclusion set, and LTTNG_PROCESS_ATTR_TRACKED_HANDLE_STATUS_INVALID if
+ * an invalid tracker argument was provided.
+ */
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_virtual_group_id_tracker_handle_remove_group_name(
+ const struct lttng_process_attr_tracker_handle *group_id_tracker,
+ const char *virtual_group_name);
+
+/*
+ * Get the process attribute values that are part of a tracker's inclusion set.
+ *
+ * The values returned are a snapshot of the values that are part of the
+ * tracker's inclusion set at the moment of the invocation; it is not updated
+ * as entries are added or removed.
+ *
+ * The values remain valid until the tracker is destroyed.
+ *
+ * Returns LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_TRACKER_HANDLE_STATUS_INVALID if the tracker's policy is
+ * not LTTNG_POLICY_INCLUDE_SET.
+ */
+extern enum lttng_process_attr_tracker_handle_status
+lttng_process_attr_tracker_handle_get_inclusion_set(
+ struct lttng_process_attr_tracker_handle *tracker_handle,
+ const struct lttng_process_attr_values **values);
/*
- * Backward compatibility
- * List PIDs in the tracker.
+ * Get the count of values within a set of process attribute values.
*
- * enabled is set to whether the PID tracker is enabled.
- * pids is set to an allocated array of PIDs currently tracked. On
- * success, pids must be freed by the caller.
- * nr_pids is set to the number of entries contained by the pids array.
+ * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID if an invalid argument is provided.
+ */
+extern enum lttng_process_attr_values_status
+lttng_process_attr_values_get_count(
+ const struct lttng_process_attr_values *values,
+ unsigned int *count);
+
+/*
+ * Get the type of a process attribute value at a given index.
+ *
+ * Returns a process attribute value type on success,
+ * LTTNG_PROCESS_ATTR_VALUE_TYPE_INVALID if an invalid argument is provided.
+ */
+extern enum lttng_process_attr_value_type
+lttng_process_attr_values_get_type_at_index(
+ const struct lttng_process_attr_values *values,
+ unsigned int index);
+
+/*
+ * Get a process ID process attribute value.
+ *
+ * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
+ * is not a process ID.
+ */
+extern enum lttng_process_attr_values_status
+lttng_process_attr_values_get_pid_at_index(
+ const struct lttng_process_attr_values *values,
+ unsigned int index,
+ pid_t *pid);
+
+/*
+ * Get a user ID process attribute value.
+ *
+ * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
+ * is not a user ID.
+ */
+extern enum lttng_process_attr_values_status
+lttng_process_attr_values_get_uid_at_index(
+ const struct lttng_process_attr_values *values,
+ unsigned int index,
+ uid_t *uid);
+
+/*
+ * Get a user name process attribute value.
+ *
+ * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
+ * is not a user name.
+ */
+extern enum lttng_process_attr_values_status
+lttng_process_attr_values_get_user_name_at_index(
+ const struct lttng_process_attr_values *values,
+ unsigned int index,
+ const char **user_name);
+
+/*
+ * Get a group ID process attribute value.
+ *
+ * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
+ * is not a group ID.
+ */
+extern enum lttng_process_attr_values_status
+lttng_process_attr_values_get_gid_at_index(
+ const struct lttng_process_attr_values *values,
+ unsigned int index,
+ gid_t *gid);
+
+/*
+ * Get a group name process attribute value.
+ *
+ * Returns LTTNG_PROCESS_ATTR_VALUES_STATUS_OK on success,
+ * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID_TYPE if the process attribute value
+ * is not a group name.
+ */
+extern enum lttng_process_attr_values_status
+lttng_process_attr_values_get_group_name_at_index(
+ const struct lttng_process_attr_values *values,
+ unsigned int index,
+ const char **group_name);
+
+/* The following entry points are deprecated. */
+
+/*
+ * Deprecated: see `lttng_process_attr_tracker_handle_get_inclusion_set` and
+ * `lttng_process_tracker_handle_get_tracking_policy`.
+ *
+ * List tracked PIDs.
+ *
+ * `enabled` indicates whether or not the PID tracker is enabled.
+ *
+ * `pids` is set to an allocated array of PIDs currently being tracked. On
+ * success, `pids` must be freed by the caller.
+ *
+ * `nr_pids` is set to the number of entries contained in the `pids` array.
*
* Returns 0 on success, else a negative LTTng error code.
*/
size_t *nr_pids);
/*
- * Get a tracker id from the list at a given index.
+ * Deprecated: see `lttng_process_attr_process_id_tracker_handle_add_pid`.
+ *
+ * Add PID to session tracker.
*
- * Note that the list maintains the ownership of the returned tracker id.
- * It must not be destroyed by the user, nor should it be held beyond the
- * lifetime of the tracker id list.
+ * A pid argument >= 0 adds the PID to the session's PID tracker.
+ * A pid argument of -1 means "track all PIDs".
*
- * Returns a tracker id, or NULL on error.
- */
-extern const struct lttng_tracker_id *lttng_tracker_ids_get_at_index(
- const struct lttng_tracker_ids *ids, unsigned int index);
-
-/*
- * Get the number of tracker id in a tracker id list.
+ * Note on 'real' PIDs vs 'virtual' VPIDs:
+ * - With the user space domain specified, this function will add a VPID
+ * value to the virtual process ID process attribute tracker's inclusion
+ * set.
+ * - With the kernel space domain specified, this function will add a PID
+ * value to the process ID process attribute tracker's inclusion set.
*
- * Return LTTNG_TRACKER_ID_STATUS on sucess,
- * LTTNG_TRACKER_ID_STATUS_INVALID when passed invalid parameters.
+ * Returns 0 on success, else a negative LTTng error code.
*/
-extern enum lttng_tracker_id_status lttng_tracker_ids_get_count(
- const struct lttng_tracker_ids *ids, unsigned int *count);
+extern int lttng_track_pid(struct lttng_handle *handle, int pid);
/*
- * Destroy a tracker id list.
+ * Deprecated: see `lttng_process_attr_process_id_tracker_handle_remove_pid`.
+ *
+ * Remove PID from session tracker.
+ *
+ * A pid argument >= 0 removes the PID from the session's PID tracker.
+ * A pid argument of -1 means "untrack all PIDs".
+ *
+ * Note on 'real' PIDs vs 'virtual' VPIDs:
+ * - With the user space domain specified, this function will remove a VPID
+ * value from the virtual process ID process attribute tracker's inclusion
+ * set.
+ * - With the kernel space domain specified, this function will remove a PID
+ * value from the process ID process attribute tracker's inclusion set.
+ *
+ * Returns 0 on success, else a negative LTTng error code.
*/
-extern void lttng_tracker_ids_destroy(struct lttng_tracker_ids *ids);
+extern int lttng_untrack_pid(struct lttng_handle *handle, int pid);
#ifdef __cplusplus
}
projects / lttng-tools.git / blobdiff