Collaboration diagram for Map group API:

Data Structures
struct	lttng_map_group
	Map group (opaque type). More...

struct	lttng_map_group_set
	Set of map groups (opaque type). More...

Enumerations
enum	lttng_map_group_set_status { LTTNG_MAP_GROUP_SET_STATUS_OK , LTTNG_MAP_GROUP_SET_STATUS_INVALID_PARAMETER }
	Status code for map group set functions. More...

enum	lttng_map_group_status { LTTNG_MAP_GROUP_STATUS_OK , LTTNG_MAP_GROUP_STATUS_INVALID_PARAMETER , LTTNG_MAP_GROUP_STATUS_ERROR }
	Status code for map group functions. More...

enum	lttng_map_group_type { LTTNG_MAP_GROUP_TYPE_KERNEL_GLOBAL , LTTNG_MAP_GROUP_TYPE_USER_PER_USER , LTTNG_MAP_GROUP_TYPE_USER_PER_PROCESS , LTTNG_MAP_GROUP_TYPE_SHARED }
	Type of a map group. More...

Functions
void	lttng_map_group_destroy (struct lttng_map_group *group)
	Destroys the map group `group`.

enum lttng_map_group_status	lttng_map_group_get_effective_value_type (const struct lttng_map_group group, enum lttng_map_value_type value_type)
	Sets `*value_type` to the effective value type of `group`.

enum lttng_map_group_status	lttng_map_group_get_type (const struct lttng_map_group group, enum lttng_map_group_type type)
	Sets `*type` to the type of `group`.

enum lttng_map_group_status	lttng_map_group_get_values (const struct lttng_map_group group, struct lttng_map_values_set *values_set)
	Sets `*values_set` to the current map values object of `group`.

void	lttng_map_group_set_destroy (struct lttng_map_group_set *set)
	Destroys the map group set `set`.

enum lttng_map_group_set_status	lttng_map_group_set_get_at_index (const struct lttng_map_group_set set, uint64_t index, const struct lttng_map_group *group)
	Sets `*group` to the map group at index `index` in `set`.

enum lttng_map_group_set_status	lttng_map_group_set_get_count (const struct lttng_map_group_set set, uint64_t count)
	Sets `*count` to the number of map groups in `set`.

enum lttng_map_group_status	lttng_map_group_user_get_owner_id (const struct lttng_map_group group, uint64_t owner_id)
	Sets `*owner_id` to the owner ID of the user space map group `group`.

enum lttng_map_group_status	lttng_map_group_user_get_owner_name (const struct lttng_map_group group, const char *owner_name)
	Sets `*owner_name` to the owner name of the user space map group `group`.

Detailed Description

A map group is the set of maps which a single owner of a parent map channel owns (see Map partitioning for what counts as an owner).

How a map channel partitions its owners into map groups depends on its type:

Linux kernel map channel

A single, system-wide map group.

User space map channel

One map group per (owner ID, effective value type) pair, where the owner is:

Per-user buffer ownership

The Unix user running the instrumented applications.

Per-process buffer ownership

An instrumented process.

When the value type of the map channel is LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX, a single owner running applications under multiple ABIs has one map group per effective value type: a 32-bit application contributes to the #LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32 group and a 64-bit application to the LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64 group.

When the value type is concrete (LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32 or LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64), the owner has a single map group to which all its applications contribute, whatever their bitness.

In addition to those, every map channel also exposes a single shared map group: a channel-wide group with no owner ID and no per-partition decomposition.

When LTTng executes an “increment map value” action, it selects the map group based on the owner ID of the executor of the instrumentation point which made the containing trigger fire.

Obtain the map groups of a map channel from the map channel itself.

Properties

The properties of a map group are:

Property name Description Access

Type

Selects which type-specific accessors apply to the map group; see lttng_map_group_type.

The four types are:

LTTNG_MAP_GROUP_TYPE_KERNEL_GLOBAL

The single, system-wide map group of a Linux kernel map channel.

LTTNG_MAP_GROUP_TYPE_USER_PER_USER

A per-user, per-effective value type map group of a user space map channel having the per-user buffer ownership model.

LTTNG_MAP_GROUP_TYPE_USER_PER_PROCESS

A per-process, per-effective value type map group of a user space map channel having the per-process buffer ownership model.

