LTTng control library C API
Loading...
Searching...
No Matches
Modules | Data Structures | Enumerations | Functions
Map channel API
Recording session API
Collaboration diagram for Map channel API:

Modules

 Map group API
 
 Map key API
 
 Map value API
 

Data Structures

struct  lttng_map_channel
 Map channel (opaque type). More...
 
struct  lttng_map_channel_descriptor
 Map channel descriptor (opaque type). More...
 
struct  lttng_map_channel_set
 Set of map channels (opaque type). More...
 

Enumerations

enum  lttng_map_channel_buffer_ownership { LTTNG_MAP_CHANNEL_BUFFER_OWNERSHIP_PER_UID , LTTNG_MAP_CHANNEL_BUFFER_OWNERSHIP_PER_PID }
 Buffer ownership model of a user space map channel. More...
 
enum  lttng_map_channel_dead_group_policy { LTTNG_MAP_CHANNEL_DEAD_GROUP_POLICY_DROP , LTTNG_MAP_CHANNEL_DEAD_GROUP_POLICY_SUM_INTO_SHARED }
 Dead group policy of a user space map channel with the per-process buffer ownership model. More...
 
enum  lttng_map_channel_descriptor_status { LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OK , LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_UNSET , LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETER }
 Status code for map channel descriptor property accessors. More...
 
enum  lttng_map_channel_set_status { LTTNG_MAP_CHANNEL_SET_STATUS_OK , LTTNG_MAP_CHANNEL_SET_STATUS_INVALID_PARAMETER }
 Status code for map channel set functions. More...
 
enum  lttng_map_channel_status { LTTNG_MAP_CHANNEL_STATUS_OK , LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETER , LTTNG_MAP_CHANNEL_STATUS_NOT_FOUND , LTTNG_MAP_CHANNEL_STATUS_ERROR }
 Status code for map channel functions. More...
 
enum  lttng_map_channel_type { LTTNG_MAP_CHANNEL_TYPE_KERNEL , LTTNG_MAP_CHANNEL_TYPE_USER }
 Type of a map channel. More...
 
enum  lttng_map_channel_update_policy { LTTNG_MAP_CHANNEL_UPDATE_POLICY_PER_EVENT , LTTNG_MAP_CHANNEL_UPDATE_POLICY_PER_RULE_MATCH }
 Update policy of a map channel. More...
 

Functions

void lttng_map_channel_descriptor_destroy (struct lttng_map_channel_descriptor *descriptor)
 Destroys the map channel descriptor descriptor.
 
enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_get_max_key_count (const struct lttng_map_channel_descriptor *descriptor, uint64_t *max_key_count)
 Sets *max_key_count to the maximum key count property of the map channel described by descriptor.
 
enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_get_name (const struct lttng_map_channel_descriptor *descriptor, const char **name)
 Sets *name to the name of the map channel described by descriptor.
 
enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_get_type (const struct lttng_map_channel_descriptor *descriptor, enum lttng_map_channel_type *type)
 Sets *type to the type of the map channel described by descriptor.
 
enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_get_update_policy (const struct lttng_map_channel_descriptor *descriptor, enum lttng_map_channel_update_policy *policy)
 Sets *policy to the update policy property of the map channel described by descriptor.
 
enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_get_value_type (const struct lttng_map_channel_descriptor *descriptor, enum lttng_map_value_type *value_type)
 Sets *value_type to the value type of the map channel described by descriptor.
 
struct lttng_map_channel_descriptor * lttng_map_channel_descriptor_kernel_string_key_scalar_value_create (enum lttng_map_value_type value_type)
 Creates a descriptor of a Linux kernel map channel whose maps have string keys and scalar values.
 
enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_set_max_key_count (struct lttng_map_channel_descriptor *descriptor, uint64_t max_key_count)
 Sets the maximum key count property of the map channel described by descriptor to max_key_count.
 
enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_set_name (struct lttng_map_channel_descriptor *descriptor, const char *name)
 Sets the name of the map channel described by descriptor to a copy of name.
 
enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_set_update_policy (struct lttng_map_channel_descriptor *descriptor, enum lttng_map_channel_update_policy policy)
 Sets the update policy property of the map channel described by descriptor to policy.
 
enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_user_get_buffer_ownership (const struct lttng_map_channel_descriptor *descriptor, enum lttng_map_channel_buffer_ownership *ownership_model)
 Sets *ownership_model to the buffer ownership model of the user space map channel described by descriptor.
 
enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_user_get_dead_group_policy (const struct lttng_map_channel_descriptor *descriptor, enum lttng_map_channel_dead_group_policy *policy)
 Sets *policy to the dead group policy property of the user space map channel described by descriptor.
 
enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_user_set_dead_group_policy (struct lttng_map_channel_descriptor *descriptor, enum lttng_map_channel_dead_group_policy policy)
 Sets the dead group policy property of the user space map channel described by descriptor to policy.
 
struct lttng_map_channel_descriptor * lttng_map_channel_descriptor_user_string_key_scalar_value_create (enum lttng_map_value_type value_type, enum lttng_map_channel_buffer_ownership ownership_model)
 Creates a descriptor of a user space map channel whose maps have string keys and scalar values.
 
void lttng_map_channel_destroy (struct lttng_map_channel *channel)
 Destroys the map channel channel.
 
enum lttng_map_channel_status lttng_map_channel_get_groups (const struct lttng_map_channel *channel, struct lttng_map_group_set **groups)
 Sets *groups to the map groups of channel.
 
enum lttng_map_channel_status lttng_map_channel_get_keys (const struct lttng_map_channel *channel, struct lttng_map_key_set **keys)
 Sets *keys to the current set of keys of channel.
 
