+See the \ref api-tir-trace-prop-env "environment" property.
+
+@param[in] trace
+ Trace of which to get the number of environment entries.
+
+@returns
+ Number of environment entries in \bt_p{trace}.
+
+@bt_pre_not_null{trace}
+*/
+extern uint64_t bt_trace_get_environment_entry_count(const bt_trace *trace);
+
+/*!
+@brief
+ Borrows the environment entry at index \bt_p{index} from the
+ trace \bt_p{trace}, setting \bt_p{*name} to its name and
+ \bt_p{*value} to its value.
+
+See the \ref api-tir-trace-prop-env "environment" property.
+
+@param[in] trace
+ Trace from which to borrow the environment entry at index
+ \bt_p{index}.
+@param[in] index
+ Index of the environment entry to borrow from \bt_p{trace}.
+@param[in] name
+ @parblock
+ <strong>On success</strong>, \bt_p{*name} is the name of the
+ environment entry at index \bt_p{index} in \bt_p{trace}.
+
+ The returned pointer remains valid as long as \bt_p{trace}
+ is not modified.
+ @endparblock
+@param[in] value
+ @parblock
+ <strong>On success</strong>, \bt_p{*value} is a \em borrowed
+ reference of the environment entry at index \bt_p{index} in
+ \bt_p{trace}.
+
+ \bt_p{*value} is either a \bt_sint_val
+ (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
+ (#BT_VALUE_TYPE_STRING).
+
+ The returned pointer remains valid as long as \bt_p{trace}
+ is not modified.
+ @endparblock
+
+@bt_pre_not_null{trace}
+@pre
+ \bt_p{index} is less than the number of environment entries in
+ \bt_p{trace} (as returned by
+ bt_trace_get_environment_entry_count()).
+@bt_pre_not_null{name}
+@bt_pre_not_null{value}
+
+@sa bt_trace_get_environment_entry_count() —
+ Returns the number of environment entries contained in a trace.
+*/
+extern void bt_trace_borrow_environment_entry_by_index_const(
+ const bt_trace *trace, uint64_t index,
+ const char **name, const bt_value **value);
+
+/*!
+@brief
+ Borrows the value of the environment entry named \bt_p{name}
+ in the trace \bt_p{trace}.
+
+See the \ref api-tir-trace-prop-env "environment" property.
+
+If there's no environment entry named \bt_p{name} in \bt_p{trace}, this
+function returns \c NULL.
+
+@param[in] trace
+ Trace from which to borrow the value of the environment entry
+ named \bt_p{name}.
+@param[in] name
+ Name of the environment entry to borrow from \bt_p{trace}.
+
+@returns
+ @parblock
+ \em Borrowed reference of the value of the environment entry named
+ \bt_p{name} in \bt_p{trace}.
+
+ The returned value is either a \bt_sint_val
+ (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
+ (#BT_VALUE_TYPE_STRING).
+
+ The returned pointer remains valid as long as \bt_p{trace}
+ is not modified.
+ @endparblock
+
+@bt_pre_not_null{trace}
+@bt_pre_not_null{name}
+*/
+extern const bt_value *bt_trace_borrow_environment_entry_value_by_name_const(
+ const bt_trace *trace, const char *name);
+
+/*!
+@brief
+ Sets the user attributes of the trace \bt_p{trace} to
+ \bt_p{user_attributes}.
+
+See the \ref api-tir-trace-prop-user-attrs "user attributes"
+property.
+
+@note
+ When you create a default trace with bt_trace_create(), the trace's
+ initial user attributes is an empty \bt_map_val. Therefore you can
+ borrow it with bt_trace_borrow_user_attributes() and fill it
+ directly instead of setting a new one with this function.
+
+@param[in] trace
+ Trace of which to set the user attributes to \bt_p{user_attributes}.
+@param[in] user_attributes
+ New user attributes of \bt_p{trace}.
+
+@bt_pre_not_null{trace}
+@bt_pre_hot{trace}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_trace_borrow_user_attributes() —
+ Borrows the user attributes of a trace.
+*/
+extern void bt_trace_set_user_attributes(
+ bt_trace *trace, const bt_value *user_attributes);
+
+/*!
+@brief
+ Borrows the user attributes of the trace \bt_p{trace}.
+
+See the \ref api-tir-trace-prop-user-attrs "user attributes"
+property.
+
+@note
+ When you create a default trace with bt_trace_create(), the trace's
+ initial user attributes is an empty \bt_map_val.
+
+@param[in] trace
+ Trace from which to borrow the user attributes.
+
+@returns
+ User attributes of \bt_p{trace} (a \bt_map_val).
+
+@bt_pre_not_null{trace}
+
+@sa bt_trace_set_user_attributes() —
+ Sets the user attributes of a trace.
+@sa bt_trace_borrow_user_attributes_const() —
+ \c const version of this function.
+*/
+extern bt_value *bt_trace_borrow_user_attributes(bt_trace *trace);
+
+/*!
+@brief
+ Borrows the user attributes of the trace \bt_p{trace}
+ (\c const version).
+
+See bt_trace_borrow_user_attributes().
+*/
+extern const bt_value *bt_trace_borrow_user_attributes_const(
+ const bt_trace *trace);
+
+/*! @} */
+
+/*!
+@name Listeners
+@{
+*/
+
+/*!
+@brief
+ User function for bt_trace_add_destruction_listener().
+
+This is the user function type for a trace destruction listener.
+
+@param[in] trace
+ Trace being destroyed (\ref api-fund-freezing "frozen").
+@param[in] user_data
+ User data, as passed as the \bt_p{user_data} parameter of
+ bt_trace_add_destruction_listener().
+
+@bt_pre_not_null{trace}
+
+@post
+ The reference count of \bt_p{trace} is not changed.
+@bt_post_no_error
+
+@sa bt_trace_add_destruction_listener() —
+ Adds a destruction listener to a trace.
+*/
+typedef void (* bt_trace_destruction_listener_func)(
+ const bt_trace *trace, void *user_data);
+
+/*!
+@brief
+ Status codes for bt_trace_add_destruction_listener().
+*/
+typedef enum bt_trace_add_listener_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_TRACE_ADD_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_trace_add_listener_status;
+
+/*!
+@brief
+ Adds a destruction listener having the function \bt_p{user_func}
+ to the trace \bt_p{trace}.
+
+All the destruction listener user functions of a trace are called
+when it's being destroyed.
+
+If \bt_p{listener_id} is not \c NULL, then this function, on success,
+sets \bt_p{*listener_id} to the ID of the added destruction listener
+within \bt_p{trace}. You can then use this ID to remove the
+added destruction listener with bt_trace_remove_destruction_listener().
+
+@param[in] trace
+ Trace to add the destruction listener to.
+@param[in] user_func
+ User function of the destruction listener to add to
+ \bt_p{trace}.
+@param[in] user_data
+ User data to pass as the \bt_p{user_data} parameter of
+ \bt_p{user_func}.
+@param[out] listener_id
+ <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
+ is the ID of the added destruction listener within
+ \bt_p{trace}.
+
+@retval #BT_TRACE_ADD_LISTENER_STATUS_OK
+ Success.
+@retval #BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
+ Out of memory.
+
+@bt_pre_not_null{trace}
+@bt_pre_not_null{user_func}
+
+@sa bt_trace_remove_destruction_listener() —
+ Removes a destruction listener from a trace.
+*/
+extern bt_trace_add_listener_status bt_trace_add_destruction_listener(
+ const bt_trace *trace,
+ bt_trace_destruction_listener_func user_func,
+ void *user_data, bt_listener_id *listener_id);
+
+/*!
+@brief
+ Status codes for bt_trace_remove_destruction_listener().
+*/
+typedef enum bt_trace_remove_listener_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_TRACE_REMOVE_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_trace_remove_listener_status;
+
+/*!
+@brief
+ Removes the destruction listener having the ID \bt_p{listener_id}
+ from the trace \bt_p{trace}.
+
+The destruction listener to remove from \bt_p{trace} was
+previously added with bt_trace_add_destruction_listener().
+
+You can call this function when \bt_p{trace} is
+\ref api-fund-freezing "frozen".
+
+@param[in] trace
+ Trace from which to remove the destruction listener having
+ the ID \bt_p{listener_id}.
+@param[in] listener_id
+ ID of the destruction listener to remove from \bt_p{trace}.
+
+@retval #BT_TRACE_REMOVE_LISTENER_STATUS_OK
+ Success.
+@retval #BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
+ Out of memory.
+
+@bt_pre_not_null{trace}
+@pre
+ \bt_p{listener_id} is the ID of an existing destruction listener
+ in \bt_p{trace}.
+
+@sa bt_trace_add_destruction_listener() —
+ Adds a destruction listener to a trace.
+*/
+extern bt_trace_remove_listener_status bt_trace_remove_destruction_listener(
+ const bt_trace *trace, bt_listener_id listener_id);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+ Increments the \ref api-fund-shared-object "reference count" of
+ the trace \bt_p{trace}.
+
+@param[in] trace
+ @parblock
+ Trace of which to increment the reference count.
+
+ Can be \c NULL.
+ @endparblock
+
+@sa bt_trace_put_ref() —
+ Decrements the reference count of a trace.
+*/
+extern void bt_trace_get_ref(const bt_trace *trace);
+
+/*!
+@brief
+ Decrements the \ref api-fund-shared-object "reference count" of
+ the trace \bt_p{trace}.
+
+@param[in] trace
+ @parblock
+ Trace of which to decrement the reference count.
+
+ Can be \c NULL.
+ @endparblock
+
+@sa bt_trace_get_ref() —
+ Increments the reference count of a trace.
+*/
+extern void bt_trace_put_ref(const bt_trace *trace);
+
+/*!
+@brief
+ Decrements the reference count of the trace
+ \bt_p{_trace}, and then sets \bt_p{_trace} to \c NULL.
+
+@param _trace
+ @parblock
+ Trace of which to decrement the reference count.
+
+ Can contain \c NULL.
+ @endparblock
+
+@bt_pre_assign_expr{_trace}
+*/
+#define BT_TRACE_PUT_REF_AND_RESET(_trace) \
+ do { \
+ bt_trace_put_ref(_trace); \
+ (_trace) = NULL; \
+ } while (0)
+
+/*!
+@brief
+ Decrements the reference count of the trace \bt_p{_dst}, sets
+ \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a trace reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+ @parblock
+ Destination expression.
+
+ Can contain \c NULL.
+ @endparblock
+@param _src
+ @parblock
+ Source expression.
+
+ Can contain \c NULL.
+ @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_TRACE_MOVE_REF(_dst, _src) \
+ do { \
+ bt_trace_put_ref(_dst); \
+ (_dst) = (_src); \
+ (_src) = NULL; \
+ } while (0)
+
+/*! @} */
+
+/*! @} */