LTTNG_MAP_GROUP_TYPE_SHARED

The single, channel-wide shared map group of a user space map channel (any buffer ownership model). A Linux kernel map channel has no shared map group.

The lttng_map_group_user_*() accessors only apply to a map group whose type is LTTNG_MAP_GROUP_TYPE_USER_PER_USER or LTTNG_MAP_GROUP_TYPE_USER_PER_PROCESS.

lttng_map_group_get_type()

Effective value type

The actual value type of the map group, resolved from the value type of the parent map channel; see lttng_map_value_type.

Always LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32 or LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64, never LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX: the session daemon resolves the value type of the channel to an effective value type when it creates the maps of the group.

lttng_map_group_get_effective_value_type()

Operations

The map group operations are:

Operation	Means
Type access	lttng_map_group_get_type()
Effective value type access	lttng_map_group_get_effective_value_type()
Owner ID and owner name access (user space map group)	Only applies to a map group whose type is LTTNG_MAP_GROUP_TYPE_USER_PER_USER or LTTNG_MAP_GROUP_TYPE_USER_PER_PROCESS. Owner ID (Unix user ID or process ID) lttng_map_group_user_get_owner_id() Owner name (display/informational only) lttng_map_group_user_get_owner_name()
Value sampling	Obtain a map values object set with lttng_map_group_get_values(). The resulting set contains one map values object per partition which contributes to the map group (one per CPU, as of LTTng-tools 16.2). For a shared map group (type LTTNG_MAP_GROUP_TYPE_SHARED), the resulting set always contains exactly one map values object, and lttng_map_values_get_partition_id() does not apply to it. @important lttng_map_group_get_values() does not provide an atomic snapshot of the map values: the connected session daemon reads the values one by one, and LTTng tracers may concurrently update any of them while the function runs. Therefore, the resulting set doesn't necessarily reflect the state of the maps at a single instant. To obtain a consistent view of the map values, either: Stop the recording session with lttng_stop_tracing() before calling lttng_map_group_get_values(). Disable the recording event rules and/or remove the triggers having an "increment map value" action which targets the map channel of the map group. Use the map values set; see Map value API. Destroy the map values set with lttng_map_values_set_destroy().

Enumeration Type Documentation

◆ lttng_map_group_set_status

enum lttng_map_group_set_status

Status code for map group set functions.

Enumerator
LTTNG_MAP_GROUP_SET_STATUS_OK	Success.
LTTNG_MAP_GROUP_SET_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

◆ lttng_map_group_status

enum lttng_map_group_status

Status code for map group functions.

Enumerator
LTTNG_MAP_GROUP_STATUS_OK	Success.
LTTNG_MAP_GROUP_STATUS_INVALID_PARAMETER	Unsatisfied precondition.
LTTNG_MAP_GROUP_STATUS_ERROR	Other error.

◆ lttng_map_group_type

enum lttng_map_group_type

Type of a map group.

See Type to learn more.

Enumerator
LTTNG_MAP_GROUP_TYPE_KERNEL_GLOBAL	Linux kernel, system-wide map group.
LTTNG_MAP_GROUP_TYPE_USER_PER_USER	Per-user, user space map group.
LTTNG_MAP_GROUP_TYPE_USER_PER_PROCESS	Per-process, user space map group.
LTTNG_MAP_GROUP_TYPE_SHARED	Channel-wide map group with no owner ID (one per user space map channel). A Linux kernel map channel has no shared map group. See Shared map group to learn more.

Function Documentation

◆ lttng_map_group_destroy()

void lttng_map_group_destroy ( struct lttng_map_group * group )

extern

Destroys the map group group.

This function destroys the local, client-side handle on group: it does not destroy the corresponding session daemon map group.

Only use this function to release a map group handle which you obtained from lttng_map_channel_get_shared_group(), lttng_map_channel_user_get_group_by_uid(), or lttng_map_channel_user_get_group_by_pid(). For groups owned by a map group set, call lttng_map_group_set_destroy() instead.

Parameters

[in]

group

Map group to destroy.

May be NULL, in which case this function does nothing.

◆ lttng_map_group_get_effective_value_type()

enum lttng_map_group_status lttng_map_group_get_effective_value_type	(	const struct lttng_map_group *	group,
		enum lttng_map_value_type *	value_type
	)