enum lttng_map_channel_status lttng_map_channel_get_max_key_count (const struct lttng_map_channel *channel, uint64_t *max_key_count)
 Sets *max_key_count to the maximum key count property of channel.
 
enum lttng_map_channel_status lttng_map_channel_get_name (const struct lttng_map_channel *channel, const char **name)
 Sets *name to the name of channel.
 
enum lttng_map_channel_status lttng_map_channel_get_shared_group (const struct lttng_map_channel *channel, struct lttng_map_group **group)
 Sets *group to the shared map group of channel.
 
enum lttng_map_channel_status lttng_map_channel_get_type (const struct lttng_map_channel *channel, enum lttng_map_channel_type *type)
 Sets *type to the type of channel.
 
enum lttng_map_channel_status lttng_map_channel_get_update_policy (const struct lttng_map_channel *channel, enum lttng_map_channel_update_policy *policy)
 Sets *policy to the update policy property of channel.
 
enum lttng_map_channel_status lttng_map_channel_get_value_type (const struct lttng_map_channel *channel, enum lttng_map_value_type *value_type)
 Sets *value_type to the value type of channel.
 
void lttng_map_channel_set_destroy (struct lttng_map_channel_set *set)
 Destroys the map channel set set.
 
enum lttng_map_channel_set_status lttng_map_channel_set_get_at_index (const struct lttng_map_channel_set *set, uint64_t index, const struct lttng_map_channel **channel)
 Sets *channel to the map channel at index index in set.
 
enum lttng_map_channel_set_status lttng_map_channel_set_get_count (const struct lttng_map_channel_set *set, uint64_t *count)
 Sets *count to the number of map channels in set.
 
enum lttng_map_channel_status lttng_map_channel_user_get_buffer_ownership (const struct lttng_map_channel *channel, enum lttng_map_channel_buffer_ownership *ownership_model)
 Sets *ownership_model to the buffer ownership model of the user space map channel channel.
 
enum lttng_map_channel_status lttng_map_channel_user_get_dead_group_policy (const struct lttng_map_channel *channel, enum lttng_map_channel_dead_group_policy *policy)
 Sets *policy to the dead group policy of the user space map channel channel.
 
enum lttng_map_channel_status lttng_map_channel_user_get_group_by_pid (const struct lttng_map_channel *channel, pid_t pid, struct lttng_map_group_set **groups)
 Sets *groups to the map groups of the user space map channel channel for the process ID pid.
 
enum lttng_map_channel_status lttng_map_channel_user_get_group_by_uid (const struct lttng_map_channel *channel, uid_t uid, struct lttng_map_group_set **groups)
 Sets *groups to the map groups of the user space map channel channel for the Unix user ID uid.
 

Detailed Description

A map channel is an object which is responsible for a set of fixed-size, per-partition key-value stores known as maps.

A map channel is similar to a event record channel, except that, instead of containing ring buffers to record events, it contains maps which hold integer values keyed by strings (as of LTTng-tools 16.2).

Unlike a event record channel, which lives within a single tracing domain, a map channel only distinguishes Linux kernel from user space through its type: the map channel API treats every non-kernel tracing domain uniformly as user space.

To populate the maps of a map channel, add a trigger with an “increment map value” action which targets that map channel: each time the trigger fires, LTTng expands the key template of the action to obtain an effective key, and then increments the value of the corresponding map entry.

See also
The “MAP CHANNEL AND MAP” section of lttng-concepts(7).

Map partitioning

A map is the per-partition view of the values which a map channel keeps for a given owner, that is:

Linux kernel map channel

The whole system (a single, implicit owner).

User space map channel
A (Unix user or process, effective value type) pair, depending on the buffer ownership model of the map channel.

Each map exposes one value per key, and the map group for the owner is the set of all such per-partition views.

As of LTTng-tools 16.2, a map channel always allocates one map per CPU per owner (equivalent to per-CPU buffering for a event record channel): the partitioning is by CPU ID. Get the partition ID of a given per-partition map values object with lttng_map_values_get_partition_id().

In addition to the per-owner, per-CPU maps which the buffer ownership model dictates, every user space map channel also carries a single, channel-wide shared map group.

Properties

The properties of a map channel are:

Property name Description Access
Name Identifies the map channel within its (recording session, type) pair: two map channels may share the same name provided their types differ.

Initially unset on a map channel descriptor.

When unset, the session daemon automatically generates a name when you call lttng_session_add_map_channel().

Type

Selects which tracing domain family the map channel belongs to (kernel vs. user space; see lttng_map_channel_type) and which type-specific accessors apply (lttng_map_channel_kernel_*() vs. lttng_map_channel_user_*() functions).

Within a recording session, a map channel is uniquely identified by the (type, name) pair: two map channels may share the same name provided their types differ.

Determined by the descriptor creation function (kernel vs. user space).

Key type

Type of the map keys of the maps which the map channel contains; see lttng_map_key_type.

As of LTTng-tools 16.2, only string keys are available: every descriptor creation function bakes in LTTNG_MAP_KEY_TYPE_STRING.

Determined by the descriptor creation function (the _string_key_ infix in lttng_map_channel_descriptor_kernel_string_key_scalar_value_create() and lttng_map_channel_descriptor_user_string_key_scalar_value_create()).

Value type

Type of the values of the maps which the map channel contains; see lttng_map_value_type.

