X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Ftracker.h;h=fa91abab6225c98c032043e14151c2bf1d310e2f;hp=fd715d799ed53dca68a7c74d0c15a13d8dafddf1;hb=64defc29e677a20a8ed00d55d9884a77bdc893d2;hpb=ab5be9fa2eb5ba9600a82cd18fd3cfcbac69169a diff --git a/include/lttng/tracker.h b/include/lttng/tracker.h index fd715d799..fa91abab6 100644 --- a/include/lttng/tracker.h +++ b/include/lttng/tracker.h @@ -1,5 +1,6 @@ /* - * Copyright (C) 2019 Jonathan Rajotte-Julien + * Copyright (C) 2019 Jonathan Rajotte + * Copyright (C) 2020 Jérémie Galarneau * * SPDX-License-Identifier: LGPL-2.1-only * @@ -9,192 +10,581 @@ #define LTTNG_TRACKER_H #include -#include +#include +#include #include +#include + #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. */ @@ -204,30 +594,42 @@ extern int lttng_list_tracker_pids(struct lttng_handle *handle, 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 }