extern

Sets *value_type to the effective value type of group.

The effective value type of group is the concrete signed integer type (as of LTTng-tools 16.2) of its map values object, resolved from the value type of the map channel of group.

As of LTTng stable-2.16, the effective value type of a map group is always LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32 or LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64: it's never LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX, which the session daemon resolves to a concrete width when it creates the maps of the group.

A user space map channel having the LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX value type can expose, for a single owner, both a LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32 and a LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64 map group: the instrumented applications of the owner contribute to the group of their own bitness. A channel having the LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32 or LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64 value type exposes a single group per owner: all the applications of the owner, whatever their bitness, contribute to the same map group.

Parameters

[in]	group	Map group of which to get the effective value type.
[out]	value_type	On success, this function sets `*value_type` to the effective value type of `group`.

Return values

LTTNG_MAP_GROUP_STATUS_OK	Success.
LTTNG_MAP_GROUP_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

group is not NULL.
value_type is not NULL.

◆ lttng_map_group_get_type()

enum lttng_map_group_status lttng_map_group_get_type	(	const struct lttng_map_group *	group,
		enum lttng_map_group_type *	type
	)

extern

Sets *type to the type of group.

The type of group selects which type-specific accessors apply to it:

LTTNG_MAP_GROUP_TYPE_KERNEL_GLOBAL

No type-specific accessor applies.

LTTNG_MAP_GROUP_TYPE_USER_PER_USER

LTTNG_MAP_GROUP_TYPE_USER_PER_PROCESS

LTTNG_MAP_GROUP_TYPE_SHARED

No type-specific accessor applies.

In addition, lttng_map_values_get_partition_id() doesn't apply to any map values object which lttng_map_group_get_values() produces from group.

Parameters

[in]	group	Map group of which to get the type.
[out]	type	On success, this function sets `*type` to the type of `group`.

Return values

LTTNG_MAP_GROUP_STATUS_OK	Success.
LTTNG_MAP_GROUP_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

group is not NULL.
type is not NULL.

◆ lttng_map_group_get_values()

enum lttng_map_group_status lttng_map_group_get_values	(	const struct lttng_map_group *	group,
		struct lttng_map_values_set **	values_set
	)

extern

Sets *values_set to the current map values object of group.

*values_set contains one per-partition values object per partition which contributes to group.

When the type of group is LTTNG_MAP_GROUP_TYPE_SHARED, the shared map group has no per-partition decomposition: *values_set always contains exactly one map values object, and lttng_map_values_get_partition_id() does not apply to it.

@important

This function does not provide an atomic snapshot of the map values: the connected session daemon reads the values one by one, and LTTng tracers may concurrently update any of them while the function runs. Therefore, *values_set doesn't necessarily reflect the state of the maps at a single instant.

To obtain a consistent view of the map values, either:

Stop the recording session with lttng_stop_tracing() before calling this function.
Disable the recording event rules and/or remove the triggers having an "increment map value" action which targets the map channel of group.

Parameters

[in] group Map group of which to snapshot the per-partition views.

[out]

values_set

On success, this function sets *values_set to the resulting collection of per-partition views.

Destroy *values_set with lttng_map_values_set_destroy().

Return values

LTTNG_MAP_GROUP_STATUS_OK	Success.
LTTNG_MAP_GROUP_STATUS_INVALID_PARAMETER	Unsatisfied precondition.
LTTNG_MAP_GROUP_STATUS_ERROR	Other error.

Precondition

liblttng-ctl can connect to a session daemon.
group is not NULL.
values_set is not NULL.

◆ lttng_map_group_set_destroy()

void lttng_map_group_set_destroy ( struct lttng_map_group_set * set )

extern

Destroys the map group set set.

Parameters

[in]

set

Map group set to destroy.

May be NULL, in which case this function does nothing.

◆ lttng_map_group_set_get_at_index()

enum lttng_map_group_set_status lttng_map_group_set_get_at_index	(	const struct lttng_map_group_set *	set,
		uint64_t	index,
		const struct lttng_map_group **	group
	)

extern

Sets *group to the map group at index index in set.

Parameters

[in] set Map group set of which to get a map group.

[in] index Index of the map group to get from set.

[out]

group

On success, this function sets *group to the map group at index in set.

