X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Fevent.h;h=0f75245c91e95f9075a6a147f7cbbf0f6d7d48cf;hp=0131defcca2357063585130d20c35113d3a51c48;hb=b878f05a6e62779ddf2364d5bb51821cb6d6d572;hpb=ef0e06bcabd5f5fcf609b60d6558c2bdded5e496

diff --git a/include/lttng/event.h b/include/lttng/event.h
index 0131defcc..0f75245c9 100644
--- a/include/lttng/event.h
+++ b/include/lttng/event.h
@@ -37,6 +37,7 @@ enum lttng_event_type {
 	LTTNG_EVENT_FUNCTION_ENTRY            = 3,
 	LTTNG_EVENT_NOOP                      = 4,
 	LTTNG_EVENT_SYSCALL                   = 5,
+	LTTNG_EVENT_USERSPACE_PROBE           = 6,
 };
 
 /*
@@ -302,8 +303,30 @@ struct lttng_event_field {
 extern int lttng_list_events(struct lttng_handle *handle,
 		const char *channel_name, struct lttng_event **events);
 
+/*
+ * Create an lttng_event.
+ *
+ * This creation function, introduced in LTTng 2.11, works around
+ * the fact that the layout of the 'lttng_event' is publicly exposed.
+ *
+ * It allocates a larger object which exposes the same public fields
+ * as a 'struct lttng_event', but also allows the use of the following extended
+ * attribute setters:
+ *   - lttng_event_set_userspace_probe_location();
+ *
+ * Events created through this function must be destroyed using
+ * lttng_event_destroy().
+ *
+ * Returns a zeroed lttng_event on success, NULL on error.
+ */
 extern struct lttng_event *lttng_event_create(void);
 
+/*
+ * Destroy an lttng_event.
+ *
+ * This destruction function, introduced in LTTng 2.11, should only
+ * be used with events created by lttng_event_create().
+  */
 extern void lttng_event_destroy(struct lttng_event *event);
 
 /*
@@ -338,21 +361,24 @@ extern int lttng_event_get_exclusion_name_count(struct lttng_event *event);
 extern int lttng_event_get_exclusion_name(struct lttng_event *event,
 		size_t index, const char **exclusion_name);
 
-
 /*
  * Get the userspace probe location of a specific LTTng event.
  * If the call is successful, then a pointer to the probe location is returned.
  * If the event has no probe location a NULL pointer is returned. The caller
  * does not own the returned probe location.
  */
-extern struct lttng_userspace_probe_location *
-lttng_event_get_userspace_probe_location(struct lttng_event *event);
+extern const struct lttng_userspace_probe_location *
+lttng_event_get_userspace_probe_location(const struct lttng_event *event);
 
 /*
  * Set an LTTng event's userspace probe location.
+ *
  * If the call is successful, then the probe location is set to the event. The
  * ownership of the probe_location is given to the event.
  *
+ * Note that the event must have been created using 'lttng_event_create()' in
+ * order for this call to succeed.
+ *
  * Returns 0 on success, or a negative LTTng error code on error.
  */
 extern int lttng_event_set_userspace_probe_location(struct lttng_event *event,