-extern int lttng_register_consumer(struct lttng_handle *handle,
- const char *socket_path);
-
-/*
- * Start tracing for *all* domain(s) in the session.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-extern int lttng_start_tracing(const char *session_name);
-
-/*
- * Stop tracing for *all* domain(s) in the session.
- *
- * This call will wait for data availability for each domain of the session so
- * this can take an abritrary amount of time. However, when returning you have
- * the guarantee that the data is ready to be read and analyze. Use the
- * _no_wait call below to avoid this behavior.
- *
- * The session_name can't be NULL.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-extern int lttng_stop_tracing(const char *session_name);
-
-/*
- * Behave exactly like lttng_stop_tracing but does not wait for data
- * availability.
- */
-extern int lttng_stop_tracing_no_wait(const char *session_name);
-
-/*
- * Add context to event(s) for a specific channel (or for all).
- *
- * If the channel_name is NULL and they are no channel for the domain, the
- * default channel is created (channel0). The context is then added on ALL
- * channels since no name was specified.
- *
- * The event_name is ignored since adding a context to an event is not possible
- * for now.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-extern int lttng_add_context(struct lttng_handle *handle,
- struct lttng_event_context *ctx, const char *event_name,
- const char *channel_name);
-
-/*
- * 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. If channel_name is NULL, the default channel is used
- * (channel0).
- *
- * The handle and ev params can not be NULL.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-extern int lttng_enable_event(struct lttng_handle *handle,
- struct lttng_event *ev, const char *channel_name);
-
-/*
- * Create or enable an event with a specific filter.
- *
- * If the event you are trying to enable does not exist, it will be created,
- * else it is enabled.
- * If ev is NULL, all events are enabled with that filter.
- * If channel_name is NULL, the default channel is used (channel0) and created
- * if not found.
- * If filter_expression is NULL, an event without associated filter is
- * created.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-extern int lttng_enable_event_with_filter(struct lttng_handle *handle,
- struct lttng_event *event, const char *channel_name,
- const char *filter_expression);
-
-/*
- * Create or enable an event with a filter and/or exclusions.
- *
- * If the event you are trying to enable does not exist, it will be created,
- * else it is enabled.
- * If ev is NULL, all events are enabled with the filter and exclusion options.
- * If channel_name is NULL, the default channel is used (channel0) and created
- * if not found.
- * If filter_expression is NULL, an event without associated filter is
- * created.
- * If exclusion count is zero, the event will be created without exclusions.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-extern int lttng_enable_event_with_exclusions(struct lttng_handle *handle,
- struct lttng_event *event, const char *channel_name,
- const char *filter_expression,
- int exclusion_count, char **exclusion_names);
-
-/*
- * Create or enable a channel.
- *
- * The chan and handle params can not be NULL.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-extern int lttng_enable_channel(struct lttng_handle *handle,
- struct lttng_channel *chan);
-
-/*
- * Disable event(s) of a channel and domain.
- *
- * If name is NULL, all events are disabled.
- * If channel_name is NULL, the default channel is used (channel0).
- *
- * Return 0 on success else a negative LTTng error code.
- */
-extern int lttng_disable_event(struct lttng_handle *handle,
- const char *name, const char *channel_name);
-
-/*
- * Disable channel.
- *
- * Name and handle CAN NOT be NULL.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-extern int lttng_disable_channel(struct lttng_handle *handle,
- const char *name);
-
-/*
- * Calibrate LTTng overhead.
- *
- * The chan and handle params can not be NULL.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-extern int lttng_calibrate(struct lttng_handle *handle,
- struct lttng_calibrate *calibrate);
-
-/*
- * Set the default channel attributes for a specific domain and an allocated
- * lttng_channel_attr pointer.
- *
- * If one or both arguments are NULL, nothing happens.
- */
-extern void lttng_channel_set_default_attr(struct lttng_domain *domain,
- struct lttng_channel_attr *attr);
+LTTNG_EXPORT extern int lttng_register_consumer(struct lttng_handle *handle,
+ const char *socket_path);
+
+/*!
+@brief
+ Makes the recording session named \lt_p{session_name} active,
+ starting all the tracers for its
+ \ref api-channel-channel "channels".
+
+@ingroup api_session
+
+@note
+ An #LTTNG_ACTION_TYPE_START_SESSION trigger action can also activate
+ (start) a recording session.
+
+@param[in] session_name
+ Name of the recording session to activate/start.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@lt_pre_sess_inactive{session_name}
+
+@sa lttng_stop_tracing() --
+ Stops a recording session.
+@sa \lt_man{lttng-start,1}
+*/
+LTTNG_EXPORT extern int lttng_start_tracing(const char *session_name);
+
+/*!
+@brief
+ Makes the recording session named \lt_p{session_name} inactive,
+ stopping all the tracers for its
+ \ref api-channel-channel "channels", blocking until the operation
+ completes.
+
+@ingroup api_session
+
+This function blocks until the trace data of the
+recording session named \lt_p{session_name} is valid. Use
+lttng_stop_tracing_no_wait() to avoid a blocking call.
+
+If LTTng \ref api_session_rotation "archived the current trace chunk"
+of the recording session named \lt_p{session_name} at least
+once during its lifetime, then this function renames the current trace
+chunk subdirectory. Although it's safe to
+read the content of this renamed subdirectory while the recording
+session remains inactive, it's \em not a trace chunk archive: you need to
+\link lttng_destroy_session_ext() destroy\endlink the recording session
+or a rotation needs to occur to archive it.
+
+@note
+ An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also
+ deactivate (stop) a recording session.
+
+@param[in] session_name
+ Name of the recording session to deactivate/stop.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@lt_pre_sess_active{session_name}
+
+@sa lttng_stop_tracing_no_wait() --
+ Deactivates a recording session without waiting for the operation
+ to complete.
+@sa lttng_start_tracing() --
+ Starts a recording session.
+@sa \lt_man{lttng-stop,1}
+*/
+LTTNG_EXPORT extern int lttng_stop_tracing(const char *session_name);
+
+/*!
+@brief
+ Makes the recording session named \lt_p{session_name} inactive,
+ stopping all the tracers for its
+ \ref api-channel-channel "channels" without waiting for the
+ operation to complete.
+
+@ingroup api_session
+
+Unlike lttng_stop_tracing(), this function does \em not block until
+the operation is complete: it returns immediately. This
+means the traces(s) of the recording session might not be valid when
+this function returns, and there's no way to know when it/they become
+valid.
+
+@note
+ An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also
+ deactivate (stop) a recording session.
+
+@param[in] session_name
+ Name of the recording session to deactivate/stop.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@lt_pre_sess_active{session_name}
+@pre
+ No deactivation operation is in progress for the recording session
+ named \lt_p{session_name}.
+
+@sa lttng_stop_tracing() --
+ Deactivates a recording session, blocking until the operation
+ completes.
+@sa lttng_start_tracing() --
+ Starts a recording session.
+@sa \lt_man{lttng-stop,1}
+*/
+LTTNG_EXPORT extern int lttng_stop_tracing_no_wait(const char *session_name);
+
+/*
+ * Deprecated: As of LTTng 2.9, this function always returns
+ * -LTTNG_ERR_UND.
+ */
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wshadow"
+LTTNG_EXPORT extern int lttng_calibrate(struct lttng_handle *handle,
+ struct lttng_calibrate *calibrate);
+#pragma GCC diagnostic pop