Implement event fields listing

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

diff --git a/include/lttng/lttng.h b/include/lttng/lttng.h
index 065caee9146a12d2bf9f63dfff3aa0511c611641..3b1be61974bd8f60558ae34b948ef41751e1e34e 100644 (file)
--- a/include/lttng/lttng.h
+++ b/include/lttng/lttng.h
@@ -6,8 +6,8 @@
  * Copyright (C) 2011 - David Goulet <david.goulet@polymtl.ca>
  *
  * This library is free software; you can redistribute it and/or modify it
- * under the terms of the GNU Lesser General Public License as published by the
- * Free Software Foundation; only version 2.1 of the License.
+ * under the terms of the GNU Lesser General Public License, version 2.1 only,
+ * as published by the Free Software Foundation.
  *
  * This library is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@@ -124,6 +124,9 @@ enum lttng_calibrate_type {
        LTTNG_CALIBRATE_FUNCTION              = 0,
 };
 
+/*
+ * The structures should be initialized to zero before use.
+ */
 #define LTTNG_DOMAIN_PADDING1              16
 #define LTTNG_DOMAIN_PADDING2              LTTNG_SYMBOL_NAME_LEN + 32
 struct lttng_domain {
@@ -137,7 +140,11 @@ struct lttng_domain {
        } attr;
 };
 
-/* Perf counter attributes */
+/*
+ * Perf counter attributes
+ *
+ * The structures should be initialized to zero before use.
+ */
 #define LTTNG_PERF_EVENT_PADDING1          16
 struct lttng_event_perf_counter_ctx {
        uint32_t type;
@@ -147,7 +154,11 @@ struct lttng_event_perf_counter_ctx {
        char padding[LTTNG_PERF_EVENT_PADDING1];
 };
 
-/* Event/Channel context */
+/*
+ * Event/channel context
+ *
+ * The structures should be initialized to zero before use.
+ */
 #define LTTNG_EVENT_CONTEXT_PADDING1       16
 #define LTTNG_EVENT_CONTEXT_PADDING2       LTTNG_SYMBOL_NAME_LEN + 32
 struct lttng_event_context {
@@ -164,6 +175,8 @@ struct lttng_event_context {
  * Event probe.
  *
  * Either addr is used or symbol_name and offset.
+ *
+ * The structures should be initialized to zero before use.
  */
 #define LTTNG_EVENT_PROBE_PADDING1         16
 struct lttng_event_probe_attr {
@@ -177,6 +190,8 @@ struct lttng_event_probe_attr {
 
 /*
  * Function tracer
+ *
+ * The structures should be initialized to zero before use.
  */
 #define LTTNG_EVENT_FUNCTION_PADDING1      16
 struct lttng_event_function_attr {
@@ -187,6 +202,8 @@ struct lttng_event_function_attr {
 
 /*
  * Generic lttng event
+ *
+ * The structures should be initialized to zero before use.
  */
 #define LTTNG_EVENT_PADDING1               16
 #define LTTNG_EVENT_PADDING2               LTTNG_SYMBOL_NAME_LEN + 32
@@ -211,8 +228,26 @@ struct lttng_event {
        } attr;
 };
 
+enum lttng_event_field_type {
+       LTTNG_EVENT_FIELD_OTHER                 = 0,
+       LTTNG_EVENT_FIELD_INTEGER               = 1,
+       LTTNG_EVENT_FIELD_ENUM                  = 2,
+       LTTNG_EVENT_FIELD_FLOAT                 = 3,
+       LTTNG_EVENT_FIELD_STRING                = 4,
+};
+
+#define LTTNG_EVENT_FIELD_PADDING      LTTNG_SYMBOL_NAME_LEN + 32
+struct lttng_event_field {
+       char field_name[LTTNG_SYMBOL_NAME_LEN];
+       enum lttng_event_field_type type;
+       char padding[LTTNG_EVENT_FIELD_PADDING];
+       struct lttng_event event;
+};
+
 /*
  * Tracer channel attributes. For both kernel and user-space.
+ *
+ * The structures should be initialized to zero before use.
  */
 #define LTTNG_CHANNEL_ATTR_PADDING1        LTTNG_SYMBOL_NAME_LEN + 32
 struct lttng_channel_attr {
@@ -228,6 +263,8 @@ struct lttng_channel_attr {
 
 /*
  * Channel information structure. For both kernel and user-space.
+ *
+ * The structures should be initialized to zero before use.
  */
 #define LTTNG_CHANNEL_PADDING1             16
 struct lttng_channel {
@@ -251,6 +288,8 @@ struct lttng_calibrate {
  * This is an 'output data' meaning that it only comes *from* the session
  * daemon *to* the lttng client. It's basically a 'human' representation of
  * tracing entities (here a session).
+ *
+ * The structures should be initialized to zero before use.
  */
 #define LTTNG_SESSION_PADDING1             16
 struct lttng_session {
@@ -264,6 +303,8 @@ struct lttng_session {
 
 /*
  * Handle used as a context for commands.
+ *
+ * The structures should be initialized to zero before use.
  */
 #define LTTNG_HANDLE_PADDING1              16
 struct lttng_handle {
@@ -362,6 +403,15 @@ extern int lttng_list_events(struct lttng_handle *handle,
 extern int lttng_list_tracepoints(struct lttng_handle *handle,
                struct lttng_event **events);
 
+/*
+ * List the available tracepoints fields of a specific lttng domain.
+ *
+ * Return the size (number of entries) of the "lttng_event_field" array.
+ * Caller must free(3).
+ */
+extern int lttng_list_tracepoint_fields(struct lttng_handle *handle,
+               struct lttng_event_field **fields);
+
 /*
  * Check if a session daemon is alive.
  *
@@ -416,7 +466,7 @@ extern int lttng_add_context(struct lttng_handle *handle,
                const char *channel_name);
 
 /*
- * Create or enable a kernel event (or events) for a channel.
+ * Create or enable an event (or events) for a channel.
  *
  * If the event you are trying to enable does not exist, it will be created,
  * else it is enabled.
@@ -427,14 +477,14 @@ extern int lttng_enable_event(struct lttng_handle *handle,
                struct lttng_event *ev, const char *channel_name);
 
 /*
- * Create or enable a kernel channel.
+ * Create or enable a channel.
  * The channel name cannot be NULL.
  */
 extern int lttng_enable_channel(struct lttng_handle *handle,
                struct lttng_channel *chan);
 
 /*
- * Disable kernel event(s) of a channel and domain.
+ * Disable event(s) of a channel and domain.
  *
  * If event_name is NULL, all events are disabled.
  * If channel_name is NULL, the default channel is used (channel0).
@@ -443,7 +493,7 @@ extern int lttng_disable_event(struct lttng_handle *handle,
                const char *name, const char *channel_name);
 
 /*
- * Disable kernel channel.
+ * Disable channel.
  *
  * The channel name cannot be NULL.
  */