Trigger API

Collaboration diagram for Trigger API:

Modules
	Trigger condition API
	Trigger action API

Data Structures
struct	lttng_trigger
	Trigger (opaque type). More...
struct	lttng_triggers
	Trigger list (opaque type). More...

Enumerations
enum	lttng_trigger_status {   LTTNG_TRIGGER_STATUS_OK , LTTNG_TRIGGER_STATUS_ERROR , LTTNG_TRIGGER_STATUS_UNKNOWN , LTTNG_TRIGGER_STATUS_UNSUPPORTED ,   LTTNG_TRIGGER_STATUS_INVALID , LTTNG_TRIGGER_STATUS_UNSET , LTTNG_TRIGGER_STATUS_PERMISSION_DENIED }
	Return type of trigger API functions. More...

Functions
enum lttng_error_code	lttng_list_triggers (struct lttng_triggers **triggers)
	Sets *triggers to a list of available triggers.
enum lttng_error_code	lttng_register_trigger_with_automatic_name (struct lttng_trigger *trigger)
	Registers the trigger trigger to the session daemon with a generated unique name.
enum lttng_error_code	lttng_register_trigger_with_name (struct lttng_trigger *trigger, const char *name)
	Registers the trigger trigger to the session daemon with the name name.
struct lttng_trigger *	lttng_trigger_create (struct lttng_condition *condition, struct lttng_action *action)
	Creates a trigger to attempt to execute the action action when the condition condition is satisfied.
void	lttng_trigger_destroy (struct lttng_trigger *trigger)
	Destroys the trigger trigger.
struct lttng_action *	lttng_trigger_get_action (struct lttng_trigger *trigger)
	Returns the action of the trigger trigger.
struct lttng_condition *	lttng_trigger_get_condition (struct lttng_trigger *trigger)
	Returns the condition of the trigger trigger.
const struct lttng_action *	lttng_trigger_get_const_action (const struct lttng_trigger *trigger)
	Returns the action of the trigger trigger (const version).
const struct lttng_condition *	lttng_trigger_get_const_condition (const struct lttng_trigger *trigger)
	Returns the condition of the trigger trigger (const version).
enum lttng_trigger_status	lttng_trigger_get_name (const struct lttng_trigger *trigger, const char **name)
	Sets *name to the name of the trigger trigger.
enum lttng_trigger_status	lttng_trigger_get_owner_uid (const struct lttng_trigger *trigger, uid_t *uid)
	Sets *uid to the owner Unix user ID (UID) of the trigger trigger.
enum lttng_trigger_status	lttng_trigger_set_owner_uid (struct lttng_trigger *trigger, uid_t uid)
	Sets the owner Unix user ID (UID) of the trigger trigger to uid.
void	lttng_triggers_destroy (struct lttng_triggers *triggers)
	Destroys the trigger list triggers.
const struct lttng_trigger *	lttng_triggers_get_at_index (const struct lttng_triggers *triggers, unsigned int index)
	Returns the trigger of the trigger list triggers at the index index.
enum lttng_trigger_status	lttng_triggers_get_count (const struct lttng_triggers *triggers, unsigned int *count)
	Sets *count to the number of triggers contained in the trigger list triggers.
int	lttng_unregister_trigger (const struct lttng_trigger *trigger)
	Unregisters the trigger trigger from the session daemon.

Detailed Description

A trigger associates a condition to an action.

When the condition of a trigger is satisfied, LTTng attempts to execute its action.

A trigger belongs to a session daemon (see lttng-sessiond(8) and Session daemon connection), not to a specific recording session.

To create and register a trigger:

1. Create the condition and action objects.

   If you need LTTng to execute more than one action when the trigger condition is satisfied, then use an action list.

2. Create the trigger object with lttng_trigger_create(), passing the condition and action of step 1.

3. Register the trigger to the connected session daemon with one of:

   Let LTTng assign an automatic trigger name

   lttng_register_trigger_with_automatic_name()

   Set a unique trigger name

   lttng_register_trigger_with_name()

4. When you're done with the trigger object, destroy it with lttng_trigger_destroy().

For a given session daemon, each Unix user has its own, private triggers. Note, however, that the root Unix user may, for the root session daemon:

• Add a trigger as another Unix user and remove a trigger which belongs to another Unix user.

  See lttng_trigger_set_owner_uid().