This property is the configured value type. The effective value type, that is, the value type which LTTng actually creates for a given instrumented application or for the Linux kernel, may differ from it, following two simple rules:

  • A counter can't be wider than whatever hosts it: the session daemon for a user space map channel, or the Linux kernel for a kernel map channel. Therefore, requesting a 64-bit counter on a 32-bit host makes the map channel creation fail.

  • The bitness of an instrumented application doesn't affect whether LTTng creates a user space map channel, since LTTng doesn't know it at that time; it only affects access afterwards.

    A 64-bit application can access a counter of any width, whereas a 32-bit application can only access a 32-bit counter.

    This access limit doesn't apply to kernel map channels, of which the session daemon reads the counters directly: a 32-bit session daemon reads a 64-bit kernel counter fine.

As of LTTng-tools 16.2, only signed integer value types are available:

LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32

32-bit signed integer values.

LTTng can always create such a map channel, and any instrumented application can access its counters.

LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64

64-bit signed integer values.

For a user space map channel, this requires a 64-bit session daemon (otherwise the map channel creation fails), and instrumented 32-bit applications can't access the counters.

For a kernel map channel, this requires a 64-bit kernel (otherwise the map channel creation fails).

LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX

The widest signed integer values which keep the counters accessible without making the map channel creation fail.

For a user space map channel, each instrumented application gets a counter of its own bitness, but never wider than the session daemon: both 32-bit and 64-bit applications can therefore always access such a map channel, and LTTng can always create it.

For a kernel map channel, this is the bitness of the session daemon, which reads the counters.

Set at descriptor creation time through the value_type parameter of lttng_map_channel_descriptor_kernel_string_key_scalar_value_create() or lttng_map_channel_descriptor_user_string_key_scalar_value_create().

Buffer ownership model (user space map channel) See Buffer ownership model.

Set at descriptor creation time through the ownership_model parameter of lttng_map_channel_descriptor_user_string_key_scalar_value_create().

Maximum key count

Caps the number of distinct keys which the map channel may track, and determines the size of each contained map.

When a map is full, LTTng silently drops any new key.

Update policy See Update policy.
Dead group policy (user space map channel with per-process buffer ownership) See Dead group policy.

All the properties above are immutable once a map channel exists.

Buffer ownership model

For a user space map channel, the buffer ownership model (lttng_map_channel_buffer_ownership enumerator) specifies whether each Unix user, or each process, owns its own maps:

LTTNG_MAP_CHANNEL_BUFFER_OWNERSHIP_PER_UID

The maps which back the channel are shared between all the instrumented applications of a given Unix user.

LTTNG_MAP_CHANNEL_BUFFER_OWNERSHIP_PER_PID
Each instrumented process has its own private maps.

This is the same concept as the buffer ownership model of a event record channel, except that it applies to the backing memory of maps instead of ring buffers.

A Linux kernel map channel doesn't have a buffer ownership model: its maps are always system-wide.

Update policy

The update policy of a map channel (lttng_map_channel_update_policy enumerator) controls how LTTng increments map values when multiple “event rule matches” triggers having an “increment map value” action which targets the same map channel match the same event and produce the same effective key:

LTTNG_MAP_CHANNEL_UPDATE_POLICY_PER_EVENT

LTTng increments a single map value per resulting key, regardless of how many of those triggers match.

This is similar to how LTTng writes a single event record to a given event record channel when multiple recording event rules of the map channel match the same event.

LTTNG_MAP_CHANNEL_UPDATE_POLICY_PER_RULE_MATCH
LTTng performs one map value increment per matching trigger, even when several matching triggers produce the same key.

The update policy is only meaningful when an “increment map value” action increments a map value because of an “event rule matches” trigger condition, since that's the only condition type which can match the same event through more than one trigger at once.

For a trigger having any other condition type, each firing of the trigger causes a single map value increment, regardless of the update policy.

Shared map group

A shared map group is a user space map channel concept: a Linux kernel map channel never has one.

In addition to the per-owner map groups which the buffer ownership model dictates, every user space map channel carries a single, channel-wide shared map group: one map with no owner ID (no Unix user, no process) and no per-partition decomposition.

In the map group API, the shared map group is a map group of type LTTNG_MAP_GROUP_TYPE_SHARED. Reach it directly with lttng_map_channel_get_shared_group(), or find it within the result of lttng_map_channel_get_groups() (it always exists for a user space map channel).

The LTTng session daemon (see lttng-sessiond(8)) writes its values directly: tracers don't update the shared map group. The session daemon writes to it when the dead group policy of the map channel is LTTNG_MAP_CHANNEL_DEAD_GROUP_POLICY_SUM_INTO_SHARED and an instrumented process terminates: LTTng then accumulates the values of the dying per-process maps into the shared map group of the channel.

Because the shared map group has no per-partition decomposition, lttng_map_group_get_values() always returns a map values object set of size 1 for it, and lttng_map_values_get_partition_id() does not apply to the contained map values object.

Dead group policy

The dead group policy of a user space map channel with the per-process buffer ownership model (lttng_map_channel_dead_group_policy enumerator) controls what LTTng does with the values of the maps of an instrumented process when this process terminates while the map channel still exists:

LTTNG_MAP_CHANNEL_DEAD_GROUP_POLICY_DROP

Discard the maps of the terminated process: their values, which the process accumulated since the start of the recording session, are lost.

LTTNG_MAP_CHANNEL_DEAD_GROUP_POLICY_SUM_INTO_SHARED

For each map of the terminated process, add each value to the corresponding key of the shared map group of the map channel.

When the addition would overflow the effective value type of the map group, the result wraps around (modular arithmetic) and LTTng sets the overflow flag of the corresponding shared map value (see lttng_map_values_signed_int_has_overflow_at_index()).

The dead group policy only applies to a user space map channel whose buffer ownership model is LTTNG_MAP_CHANNEL_BUFFER_OWNERSHIP_PER_PID. A kernel map channel and a per-user user space map channel don't have a dead group policy: nothing in their data model goes away independently of the recording session itself.

