[lttng-tools.git] / include / lttng / trigger / trigger.h

/*
 * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_TRIGGER_H
#define LTTNG_TRIGGER_H

#include <sys/types.h>

struct lttng_action;
struct lttng_condition;
struct lttng_trigger;

#ifdef __cplusplus
extern "C" {
#endif

enum lttng_register_trigger_status {
	LTTNG_REGISTER_TRIGGER_STATUS_OK = 0,
	LTTNG_REGISTER_TRIGGER_STATUS_INVALID = -1,
};

enum lttng_trigger_status {
	LTTNG_TRIGGER_STATUS_OK = 0,
	LTTNG_TRIGGER_STATUS_ERROR = -1,
	LTTNG_TRIGGER_STATUS_UNKNOWN = -2,
	LTTNG_TRIGGER_STATUS_INVALID = -3,
	LTTNG_TRIGGER_STATUS_UNSET = -4,
	LTTNG_TRIGGER_STATUS_UNSUPPORTED = -5,
	LTTNG_TRIGGER_STATUS_PERMISSION_DENIED = -6,
};

/*
 * Create a trigger object associating a condition and an action.
 *
 * A trigger associates a condition and an action to take whenever the
 * condition evaluates to true. Such actions can, for example, consist
 * in the emission of a notification to clients listening through
 * notification channels.
 *
 * The caller retains the ownership of both the condition and action
 * and both must be kept alive for the lifetime of the trigger object.
 *
 * A trigger must be registered in order to become activate and can
 * be destroyed after its registration.
 *
 * Returns a trigger object on success, NULL on error.
 * Trigger objects must be destroyed using the lttng_trigger_destroy()
 * function.
 */
extern struct lttng_trigger *lttng_trigger_create(
		struct lttng_condition *condition, struct lttng_action *action);

/*
 * Set the user identity (uid) of a trigger.
 *
 * Only available for the root user (uid 0).
 *
 * Returns LTTNG_TRIGGER_STATUS_OK on success,
 * LTTNG_TRIGGER_STATUS_EPERM if not authorized,
 * LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed.
 */
extern enum lttng_trigger_status lttng_trigger_set_owner_uid(
		struct lttng_trigger *trigger, uid_t uid);

/*
 * Get the user identity (uid) of a trigger.
 *
 * Returns LTTNG_TRIGGER_STATUS_OK on success,
 * LTTNG_TRIGGER_STATUS_UNSET if unset,
 * LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed.
 */
extern enum lttng_trigger_status lttng_trigger_get_owner_uid(
		const struct lttng_trigger *trigger, uid_t *uid);

/*
 * Get the condition of a trigger.
 *
 * The caller acquires no ownership of the returned condition.
 *
 * Returns a condition on success, NULL on error.
 */
extern struct lttng_condition *lttng_trigger_get_condition(
		struct lttng_trigger *trigger);

/*
 * Get the action of a trigger.
 *
 * The caller acquires no ownership of the returned action.
 *
 * Returns an action on success, NULL on error.
 */
extern struct lttng_action *lttng_trigger_get_action(
		struct lttng_trigger *trigger);

/*
 * Destroy (frees) a trigger object.
 */
extern void lttng_trigger_destroy(struct lttng_trigger *trigger);

/*
 * Register a trigger to the session daemon.
 *
 * The trigger can be destroyed after this call.
 *
 * Return 0 on success, a negative LTTng error code on error.
 */
extern int lttng_register_trigger(struct lttng_trigger *trigger);

/*
 * Unregister a trigger from the session daemon.
 *
 * The trigger can be destroyed after this call.
 *
 * Return 0 on success, a negative LTTng error code on error.
 */
extern int lttng_unregister_trigger(struct lttng_trigger *trigger);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_TRIGGER_H */
Commit	Line	Data
a58c490f	1	/*
ab5be9fa	2	* Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
a58c490f	3	*
ab5be9fa	4	* SPDX-License-Identifier: LGPL-2.1-only
a58c490f	5	*
a58c490f JG	6	*/
	7
	8	#ifndef LTTNG_TRIGGER_H
	9	#define LTTNG_TRIGGER_H
	10