• List all the triggers, regardless of their owner.

Unregister a trigger with lttng_unregister_trigger().

To list the available triggers your Unix user has access to:

1. Get the trigger list with lttng_list_triggers().

2. Get triggers from the list with lttng_triggers_get_count() and lttng_triggers_get_at_index().

   Get the condition and action of a such a trigger with lttng_trigger_get_const_condition() and lttng_trigger_get_const_action().

3. When you're done with the trigger list, destroy it with lttng_triggers_destroy().

See also

• The “TRIGGER” section of lttng-concepts(7).
• lttng-add-trigger(1)
• lttng-list-triggers(1)
• lttng-remove-trigger(1)

Enumeration Type Documentation

lttng_trigger_status

enum lttng_trigger_status

Return type of trigger API functions.

Enumerator
LTTNG_TRIGGER_STATUS_OK	Success.
LTTNG_TRIGGER_STATUS_ERROR	Error.
LTTNG_TRIGGER_STATUS_INVALID	Unsatisfied precondition.
LTTNG_TRIGGER_STATUS_UNSET	Not set.
LTTNG_TRIGGER_STATUS_PERMISSION_DENIED	Permission denied.

Function Documentation

lttng_list_triggers()

enum lttng_error_code lttng_list_triggers ( struct lttng_triggers **  triggers )

extern

Sets *triggers to a list of available triggers.

This function connects to the session daemon to list triggers.

The available triggers are, depending on your Unix user ID (UID):

0 (root)

All the triggers of the session daemon to connect to.

Other UID UID

Only the triggers having the owner UID UID.

Parameters

[out]

triggers

On success, this function sets *triggers to a list of available triggers. Destroy the returned trigger list with lttng_triggers_destroy().

Returns

LTTNG_OK

Success

Another lttng_error_code enumerator

Error

Precondition

• liblttng-ctl can connect to a session daemon.
• triggers is not NULL.

See also

lttng_triggers_get_count() – Get the length of a trigger list.

lttng_triggers_get_at_index() – Get a trigger from a trigger list by index.

lttng_register_trigger_with_automatic_name()

enum lttng_error_code lttng_register_trigger_with_automatic_name ( struct lttng_trigger *  trigger )

extern

Registers the trigger trigger to the session daemon with a generated unique name.

This function connects to the session daemon to register trigger.

If lttng_trigger_get_owner_uid() returns LTTNG_TRIGGER_STATUS_UNSET with trigger, then this function sets your current UID as the owner UID for trigger.

Parameters

[in]

trigger

Trigger to register to the session daemon (not moved). It's safe to destroy trigger with lttng_trigger_destroy() after calling this function.

Returns

LTTNG_OK

Success

Another lttng_error_code enumerator

Error

Precondition

• liblttng-ctl can connect to a session daemon.
• trigger is not NULL.
• You created trigger with lttng_trigger_create().
• The condition and action of trigger are valid. The documentation of each trigger condition and action creation function indicates how to build a valid condition/action.
• If the condition of trigger isn't an “event rule matches” condition, then each “increment map value” action of trigger:
  • Targets a LTTNG_MAP_CHANNEL_TYPE_USER map channel.
  • Has a literal key template (no placeholder).
• Your Unix user ID (UID) is either 0 (root) or the same as the owner UID of trigger.

See also

lttng_register_trigger_with_name() – Register a trigger with a specific name.

lttng_unregister_trigger() – Unregister a trigger.

lttng_register_trigger_with_name()

enum lttng_error_code lttng_register_trigger_with_name ( struct lttng_trigger *  trigger, const char *  name  )

extern

Registers the trigger trigger to the session daemon with the name name.

This function connects to the session daemon to register trigger.

If lttng_trigger_get_owner_uid() returns LTTNG_TRIGGER_STATUS_UNSET with trigger, then this function sets your current UID as the owner UID for trigger.

Parameters

[in]	trigger	Trigger to register to the session daemon (not moved). It's safe to destroy trigger with lttng_trigger_destroy() after calling this function.
[in]	name	Name of the trigger to register (copied).

Returns

LTTNG_OK

Success

Another lttng_error_code enumerator

Error

Precondition