Operations

The map channel operations are:

Operation Means
Creation

  1. Create a map channel descriptor with lttng_map_channel_descriptor_kernel_string_key_scalar_value_create() or lttng_map_channel_descriptor_user_string_key_scalar_value_create() depending on the target tracing domain.

    These functions set the properties of the descriptor to initial values, fixing all the immutable ones up front:

  2. Set the optional properties of the descriptor:
  3. Add the described map channel to a recording session with lttng_session_add_map_channel().
  4. Destroy the descriptor with lttng_map_channel_descriptor_destroy().
See also
lttng-add-map-channel(1)
Listing

Use lttng_session_list_map_channels(), passing the type of the map channels of interest.

Look up a single map channel by (type, name) pair with lttng_session_get_map_channel_by_name().

See also
lttng-list(1)
lttng-status(1)
Property access Use the dedicated lttng_map_channel_get_*() and lttng_map_channel_user_get_*() functions.
Key access

  1. Use lttng_map_channel_get_keys() to obtain a "snapshot" of the current map key set of the map channel.

    The connected session daemon returns the keys which the map channel tracks at that moment; LTTng doesn't update the resulting set as keys are added to the channel afterwards.

  2. Use the resulting map key set; see Map key API for how to iterate, look up, and inspect individual keys.
  3. Destroy the resulting map key set with lttng_map_key_set_destroy().
Group access

  1. Reach a map group of the map channel:

    For all the map groups of the map channel, in one call

    Use lttng_map_channel_get_groups() to obtain a "snapshot" of the current map group set.

    For a user space map channel, the resulting set always includes the shared map group, which always exists. A Linux kernel map channel has no shared map group.

    The connected session daemon returns the map groups which the channel exposes at that moment; LTTng doesn't update the resulting set as map groups are added to or removed from the channel afterwards.

    For the map groups of one owner of a user space map channel

    Use lttng_map_channel_user_get_group_by_uid() or lttng_map_channel_user_get_group_by_pid(), depending on the buffer ownership model of the map channel. The resulting map group set contains one map group per effective value type of the owner (one or two, as of LTTng-tools 16.2).

    For the shared map group of a user space map channel
    Use lttng_map_channel_get_shared_group().
  2. Use the resulting map group(s); see Map group API.

  3. Destroy the resulting object:

    Map group set

    lttng_map_group_set_destroy().

    The set owns its map groups: do not destroy them individually with lttng_map_group_destroy().

    Single map group
    lttng_map_group_destroy().
See also
lttng-show-maps(1)
Value reset

Resetting the values of all the maps of all the map channels of a recording session to 0, without removing the keys themselves, is part of recording session clearing.

See also
lttng-clear(1)
Destruction (client-side handle)

Destroy a map channel handle obtained from lttng_session_get_map_channel_by_name() with lttng_map_channel_destroy().

For map channels owned by a map channel set, call lttng_map_channel_set_destroy() instead.

As of LTTng-tools 16.2, you can't remove a map channel from a recording session: it exists as long as the recording session exists.

Enumeration Type Documentation

◆ lttng_map_channel_buffer_ownership

enum lttng_map_channel_buffer_ownership

Buffer ownership model of a user space map channel.

See Buffer ownership model to learn more.

Enumerator
LTTNG_MAP_CHANNEL_BUFFER_OWNERSHIP_PER_UID 

Per-user buffering.

LTTNG_MAP_CHANNEL_BUFFER_OWNERSHIP_PER_PID 

Per-process buffering.

◆ lttng_map_channel_dead_group_policy

enum lttng_map_channel_dead_group_policy

Dead group policy of a user space map channel with the per-process buffer ownership model.

See Dead group policy to learn more.

Enumerator
LTTNG_MAP_CHANNEL_DEAD_GROUP_POLICY_DROP 

Discard the maps of the terminated process.

The values which the process accumulated since the start of the recording session are lost.

LTTNG_MAP_CHANNEL_DEAD_GROUP_POLICY_SUM_INTO_SHARED 

Add each value of each map of the terminated process to the corresponding key of the shared map group of the map channel.

When the addition would overflow the effective value type of the map group, the result wraps around (modular arithmetic) and LTTng sets the overflow flag of the corresponding shared map value (see lttng_map_values_signed_int_has_overflow_at_index()).

◆ lttng_map_channel_descriptor_status

enum lttng_map_channel_descriptor_status

Status code for map channel descriptor property accessors.

Enumerator
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OK 

Success.

LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_UNSET 

Property is not set.

LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETER 

Unsatisfied precondition.

◆ lttng_map_channel_set_status

enum lttng_map_channel_set_status

Status code for map channel set functions.

Enumerator
LTTNG_MAP_CHANNEL_SET_STATUS_OK 

Success.

LTTNG_MAP_CHANNEL_SET_STATUS_INVALID_PARAMETER 

Unsatisfied precondition.

◆ lttng_map_channel_status

enum lttng_map_channel_status

Status code for map channel functions.

Enumerator
LTTNG_MAP_CHANNEL_STATUS_OK 

Success.

LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETER 

Unsatisfied precondition.

LTTNG_MAP_CHANNEL_STATUS_NOT_FOUND 

No matching map group found.

LTTNG_MAP_CHANNEL_STATUS_ERROR 

Other error.

◆ lttng_map_channel_type

enum lttng_map_channel_type

Type of a map channel.

Enumerator
LTTNG_MAP_CHANNEL_TYPE_KERNEL 

Linux kernel map channel.

LTTNG_MAP_CHANNEL_TYPE_USER 

User space map channel.