64eafdf6 JR	11	#include <sys/types.h>
64eafdf6 JR	12
a58c490f JG	13	struct lttng_action;
	14	struct lttng_condition;
	15	struct lttng_trigger;
	16
	17	#ifdef __cplusplus
	18	extern "C" {
	19	#endif
	20
	21	enum lttng_register_trigger_status {
	22	LTTNG_REGISTER_TRIGGER_STATUS_OK = 0,
	23	LTTNG_REGISTER_TRIGGER_STATUS_INVALID = -1,
	24	};
	25
64eafdf6 JR	26	enum lttng_trigger_status {
	27	LTTNG_TRIGGER_STATUS_OK = 0,
	28	LTTNG_TRIGGER_STATUS_ERROR = -1,
	29	LTTNG_TRIGGER_STATUS_UNKNOWN = -2,
	30	LTTNG_TRIGGER_STATUS_INVALID = -3,
	31	LTTNG_TRIGGER_STATUS_UNSET = -4,
	32	LTTNG_TRIGGER_STATUS_UNSUPPORTED = -5,
	33	LTTNG_TRIGGER_STATUS_PERMISSION_DENIED = -6,
	34	};
	35
75984389 JG	36	/*
	37	* Create a trigger object associating a condition and an action.
	38	*
	39	* A trigger associates a condition and an action to take whenever the
	40	* condition evaluates to true. Such actions can, for example, consist
	41	* in the emission of a notification to clients listening through
	42	* notification channels.
	43	*
	44	* The caller retains the ownership of both the condition and action
	45	* and both must be kept alive for the lifetime of the trigger object.
	46	*
	47	* A trigger must be registered in order to become activate and can
	48	* be destroyed after its registration.
	49	*
	50	* Returns a trigger object on success, NULL on error.
	51	* Trigger objects must be destroyed using the lttng_trigger_destroy()
	52	* function.
	53	*/
a58c490f JG	54	extern struct lttng_trigger *lttng_trigger_create(
	55	struct lttng_condition condition, struct lttng_action action);
	56
64eafdf6 JR	57	/*
	58	* Set the user identity (uid) of a trigger.
	59	*
	60	* Only available for the root user (uid 0).
	61	*
	62	* Returns LTTNG_TRIGGER_STATUS_OK on success,
	63	* LTTNG_TRIGGER_STATUS_EPERM if not authorized,
	64	* LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed.
	65	*/
	66	extern enum lttng_trigger_status lttng_trigger_set_owner_uid(
	67	struct lttng_trigger *trigger, uid_t uid);
	68
	69	/*
	70	* Get the user identity (uid) of a trigger.
	71	*
	72	* Returns LTTNG_TRIGGER_STATUS_OK on success,
	73	* LTTNG_TRIGGER_STATUS_UNSET if unset,
	74	* LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed.
	75	*/
	76	extern enum lttng_trigger_status lttng_trigger_get_owner_uid(
	77	const struct lttng_trigger trigger, uid_t uid);
	78
75984389 JG	79	/*
	80	* Get the condition of a trigger.
	81	*
	82	* The caller acquires no ownership of the returned condition.
	83	*
	84	* Returns a condition on success, NULL on error.
	85	*/
a58c490f JG	86	extern struct lttng_condition *lttng_trigger_get_condition(
	87	struct lttng_trigger *trigger);
	88
75984389 JG	89	/*
	90	* Get the action of a trigger.
	91	*
	92	* The caller acquires no ownership of the returned action.
	93	*
	94	* Returns an action on success, NULL on error.
	95	*/
a58c490f JG	96	extern struct lttng_action *lttng_trigger_get_action(
	97	struct lttng_trigger *trigger);
	98
75984389 JG	99	/*
	100	* Destroy (frees) a trigger object.
	101	*/
a58c490f JG	102	extern void lttng_trigger_destroy(struct lttng_trigger *trigger);
a58c490f JG	103
75984389 JG	104	/*
	105	* Register a trigger to the session daemon.
	106	*
	107	* The trigger can be destroyed after this call.
	108	*
	109	* Return 0 on success, a negative LTTng error code on error.
	110	*/
a58c490f JG	111	extern int lttng_register_trigger(struct lttng_trigger *trigger);
a58c490f JG	112
75984389 JG	113	/*
	114	* Unregister a trigger from the session daemon.
	115	*
	116	* The trigger can be destroyed after this call.
	117	*
	118	* Return 0 on success, a negative LTTng error code on error.
	119	*/
a58c490f JG	120	extern int lttng_unregister_trigger(struct lttng_trigger *trigger);
	121
	122	#ifdef __cplusplus
	123	}
	124	#endif
	125
	126	#endif /* LTTNG_TRIGGER_H */