“Start recording session” trigger action API

Collaboration diagram for “Start recording session” trigger action API:

Functions
struct lttng_action *	lttng_action_start_session_create (void)
	Creates an initial “start recording session” trigger action.
enum lttng_action_status	lttng_action_start_session_get_rate_policy (const struct lttng_action *action, const struct lttng_rate_policy **policy)
	Sets *policy to the rate policy of the “start recording session” trigger action action.
enum lttng_action_status	lttng_action_start_session_get_session_name (const struct lttng_action *action, const char **session_name)
	Sets *session_name to the target recording session name of the “start recording session” trigger action action.
enum lttng_action_status	lttng_action_start_session_set_rate_policy (struct lttng_action *action, const struct lttng_rate_policy *policy)
	Sets the rate policy of the “start recording session” trigger action action to policy.
enum lttng_action_status	lttng_action_start_session_set_session_name (struct lttng_action *action, const char *session_name)
	Sets the target recording session name (to start) of the “start recording session” trigger action action to session_name.

Detailed Description

A “start recording session” trigger action starts a specific recording session when its containing trigger fires.

LTTng finds the recording session to start by name when it executes the action.

Executing this action is equivalent to calling lttng_start_tracing() with the same recording session name.

A “start recording session” trigger action has the type LTTNG_ACTION_TYPE_START_SESSION.

To create a valid “start recording session” trigger action:

1. Create the initial trigger action with lttng_action_start_session_create().
2. Set the target recording session name with lttng_action_start_session_set_session_name().

Get the target recording session name of a “start recording session” trigger action with lttng_action_start_session_get_session_name().

Set and get the rate policy of a “start recording session” trigger action with lttng_action_start_session_set_rate_policy() and lttng_action_start_session_get_rate_policy().

Function Documentation

lttng_action_start_session_create()

struct lttng_action * lttng_action_start_session_create ( void  )

extern

Creates an initial “start recording session” trigger action.

On success, the returned trigger action isn't valid yet; you must set a target recording session name with lttng_action_start_session_set_session_name().

The initial rate policy of the returned trigger action is “every time”. Set a new rate policy with lttng_action_start_session_set_rate_policy().

Returns

Trigger action with the type LTTNG_ACTION_TYPE_START_SESSION on success, or NULL on error.

Destroy the returned trigger action with lttng_action_destroy().

lttng_action_start_session_get_rate_policy()

enum lttng_action_status lttng_action_start_session_get_rate_policy ( const struct lttng_action *  action, const struct lttng_rate_policy **  policy  )

extern

Sets *policy to the rate policy of the “start recording session” trigger action action.

Parameters

[in]	action	“Start recording session” trigger action of which to get the rate policy.
[out]	policy	On success, this function sets *policy to the rate policy of action. action owns *policy. *policy remains valid until the next function call with action.

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_START_SESSION.
• policy is not NULL.

See also

lttng_action_start_session_set_rate_policy() – Set the rate policy of a “start recording session” trigger action.

lttng_action_start_session_get_session_name()

enum lttng_action_status lttng_action_start_session_get_session_name ( const struct lttng_action *  action, const char **  session_name  )

extern

Sets *session_name to the target recording session name of the “start recording session” trigger action action.

Parameters

[in]	action	“Start recording session” trigger action of which to get the target recording session name.
[out]	session_name	On success, this function sets *session_name to the target recording session name of action. action owns *session_name. *session_name remains valid until the next function call with action.

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_START_SESSION.
• session_name is not NULL.

See also

lttng_action_start_session_set_session_name() – Set the target recording session name of a “start recording session” trigger action.

lttng_action_start_session_set_rate_policy()

enum lttng_action_status lttng_action_start_session_set_rate_policy ( struct lttng_action *  action, const struct lttng_rate_policy *  policy  )

extern

Sets the rate policy of the “start recording session” trigger action action to policy.

Parameters

[in]	action	“Start recording session” trigger action of which to set the rate policy.
[in]	policy	Rate policy of action (copied).

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.
LTTNG_ACTION_STATUS_ERROR	Memory error.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_START_SESSION.
• policy is not NULL.

See also

lttng_action_start_session_get_rate_policy() – Get the rate policy of a “start recording session” trigger action.

lttng_action_start_session_set_session_name()

enum lttng_action_status lttng_action_start_session_set_session_name ( struct lttng_action *  action, const char *  session_name  )

extern

Sets the target recording session name (to start) of the “start recording session” trigger action action to session_name.

Parameters

[in]	action	“Start recording session” trigger action of which to set the target recording session name.
[in]	session_name	Target recording session name of action (copied).

Return values

LTTNG_ACTION_STATUS_OK	Success.
LTTNG_ACTION_STATUS_INVALID	Unsatisfied precondition.
LTTNG_ACTION_STATUS_ERROR	Memory error.

Precondition

• action is not NULL.
• action has the type LTTNG_ACTION_TYPE_START_SESSION.
• session_name is not NULL.

See also

lttng_action_start_session_get_session_name() – Get the target recording session name of a “start recording session” trigger action.