◆ lttng_map_channel_update_policy

enum lttng_map_channel_update_policy

Update policy of a map channel.

Enumerator
LTTNG_MAP_CHANNEL_UPDATE_POLICY_PER_EVENT 

Per matching event.

LTTNG_MAP_CHANNEL_UPDATE_POLICY_PER_RULE_MATCH 

Per event rule match.

Function Documentation

◆ lttng_map_channel_descriptor_destroy()

void lttng_map_channel_descriptor_destroy ( struct lttng_map_channel_descriptor *  descriptor)
extern

Destroys the map channel descriptor descriptor.

Parameters
[in]descriptor

Map channel descriptor to destroy.

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

◆ lttng_map_channel_descriptor_get_max_key_count()

enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_get_max_key_count ( const struct lttng_map_channel_descriptor *  descriptor,
uint64_t *  max_key_count 
)
extern

Sets *max_key_count to the maximum key count property of the map channel described by descriptor.

Parameters
[in]descriptorDescriptor of which to get the maximum key count of the described map channel.
[out]max_key_countOn success, this function sets *max_key_count to the maximum key count of the described map channel.
Return values
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • descriptor is not NULL.
  • max_key_count is not NULL.
See also
lttng_map_channel_descriptor_set_max_key_count() – Sets the maximum key count of the described map channel of a map channel descriptor.

◆ lttng_map_channel_descriptor_get_name()

enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_get_name ( const struct lttng_map_channel_descriptor *  descriptor,
const char **  name 
)
extern

Sets *name to the name of the map channel described by descriptor.

This function returns the name property of descriptor as last set with lttng_map_channel_descriptor_set_name(), or LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_UNSET when that property isn't set.

When the name property isn't set, the session daemon generates the name of the resulting map channel when you call lttng_session_add_map_channel(). That generated name is a property of the map channel itself, not of descriptor: retrieve it through lttng_map_channel_get_name() with a map channel obtained from lttng_session_list_map_channels().

Parameters
[in]descriptorDescriptor of the map channel of which to get the name.
[out]name

On success, this function sets *name to the name of the described map channel.

*name remains valid as long as descriptor exists.

Return values
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_UNSETThe name property of descriptor is not set.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • descriptor is not NULL.
  • name is not NULL.
See also
lttng_map_channel_descriptor_set_name() – Sets the name of the described map channel of a map channel descriptor.

◆ lttng_map_channel_descriptor_get_type()

enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_get_type ( const struct lttng_map_channel_descriptor *  descriptor,
enum lttng_map_channel_type *  type 
)
extern

Sets *type to the type of the map channel described by descriptor.

The function which produced descriptor (user space vs. kernel) determines its type, which selects which type-specific accessors apply.

Parameters
[in]descriptorDescriptor of which to get the type of the described map channel.
[out]typeOn success, this function sets *type to the type of the described map channel.
Return values
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • descriptor is not NULL.
  • type is not NULL.

◆ lttng_map_channel_descriptor_get_update_policy()

enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_get_update_policy ( const struct lttng_map_channel_descriptor *  descriptor,
enum lttng_map_channel_update_policy *  policy 
)
extern

Sets *policy to the update policy property of the map channel described by descriptor.

Parameters
[in]descriptorDescriptor of which to get the update policy of the described map channel.
[out]policyOn success, this function sets *policy to the update policy of the described map channel.
Return values
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • descriptor is not NULL.
  • policy is not NULL.
See also
lttng_map_channel_descriptor_set_update_policy() – Sets the update policy of the described map channel of a map channel descriptor.

◆ lttng_map_channel_descriptor_get_value_type()

enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_get_value_type ( const struct lttng_map_channel_descriptor *  descriptor,
enum lttng_map_value_type *  value_type 
)
extern

Sets *value_type to the value type of the map channel described by descriptor.

Parameters
[in]descriptorDescriptor of which to get the value type of the described map channel.
[out]value_typeOn success, this function sets *value_type to the value type of the described map channel.
Return values
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • descriptor is not NULL.
  • value_type is not NULL.

◆ lttng_map_channel_descriptor_kernel_string_key_scalar_value_create()

struct lttng_map_channel_descriptor * lttng_map_channel_descriptor_kernel_string_key_scalar_value_create ( enum lttng_map_value_type  value_type)
extern

Creates a descriptor of a Linux kernel map channel whose maps have string keys and scalar values.

On success, the returned descriptor has the following initial properties:

Property Value Setter
Name Unset lttng_map_channel_descriptor_set_name()
Type LTTNG_MAP_CHANNEL_TYPE_KERNEL Not applicable
Key type LTTNG_MAP_KEY_TYPE_STRING Not applicable
Value type value_type Not applicable
Maximum key count 4096 lttng_map_channel_descriptor_set_max_key_count()
Update policy LTTNG_MAP_CHANNEL_UPDATE_POLICY_PER_EVENT lttng_map_channel_descriptor_set_update_policy()
Parameters
[in]value_typeValue type of the map entries of the described map channel.
Returns

Linux kernel map channel descriptor on success, or NULL on error.

Destroy the returned descriptor with lttng_map_channel_descriptor_destroy().

Precondition
See also
lttng_map_channel_descriptor_user_string_key_scalar_value_create() – Creates a descriptor of a user space map channel whose maps have string keys and scalar values.

◆ lttng_map_channel_descriptor_set_max_key_count()

enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_set_max_key_count ( struct lttng_map_channel_descriptor *  descriptor,
uint64_t  max_key_count 
)
extern

Sets the maximum key count property of the map channel described by descriptor to max_key_count.

The maximum key count caps the number of distinct keys which the described map channel may track. It also determines the size of each contained map.