• liblttng-ctl can connect to a session daemon.
• trigger is not NULL.
• You created trigger with lttng_trigger_create().
• The condition and action of trigger are valid. The documentation of each trigger condition and action creation function indicates how to build a valid condition/action.
• If the condition of trigger isn't an “event rule matches” condition, then each “increment map value” action of trigger:
  • Targets an LTTNG_MAP_CHANNEL_TYPE_USER map channel.
  • Has a literal key template (no placeholders).
• Your Unix user ID (UID) is either 0 (root) or the same as the owner UID of trigger.
• name is not NULL.
• No other trigger with the same owner UID has the name name.

See also

lttng_register_trigger_with_automatic_name() – Register a trigger with a generated unique name.

lttng_unregister_trigger() – Unregister a trigger.

lttng_trigger_create()

struct lttng_trigger * lttng_trigger_create ( struct lttng_condition *  condition, struct lttng_action *  action  )

extern

Creates a trigger to attempt to execute the action action when the condition condition is satisfied.

This function only creates the trigger object, but doesn't register it to the LTTng session daemon: use lttng_register_trigger_with_automatic_name() or lttng_register_trigger_with_name().

Parameters

[in]	condition	Condition of the trigger to create (not moved).
[in]	action	Action of the trigger to create (not moved). If you need LTTng to execute more than one action when condition is satisfied, then use an action list.

Returns

Trigger on success, or NULL on error.

Destroy the returned trigger with lttng_trigger_destroy().

Precondition

• condition is not NULL.
• action is not NULL.

lttng_trigger_destroy()

void lttng_trigger_destroy ( struct lttng_trigger *  trigger )

extern

Destroys the trigger trigger.

Parameters

[in]

trigger

Trigger to destroy. May be NULL.

lttng_trigger_get_action()

struct lttng_action * lttng_trigger_get_action ( struct lttng_trigger *  trigger )

extern

Returns the action of the trigger trigger.

Parameters

[in]

trigger

Trigger of which to get the action.

Returns

Action of trigger, or NULL on error.

trigger owns the returned action.

The returned action remains valid as long as trigger exists.

Precondition

• trigger is not NULL.

lttng_trigger_get_condition()

struct lttng_condition * lttng_trigger_get_condition ( struct lttng_trigger *  trigger )

extern

Returns the condition of the trigger trigger.

Parameters

[in]

trigger

Trigger of which to get the condition.

Returns

Condition of trigger, or NULL on error.

trigger owns the returned condition.

The returned condition remains valid as long as trigger exists.

Precondition

• trigger is not NULL.

lttng_trigger_get_const_action()

const struct lttng_action * lttng_trigger_get_const_action ( const struct lttng_trigger *  trigger )

extern

Returns the action of the trigger trigger (const version).

Parameters

[in]

trigger

Trigger of which to get the action.

Returns

Action of trigger, or NULL on error.

trigger owns the returned action.

The returned action remains valid as long as trigger exists.

Precondition

• trigger is not NULL.

lttng_trigger_get_const_condition()

const struct lttng_condition * lttng_trigger_get_const_condition ( const struct lttng_trigger *  trigger )

extern

Returns the condition of the trigger trigger (const version).

Parameters

[in]

trigger

Trigger of which to get the condition.

Returns

Condition of trigger, or NULL on error.

trigger owns the returned condition.

The returned condition remains valid as long as trigger exists.

Precondition

• trigger is not NULL.

lttng_trigger_get_name()

enum lttng_trigger_status lttng_trigger_get_name ( const struct lttng_trigger *  trigger, const char **  name  )

extern

Sets *name to the name of the trigger trigger.

Parameters

[in]	trigger	Trigger of which to get the name.
[out]	name	On success, this function sets *name to the name of trigger. trigger owns *name. *name remains valid until the next function call with trigger.

Return values

LTTNG_TRIGGER_STATUS_OK	Success.
LTTNG_TRIGGER_STATUS_UNSET	trigger has no name.
LTTNG_TRIGGER_STATUS_INVALID	Unsatisfied precondition.

Precondition

• trigger is not NULL.
• name is not NULL.

lttng_trigger_get_owner_uid()

enum lttng_trigger_status lttng_trigger_get_owner_uid ( const struct lttng_trigger *  trigger, uid_t *  uid  )

extern

Sets *uid to the owner Unix user ID (UID) of the trigger trigger.