set owns *group, which remains valid as long as set exists.

Return values

LTTNG_MAP_GROUP_SET_STATUS_OK	Success.
LTTNG_MAP_GROUP_SET_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

set is not NULL.
index is less than the number of map groups in set, as returned by lttng_map_group_set_get_count().
group is not NULL.

See also: lttng_map_group_set_get_count() – Returns the number of map groups in a map group set.

◆ lttng_map_group_set_get_count()

enum lttng_map_group_set_status lttng_map_group_set_get_count	(	const struct lttng_map_group_set *	set,
		uint64_t *	count
	)

extern

Sets *count to the number of map groups in set.

Parameters

[in]	set	Map group set of which to get the number of map groups.
[out]	count	On success, this function sets `*count` to the number of map groups in `set`.

Return values

LTTNG_MAP_GROUP_SET_STATUS_OK	Success.
LTTNG_MAP_GROUP_SET_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

set is not NULL.
count is not NULL.

See also: lttng_map_group_set_get_at_index() – Returns a map group at a given index from a map group set.

◆ lttng_map_group_user_get_owner_id()

enum lttng_map_group_status lttng_map_group_user_get_owner_id	(	const struct lttng_map_group *	group,
		uint64_t *	owner_id
	)

extern

Sets *owner_id to the owner ID of the user space map group group.

The owner ID of group depends on its type:

LTTNG_MAP_GROUP_TYPE_USER_PER_USER

The Unix user ID of group.

LTTNG_MAP_GROUP_TYPE_USER_PER_PROCESS

The process ID of group.

Parameters

[in]	group	User space map group of which to get the owner ID.
[out]	owner_id	On success, this function sets `*owner_id` to the owner ID of `group`.

Return values

LTTNG_MAP_GROUP_STATUS_OK	Success.
LTTNG_MAP_GROUP_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

group is not NULL.
lttng_map_group_get_type() returns LTTNG_MAP_GROUP_TYPE_USER_PER_USER or LTTNG_MAP_GROUP_TYPE_USER_PER_PROCESS with group.
owner_id is not NULL.

See also: lttng_map_group_user_get_owner_name() – Returns the owner name of a user space map group.

◆ lttng_map_group_user_get_owner_name()

enum lttng_map_group_status lttng_map_group_user_get_owner_name	(	const struct lttng_map_group *	group,
		const char **	owner_name
	)

extern

Sets *owner_name to the owner name of the user space map group group.

The owner name of group is a human-readable name for its owner, for example a Unix user name (for a LTTNG_MAP_GROUP_TYPE_USER_PER_USER group) or a process/command name (for a LTTNG_MAP_GROUP_TYPE_USER_PER_PROCESS group).

Note

This API makes no guarantee about this name: it's provided for display and informational purposes only.

In particular, the name isn't guaranteed to be set (it may be an empty string), to be unique amongst the map groups of a given map channel, nor to remain stable across calls and versions.

Use lttng_map_group_user_get_owner_id() to identify the owner of group reliably.

Parameters

[in] group User space map group of which to get the owner name.

[out]

owner_name

On success, this function sets *owner_name to the owner name of group.

group owns *owner_name: it remains valid as long as group exists.

Return values

LTTNG_MAP_GROUP_STATUS_OK	Success.
LTTNG_MAP_GROUP_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

group is not NULL.
lttng_map_group_get_type() returns LTTNG_MAP_GROUP_TYPE_USER_PER_USER or LTTNG_MAP_GROUP_TYPE_USER_PER_PROCESS with group.
owner_name is not NULL.

See also: lttng_map_group_user_get_owner_id() – Returns the owner ID of a user space map group.

Data Structures

Enumerations

Functions

Detailed Description

Properties

Operations

Enumeration Type Documentation

◆ lttng_map_group_set_status

◆ lttng_map_group_status

◆ lttng_map_group_type

Function Documentation

◆ lttng_map_group_destroy()

◆ lttng_map_group_get_effective_value_type()

◆ lttng_map_group_get_type()

◆ lttng_map_group_get_values()

◆ lttng_map_group_set_destroy()

◆ lttng_map_group_set_get_at_index()

◆ lttng_map_group_set_get_count()

◆ lttng_map_group_user_get_owner_id()

◆ lttng_map_group_user_get_owner_name()