Parameters
[in]descriptorDescriptor of which to set the maximum key count of the described map channel to max_key_count.
[in]max_key_countMaximum key count property to set.
Return values
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • descriptor is not NULL.
  • max_key_count is greater than 0.
See also
lttng_map_channel_descriptor_get_max_key_count() – Returns the maximum key count of the described map channel of a map channel descriptor.

◆ lttng_map_channel_descriptor_set_name()

enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_set_name ( struct lttng_map_channel_descriptor *  descriptor,
const char *  name 
)
extern

Sets the name of the map channel described by descriptor to a copy of name.

The name property of a map channel descriptor is initially unset. When you call lttng_session_add_map_channel() with a descriptor having no name, the session daemon automatically generates a name for the resulting map channel. The generated name is a property of the map channel itself, not of descriptor: retrieve it through lttng_map_channel_get_name() with a map channel obtained from lttng_session_list_map_channels().

Parameters
[in]descriptorDescriptor of which to set the name of the described map channel to a copy of name.
[in]nameName property to set (copied).
Return values
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • descriptor is not NULL.
  • name is not NULL.
See also
lttng_map_channel_descriptor_get_name() – Returns the name of the described map channel of a map channel descriptor.

◆ lttng_map_channel_descriptor_set_update_policy()

enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_set_update_policy ( struct lttng_map_channel_descriptor *  descriptor,
enum lttng_map_channel_update_policy  policy 
)
extern

Sets the update policy property of the map channel described by descriptor to policy.

Parameters
[in]descriptorDescriptor of which to set the update policy of the described map channel to policy.
[in]policyUpdate policy property to set.
Return values
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • descriptor is not NULL.
See also
lttng_map_channel_descriptor_get_update_policy() – Returns the update policy of the described map channel of a map channel descriptor.

◆ lttng_map_channel_descriptor_user_get_buffer_ownership()

enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_user_get_buffer_ownership ( const struct lttng_map_channel_descriptor *  descriptor,
enum lttng_map_channel_buffer_ownership *  ownership_model 
)
extern

Sets *ownership_model to the buffer ownership model of the user space map channel described by descriptor.

Parameters
[in]descriptorDescriptor of which to get the buffer ownership model of the described user space map channel.
[out]ownership_modelOn success, this function sets *ownership_model to the buffer ownership model of the described map channel.
Return values
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition

◆ lttng_map_channel_descriptor_user_get_dead_group_policy()

enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_user_get_dead_group_policy ( const struct lttng_map_channel_descriptor *  descriptor,
enum lttng_map_channel_dead_group_policy *  policy 
)
extern

Sets *policy to the dead group policy property of the user space map channel described by descriptor.

Parameters
[in]descriptorDescriptor of which to get the dead group policy of the described user space map channel.
[out]policyOn success, this function sets *policy to the dead group policy of the described map channel.
Return values
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
See also
lttng_map_channel_descriptor_user_set_dead_group_policy() – Sets the dead group policy of the described user space map channel of a map channel descriptor.

◆ lttng_map_channel_descriptor_user_set_dead_group_policy()

enum lttng_map_channel_descriptor_status lttng_map_channel_descriptor_user_set_dead_group_policy ( struct lttng_map_channel_descriptor *  descriptor,
enum lttng_map_channel_dead_group_policy  policy 
)
extern

Sets the dead group policy property of the user space map channel described by descriptor to policy.

The dead group policy controls what LTTng does with the values of the maps of an instrumented process when this process terminates while the described map channel still exists. It only applies to a user space map channel whose buffer ownership model is LTTNG_MAP_CHANNEL_BUFFER_OWNERSHIP_PER_PID.

Parameters
[in]descriptorDescriptor of which to set the dead group policy of the described user space map channel to policy.
[in]policyDead group policy property to set.
Return values
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_DESCRIPTOR_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
See also
lttng_map_channel_descriptor_user_get_dead_group_policy() – Returns the dead group policy of the described user space map channel of a map channel descriptor.

◆ lttng_map_channel_descriptor_user_string_key_scalar_value_create()

struct lttng_map_channel_descriptor * lttng_map_channel_descriptor_user_string_key_scalar_value_create ( enum lttng_map_value_type  value_type,
enum lttng_map_channel_buffer_ownership  ownership_model 
)
extern

Creates a descriptor of a user space map channel whose maps have string keys and scalar values.

On success, the returned descriptor has the following initial properties:

Property Value Setter
Name Unset lttng_map_channel_descriptor_set_name()
Type LTTNG_MAP_CHANNEL_TYPE_USER Not applicable
Key type LTTNG_MAP_KEY_TYPE_STRING Not applicable
Value type value_type Not applicable
Buffer ownership model ownership_model Not applicable
Maximum key count 4096 lttng_map_channel_descriptor_set_max_key_count()
Update policy LTTNG_MAP_CHANNEL_UPDATE_POLICY_PER_EVENT lttng_map_channel_descriptor_set_update_policy()
Dead group policy LTTNG_MAP_CHANNEL_DEAD_GROUP_POLICY_SUM_INTO_SHARED lttng_map_channel_descriptor_user_set_dead_group_policy()
Parameters
[in]value_typeValue type of the map entries of the described map channel.
[in]ownership_modelBuffer ownership model of the described map channel.
Returns

User space map channel descriptor on success, or NULL on error.

Destroy the returned descriptor with lttng_map_channel_descriptor_destroy().

Precondition
See also
lttng_map_channel_descriptor_kernel_string_key_scalar_value_create() – Creates a descriptor of a kernel map channel whose maps have string keys and scalar values.

◆ lttng_map_channel_destroy()