Parameters

[in]	trigger	Trigger of which to get the owner UID.
[out]	uid	On success, this function sets *uid to the owner UID of trigger.

Return values

LTTNG_TRIGGER_STATUS_OK	Success.
LTTNG_TRIGGER_STATUS_UNSET	trigger has no specific owner UID.
LTTNG_TRIGGER_STATUS_INVALID	Unsatisfied precondition.

Precondition

• trigger is not NULL.
• uid is not NULL.

See also

lttng_trigger_set_owner_uid() – Set the owner UID of a trigger.

lttng_trigger_set_owner_uid()

enum lttng_trigger_status lttng_trigger_set_owner_uid ( struct lttng_trigger *  trigger, uid_t  uid  )

extern

Sets the owner Unix user ID (UID) of the trigger trigger to uid.

This function can only succeed if your Unix user is root and you're connecting to a root LTTng session daemon.

When you register trigger with lttng_register_trigger_with_name() or lttng_register_trigger_with_automatic_name() after calling this function, it's equivalent to some process of Unix user uid, part of the tracing group, doing it.

Parameters

[in]	trigger	Trigger of which to set the owner UID to uid.
[in]	uid	Owner UID of trigger.

Return values

LTTNG_TRIGGER_STATUS_OK	Success.
LTTNG_TRIGGER_STATUS_PERMISSION_DENIED	Permission denied.
LTTNG_TRIGGER_STATUS_INVALID	Unsatisfied precondition.

Precondition

• Your Unix user is root (UID 0).
• trigger is not NULL.
• trigger isn't registered yet (you didn't call lttng_register_trigger_with_name() or lttng_register_trigger_with_automatic_name() with it).

See also

lttng_trigger_get_owner_uid() – Get the owner UID of a trigger.

lttng_triggers_destroy()

void lttng_triggers_destroy ( struct lttng_triggers *  triggers )

extern

Destroys the trigger list triggers.

Parameters

[in]

triggers

Trigger list to destroy. May be NULL.

lttng_triggers_get_at_index()

const struct lttng_trigger * lttng_triggers_get_at_index ( const struct lttng_triggers *  triggers, unsigned int  index  )

extern

Returns the trigger of the trigger list triggers at the index index.

Parameters

[in]	triggers	Trigger list of which to get the trigger at the index index.
[in]	index	Index of the trigger to get from triggers.

Returns

Trigger of the triggers triggers at the index index, or NULL on error.

triggers owns the returned trigger.

The returned trigger remains valid as long as triggers exists.

Precondition

• triggers is not NULL.
• index is less than the number of triggers (as returned by lttng_triggers_get_count()) of triggers.

See also

lttng_triggers_get_count() – Get the length of a trigger list.

lttng_triggers_get_count()

enum lttng_trigger_status lttng_triggers_get_count ( const struct lttng_triggers *  triggers, unsigned int *  count  )

extern

Sets *count to the number of triggers contained in the trigger list triggers.

Parameters

[in]	triggers	Trigger list of which to get the number of contained triggers.
[out]	count	On success, this function sets *count to the number of triggers in triggers.

Return values

LTTNG_TRIGGER_STATUS_OK	Success.
LTTNG_TRIGGER_STATUS_INVALID	Unsatisfied precondition.

Precondition

• triggers is not NULL.
• count is not NULL.

See also

lttng_triggers_get_at_index() – Get a trigger from a trigger list by index.

lttng_unregister_trigger()

int lttng_unregister_trigger ( const struct lttng_trigger *  trigger )

extern

Unregisters the trigger trigger from the session daemon.

This function connects to the session daemon to unregister trigger.

Parameters

[in]

trigger

Trigger to unregister from the session daemon (not moved). It's safe to destroy trigger with lttng_trigger_destroy() after calling this function.

Returns

0

Success

Negative lttng_error_code enumerator

Error

Precondition

• liblttng-ctl can connect to a session daemon.
• trigger is not NULL.
• trigger is currently registered to the session daemon to connect to.
• Your Unix user ID (UID) is either 0 (root) or the same as the owner UID of trigger.

See also

lttng_register_trigger_with_automatic_name() – Register a trigger with a generated unique name.

lttng_register_trigger_with_name() – Register a trigger with a specific name.