void lttng_map_channel_destroy ( struct lttng_map_channel *  channel)
extern

Destroys the map channel channel.

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

Only use this function to release a map channel handle which you obtained from lttng_session_get_map_channel_by_name(). For channels owned by a map channel set, call lttng_map_channel_set_destroy() instead.

Parameters
[in]channel

Map channel to destroy.

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

◆ lttng_map_channel_get_groups()

enum lttng_map_channel_status lttng_map_channel_get_groups ( const struct lttng_map_channel *  channel,
struct lttng_map_group_set **  groups 
)
extern

Sets *groups to the map groups of channel.

*groups is a "snapshot" taken at call time: LTTng doesn't update it as map groups are added to or removed from channel afterwards.

The contents of *groups depend on the type and, for a user space map channel, the buffer ownership model of channel:

Linux kernel map channel

Exactly one LTTNG_MAP_GROUP_TYPE_KERNEL_GLOBAL group (the system-wide group).

A Linux kernel map channel has no shared map group: that's a user space map channel concept.

User space map channel with per-user buffer ownership

User space map channel with per-process buffer ownership

A user space map channel always has a shared map group (LTTNG_MAP_GROUP_TYPE_SHARED), regardless of its buffer ownership model; a Linux kernel map channel never has one. When it exists, reach it directly without iterating *groups with lttng_map_channel_get_shared_group().

Use lttng_map_group_get_type() on each member of *groups to classify it before calling type-specific accessors: lttng_map_group_user_get_owner_id() and lttng_map_group_user_get_owner_name() 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_effective_value_type() applies to a map group of any type.

Parameters
[in]channelMap channel of which to get the map groups.
[out]groups

On success, this function sets *groups to the set of every map group of channel.

Destroy *groups with lttng_map_group_set_destroy().

Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
LTTNG_MAP_CHANNEL_STATUS_ERROROther error.
Precondition

◆ lttng_map_channel_get_keys()

enum lttng_map_channel_status lttng_map_channel_get_keys ( const struct lttng_map_channel *  channel,
struct lttng_map_key_set **  keys 
)
extern

Sets *keys to the current set of keys of channel.

The mapping from key to index lives at the channel level: every map (per-partition view) which channel manages exposes the same set of values at the same indices. Use *keys to enumerate the keys of channel or to look up the index of a specific key, then use that index against any lttng_map_values obtained from a map of channel.

*keys is a "snapshot" taken at call time: the connected session daemon returns the keys which channel tracks at that moment, and LTTng doesn't update *keys as keys are added to channel afterwards.

Parameters
[in]channelMap channel of which to get the keys.
[out]keys

On success, this function sets *keys to the resulting set of keys.

Destroy *keys with lttng_map_key_set_destroy().

Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition

◆ lttng_map_channel_get_max_key_count()

enum lttng_map_channel_status lttng_map_channel_get_max_key_count ( const struct lttng_map_channel *  channel,
uint64_t *  max_key_count 
)
extern

Sets *max_key_count to the maximum key count property of channel.

The maximum key count caps the number of distinct keys which channel may track. It also determines the size of each contained map.

Parameters
[in]channelMap channel of which to get the maximum key count.
[out]max_key_countOn success, this function sets *max_key_count to the maximum key count of channel.
Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • channel is not NULL.
  • max_key_count is not NULL.

◆ lttng_map_channel_get_name()

enum lttng_map_channel_status lttng_map_channel_get_name ( const struct lttng_map_channel *  channel,
const char **  name 
)
extern

Sets *name to the name of channel.

Parameters
[in]channelMap channel of which to get the name.
[out]name

On success, this function sets *name to the name of channel.

*name remains valid as long as channel exists.

Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • channel is not NULL.
  • name is not NULL.

◆ lttng_map_channel_get_shared_group()

enum lttng_map_channel_status lttng_map_channel_get_shared_group ( const struct lttng_map_channel *  channel,
struct lttng_map_group **  group 
)
extern

Sets *group to the shared map group of channel.

A shared map group is a user space map channel concept: a Linux kernel map channel never has one. Therefore this function only applies to a user space map channel, which has exactly one shared map group: a single, channel-wide group with no owner ID (no Unix user, no process) and no per-partition decomposition.

The type of *group is always LTTNG_MAP_GROUP_TYPE_SHARED.

The shared map group is the destination of dead-process map values when the dead group policy of channel is LTTNG_MAP_CHANNEL_DEAD_GROUP_POLICY_SUM_INTO_SHARED.

The session daemon (see lttng-sessiond(8)) may also write to it directly to record values which don't originate from a tracer.

Parameters
[in]channelMap channel of which to get the shared map group.
[out]group

On success, this function sets *group to the shared map group of channel.

Destroy *group with lttng_map_group_destroy().

Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
LTTNG_MAP_CHANNEL_STATUS_ERROROther error.
Precondition
See also
lttng_map_channel_get_groups() – Returns the set of all map groups of a map channel, including the shared map group of a user space map channel.

◆ lttng_map_channel_get_type()

enum lttng_map_channel_status lttng_map_channel_get_type ( const struct lttng_map_channel *  channel,
enum lttng_map_channel_type *  type 
)
extern

Sets *type to the type of channel.

The type of channel is fixed at configuration time and selects which type-specific accessors apply to it (lttng_map_channel_user_* vs. lttng_map_channel_kernel_* functions).

Parameters
[in]channelMap channel of which to get the type.
[out]typeOn success, this function sets *type to the type of channel.
Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • channel is not NULL.
  • type is not NULL.

◆ lttng_map_channel_get_update_policy()

enum lttng_map_channel_status lttng_map_channel_get_update_policy ( const struct lttng_map_channel *  channel,
enum lttng_map_channel_update_policy *  policy 
)
extern

Sets *policy to the update policy property of channel.

Parameters
[in]channelMap channel of which to get the update policy.
[out]policyOn success, this function sets *policy to the update policy of channel.
Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • channel is not NULL.
  • policy is not NULL.

◆ lttng_map_channel_get_value_type()

enum lttng_map_channel_status lttng_map_channel_get_value_type ( const struct lttng_map_channel *  channel,
enum lttng_map_value_type *  value_type 
)
extern

Sets *value_type to the value type of channel.

Parameters
[in]channelMap channel of which to get the value type.
[out]value_typeOn success, this function sets *value_type to the value type of channel.
Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • channel is not NULL.
  • value_type is not NULL.

◆ lttng_map_channel_set_destroy()

void lttng_map_channel_set_destroy ( struct lttng_map_channel_set *  set)
extern

Destroys the map channel set set.

Parameters
[in]set

Map channel set to destroy.

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

◆ lttng_map_channel_set_get_at_index()

enum lttng_map_channel_set_status lttng_map_channel_set_get_at_index ( const struct lttng_map_channel_set *  set,
uint64_t  index,
const struct lttng_map_channel **  channel 
)
extern

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

Parameters
[in]setMap channel set of which to get a map channel.
[in]indexIndex of the map channel to get from set.
[out]channel

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

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

Return values
LTTNG_MAP_CHANNEL_SET_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_SET_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
See also
lttng_map_channel_set_get_count() – Returns the number of map channels in a map channel set.

◆ lttng_map_channel_set_get_count()

enum lttng_map_channel_set_status lttng_map_channel_set_get_count ( const struct lttng_map_channel_set *  set,
uint64_t *  count 
)
extern

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

Parameters
[in]setMap channel set of which to get the number of map channels.
[out]countOn success, this function sets *count to the number of map channels in set.
Return values
LTTNG_MAP_CHANNEL_SET_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_SET_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition
  • set is not NULL.
  • count is not NULL.
See also
lttng_map_channel_set_get_at_index() – Returns a map channel at a given index from a map channel set.

◆ lttng_map_channel_user_get_buffer_ownership()

enum lttng_map_channel_status lttng_map_channel_user_get_buffer_ownership ( const struct lttng_map_channel *  channel,
enum lttng_map_channel_buffer_ownership *  ownership_model 
)
extern

Sets *ownership_model to the buffer ownership model of the user space map channel channel.

Parameters
[in]channelUser space map channel of which to get the buffer ownership model.
[out]ownership_modelOn success, this function sets *ownership_model to the buffer ownership model of channel.
Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition

◆ lttng_map_channel_user_get_dead_group_policy()

enum lttng_map_channel_status lttng_map_channel_user_get_dead_group_policy ( const struct lttng_map_channel *  channel,
enum lttng_map_channel_dead_group_policy *  policy 
)
extern

Sets *policy to the dead group policy of the user space map channel channel.

Parameters
[in]channelPer-process user space map channel of which to get the dead group policy.
[out]policyOn success, this function sets *policy to the dead group policy of channel.
Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
Precondition

◆ lttng_map_channel_user_get_group_by_pid()

enum lttng_map_channel_status lttng_map_channel_user_get_group_by_pid ( const struct lttng_map_channel *  channel,
pid_t  pid,
struct lttng_map_group_set **  groups 
)
extern

Sets *groups to the map groups of the user space map channel channel for the process ID pid.

Depending on the value type of channel, *groups contains one or two map groups for pid:

LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32
LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64

*groups contains a single map group.

LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX
*groups may contain up to two map groups, one of the effective value type LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32 and one of the effective value type LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64.
Parameters
[in]channelPer-process user space map channel of which to get the map groups.
[in]pidProcess ID of the map groups to get from channel.
[out]groups

On success, this function sets *groups to the map groups of channel for pid.

Destroy *groups with lttng_map_group_set_destroy().

Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
LTTNG_MAP_CHANNEL_STATUS_ERROROther error.
Precondition
See also
lttng_map_channel_user_get_group_by_uid() – Returns the map groups of a user space map channel by UID.

◆ lttng_map_channel_user_get_group_by_uid()

enum lttng_map_channel_status lttng_map_channel_user_get_group_by_uid ( const struct lttng_map_channel *  channel,
uid_t  uid,
struct lttng_map_group_set **  groups 
)
extern

Sets *groups to the map groups of the user space map channel channel for the Unix user ID uid.

Depending on the value type of channel, *groups contains one or two map groups for uid:

LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32
LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64

*groups contains a single map group: all the instrumented applications of uid, whatever their bitness, contribute to it.

LTTNG_MAP_VALUE_TYPE_SIGNED_INT_MAX
*groups may contain up to two map groups, one of the effective value type LTTNG_MAP_VALUE_TYPE_SIGNED_INT_32 and one of the effective value type LTTNG_MAP_VALUE_TYPE_SIGNED_INT_64: the instrumented applications of uid contribute to the map group of their own bitness.
Parameters
[in]channelPer-user user space map channel of which to get the map groups.
[in]uidUnix user ID of the map groups to get from channel.
[out]groups

On success, this function sets *groups to the map groups of channel for uid.

Destroy *groups with lttng_map_group_set_destroy().

Return values
LTTNG_MAP_CHANNEL_STATUS_OKSuccess.
LTTNG_MAP_CHANNEL_STATUS_INVALID_PARAMETERUnsatisfied precondition.
LTTNG_MAP_CHANNEL_STATUS_ERROROther error.
Precondition
See also
lttng_map_channel_user_get_group_by_pid() – Returns the map groups of a user space map channel by PID.