* The structures should be initialized to zero before use.
*/
#define LTTNG_CHANNEL_ATTR_PADDING1 LTTNG_SYMBOL_NAME_LEN + 12
+
+/*!
+@brief
+ Attributes of a \link #lttng_channel channel summary\endlink.
+
+@ingroup api_channel
+
+The lttng_channel::attr member is an instance of such a structure.
+
+lttng_channel_set_default_attr() sets the members of such a structure
+to their default values given a specific \lt_obj_domain summary.
+
+\anchor api-channel-valid-attr-struct A \em valid #lttng_channel_attr
+structure satisfies the following constraints:
+
+<table>
+ <tr>
+ <th>Member
+ <th>Constraints
+ <tr>
+ <td>lttng_channel_attr::overwrite
+ <td>0, 1, or -1
+ <tr>
+ <td>lttng_channel_attr::subbuf_size
+ <td>
+ - Greater than 0
+ - Power of two
+ <tr>
+ <td>lttng_channel_attr::num_subbuf
+ <td>
+ - Greater than 0
+ - Power of two
+</table>
+*/
struct lttng_channel_attr {
+ /*!
+ @brief
+ \ref api-channel-er-loss-mode "Event record loss mode".
+
+ One of:
+
+ <dl>
+ <dt>0
+ <dd>
+ The \ref api-channel-er-loss-mode "event record loss mode"
+ of the channel is
+ <em>\ref api-channel-discard-mode "discard"</em>.
+
+ <dt>1
+ <dd>
+ The event record loss mode of the channel is
+ <em>\ref api-channel-overwrite-mode "overwrite"</em>.
+
+ <dt>-1
+ <dd>
+ The event record loss mode of the channel is the default
+ value of its \lt_obj_session:
+
+ <dl>
+ <dt>\ref api-session-snapshot-mode "Snapshot mode"
+ <dd>Overwrite mode
+
+ <dt>Other modes
+ <dd>Discard mode
+ </dl>
+ </dl>
+ */
int overwrite; /* -1: session default, 1: overwrite, 0: discard */
+
+ /*!
+ @brief
+ \ref api-channel-sub-buf-size-count "Sub-buffer size"
+ (bytes).
+ */
uint64_t subbuf_size; /* bytes, power of 2 */
+
+ /*!
+ @brief
+ \ref api-channel-sub-buf-size-count "Sub-buffer count".
+ */
uint64_t num_subbuf; /* power of 2 */
+
+ /*!
+ @brief
+ \ref api-channel-switch-timer "Switch timer period" (µs),
+ if applicable.
+
+ Only available if the \lt_obj_session which
+ owns this channel is \em not in
+ \ref api-session-live-mode "live mode".
+ */
unsigned int switch_timer_interval; /* usec */
+
+ /// \ref api-channel-read-timer "Read timer period" (µs).
unsigned int read_timer_interval; /* usec */
+
+ /// Output type (Linux kernel channel).
enum lttng_event_output output; /* splice, mmap */
+
/* LTTng 2.1 padding limit */
+
+ /*!
+ @brief
+ \ref api-channel-max-trace-file-size-count "Maximum trace file size"
+ (bytes), or 0 for unlimited.
+ */
uint64_t tracefile_size; /* bytes */
+
+ /*!
+ @brief
+ \ref api-channel-max-trace-file-size-count "Maximum trace file count",
+ or 0 for unlimited.
+ */
uint64_t tracefile_count; /* number of tracefiles */
+
/* LTTng 2.3 padding limit */
+
+ /*!
+ @brief
+ \ref api-channel-live-timer "Live timer period" (µs), if
+ applicable.
+
+ You may \em not set this member: use the
+ \lt_p{live_timer_period} parameter of
+ lttng_session_descriptor_live_network_create() when you create
+ the descriptor of a \ref api-session-live-mode "live" recording
+ session to contain the channel to create.
+
+ Only available if the \lt_obj_session which
+ owns this channel is in \ref api-session-live-mode "live mode".
+ */
unsigned int live_timer_interval; /* usec */
+
/* LTTng 2.7 padding limit */
uint32_t align_to_64;
union {
* The structures should be initialized to zero before use.
*/
#define LTTNG_CHANNEL_PADDING1 16
+
+/*!
+@brief
+ \lt_obj_c_channel summary.
+
+@ingroup api_channel
+
+The purpose of such a structure is to provide information about a
+channel itself, but not about its \lt_obj_rers
+(use lttng_list_events() for this).
+
+lttng_list_channels() sets a pointer to an array of all the
+channel summaries of a given \lt_obj_session and \lt_obj_domain.
+
+Most properties are part of the lttng_channel::attr member, but the
+following ones have their own dedicated accessors:
+
+<dl>
+ <dt>\ref api-channel-monitor-timer "Monitor timer" period
+ <dd>
+ - lttng_channel_get_monitor_timer_interval()
+ - lttng_channel_set_monitor_timer_interval()
+
+ <dt>\ref api-channel-blocking-timeout "Blocking timeout"
+ <dd>
+ - lttng_channel_get_blocking_timeout()
+ - lttng_channel_set_blocking_timeout()
+</dl>
+
+Create a channel summary with lttng_channel_create().
+
+Destroy a channel summary with lttng_channel_destroy().
+*/
struct lttng_channel {
+ /// Name.
char name[LTTNG_SYMBOL_NAME_LEN];
+
+ /*!
+ @brief
+ 1 if this \lt_obj_channel is enabled, or 0 otherwise.
+
+ @sa lttng_enable_channel() --
+ Creates or enables a channel.
+ @sa lttng_disable_channel() --
+ Disables a channel.
+ */
uint32_t enabled;
+
+ /// Other properties.
struct lttng_channel_attr attr;
char padding[LTTNG_CHANNEL_PADDING1];
};
-/*
- */
+/*!
+@brief
+ Creates and returns a \lt_obj_channel summary,
+ setting the members of its lttng_channel::attr member to default
+ values according to the \lt_obj_domain summary \lt_p{domain}.
+
+@ingroup api_channel
+
+This function internally calls
+
+@code
+lttng_channel_set_default_attr(domain, &channel->attr);
+@endcode
+
+where \c channel is the returned channel summary.
+
+After you create a channel summary with this function, you can modify
+its \ref api-channel-channel-props "properties" and call
+lttng_enable_channel() to create and enable a channel.
+
+@param[in] domain
+ Tracing domain summary to consider to set the members of the
+ lttng_channel::attr member of the returned structure to default
+ values.
+
+@returns
+ @parblock
+ New channel summary.
+
+ Destroy the returned channel summary with lttng_channel_destroy().
+ @endparblock
+
+@lt_pre_not_null{domain}
+
+@sa lttng_channel_destroy() --
+ Destroys a channel summary.
+*/
LTTNG_EXPORT extern struct lttng_channel *lttng_channel_create(struct lttng_domain *domain);
-/*
- */
+/*!
+@brief
+ Destroys the \lt_obj_channel summary \lt_p{channel}.
+
+@ingroup api_channel
+
+@note
+ This function doesn't destroy the \lt_obj_channel
+ which \lt_p{channel} summarizes: the only way to destroy a channel
+ is to \link lttng_destroy_session_ext() destroy its recording
+ session\endlink.
+
+@param[in] channel
+ @parblock
+ Channel summary to destroy.
+
+ May be \c NULL.
+ @endparblock
+*/
LTTNG_EXPORT extern void lttng_channel_destroy(struct lttng_channel *channel);
-/*
- * List the channel(s) of a session.
- *
- * The handle CAN NOT be NULL.
- *
- * Return the size (number of entries) of the "lttng_channel" array. Caller
- * must free channels. On error, a negative LTTng error code is returned.
- */
+/*!
+@brief
+ Sets \lt_p{*channels} to the summaries of the
+ \lt_obj_channels of the recording session handle \lt_p{handle}.
+
+@ingroup api_session
+
+@param[in] handle
+ Recording session handle which contains the name of the recording
+ session and the summary of the \lt_obj_domain which own the channels
+ of which to get the summaries.
+@param[out] channels
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*channels} to
+ the summaries of the channels.
+
+ Free \lt_p{*channels} with <code>free()</code>.
+ @endparblock
+
+@returns
+ The number of items in \lt_p{*channels} on success, or a \em
+ negative #lttng_error_code enumerator otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@lt_pre_valid_c_str{handle->session_name}
+@lt_pre_sess_exists{handle->session_name}
+@pre
+ \lt_p{handle->domain} is valid as per the documentation of
+ #lttng_domain.
+@lt_pre_not_null{channels}
+*/
LTTNG_EXPORT extern int lttng_list_channels(struct lttng_handle *handle,
struct lttng_channel **channels);
-/*
- * Create or enable a channel.
- *
- * The chan and handle params can not be NULL.
- *
- * Return 0 on success else a negative LTTng error code.
- */
+/*!
+@brief
+ Creates or enables a \lt_obj_channel summarized by \lt_p{channel}
+ within the recording session handle \lt_p{handle}.
+
+@ingroup api_channel
+
+This function, depending on \lt_p{channel->name}:
+
+<dl>
+ <dt>
+ \lt_p{channel->name} names an existing
+ channel within the \lt_obj_session and
+ \lt_obj_domain of \lt_p{handle}
+ <dd>
+ Enables the existing channel.
+
+ In this case, this function only uses \lt_p{channel->name}, ignoring
+ all the other properties of \lt_p{channel}.
+
+ <dt>Otherwise
+ <dd>
+ Creates and enables a new channel, considering all the properties of
+ \lt_p{channel}.
+</dl>
+
+@param[in] handle
+ Recording session handle which contains the name of the
+ recording session and the summary of the \lt_obj_domain which own
+ the channel to create or enable.
+@param[in] channel
+ Summary of the channel to create or enable.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@lt_pre_valid_c_str{handle->session_name}
+@lt_pre_sess_exists{handle->session_name}
+@pre
+ \lt_p{handle->domain} is valid as per the documentation of
+ #lttng_domain.
+@lt_pre_not_null{channel}
+@pre
+ <strong>If this function must create a new channel</strong>, then
+ \lt_p{channel->attr} is \ref api-channel-valid-attr-struct "valid".
+@pre
+ <strong>If this function must create a new channel</strong>, then
+ \lt_p{handle->session_name} names a
+ \lt_obj_session which never became
+ \link lttng_session::enabled active\endlink (started) since its
+ creation.
+@pre
+ <strong>If this function must create a new channel</strong>, then
+ all the existing channels of \lt_p{handle} have the same
+ \ref api-channel-buf-scheme "buffering scheme".
+
+@sa lttng_disable_channel() --
+ Disables a channel.
+*/
LTTNG_EXPORT extern int lttng_enable_channel(struct lttng_handle *handle,
- struct lttng_channel *chan);
+ struct lttng_channel *channel);
-/*
- * Disable channel.
- *
- * Name and handle CAN NOT be NULL.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-LTTNG_EXPORT extern int lttng_disable_channel(struct lttng_handle *handle, const char *name);
+/*!
+@brief
+ Disables the \lt_obj_channel named \lt_p{channel_name} within the
+ recording session handle \lt_p{handle}.
-/*
- * 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.
- */
+@ingroup api_channel
+
+@param[in] handle
+ Recording session handle which contains the name of the
+ recording session and the summary of the \lt_obj_domain which own
+ the channel to disable.
+@param[in] channel_name
+ Name of the channel to disable within \lt_p{handle}.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@lt_pre_valid_c_str{handle->session_name}
+@lt_pre_sess_exists{handle->session_name}
+@pre
+ \lt_p{handle->domain} is valid as per the documentation of
+ #lttng_domain.
+@lt_pre_not_null{channel_name}
+@pre
+ \lt_p{channel_name} names an existing channel within the recording
+ session and tracing domain of \lt_p{handle}.
+
+@sa lttng_enable_channel() --
+ Creates or enables a channel.
+*/
+LTTNG_EXPORT extern int lttng_disable_channel(struct lttng_handle *handle,
+ const char *channel_name);
+
+/*!
+@brief
+ Sets the members of \lt_p{attr} to their default values considering
+ the \lt_obj_domain summary \lt_p{domain}.
+
+@ingroup api_channel
+
+Use this function on an lttng_channel::attr member.
+
+@param[in] domain
+ Tracing domain summary to consider to set the members of \lt_p{attr}
+ to their default values.
+@param[in] attr
+ Structure of which to set the members to their default values.
+
+@lt_pre_not_null{domain}
+@lt_pre_not_null{attr}
+*/
LTTNG_EXPORT extern void lttng_channel_set_default_attr(struct lttng_domain *domain,
struct lttng_channel_attr *attr);
-/*
- * Get the discarded event count of a specific LTTng channel.
- *
- * Returns 0 on success, or a negative LTTng error code on error.
- */
-LTTNG_EXPORT extern int lttng_channel_get_discarded_event_count(struct lttng_channel *chan,
- uint64_t *discarded_events);
+/*!
+@brief
+ Sets \lt_p{*count} to the number of discarded event
+ records of the \lt_obj_channel summarized by \lt_p{channel}.
-/*
- * Get the lost packet count of a specific LTTng channel.
- *
- * Returns 0 on success, or a negative LTTng error code on error.
- */
-LTTNG_EXPORT extern int lttng_channel_get_lost_packet_count(struct lttng_channel *chan,
- uint64_t *lost_packets);
+@ingroup api_channel
+
+In \ref api-channel-discard-mode "discard mode", LTTng discards an event
+record when there's no sub-buffer left to write it.
+
+lttng_list_channels() sets a pointer to an array of all the
+channel summaries of a given \lt_obj_session and \lt_obj_domain.
+
+@param[in] channel
+ Summary of the channel of which to get the number of discarded
+ event records.
+@param[out] count
+ <strong>On success</strong>, this function sets \lt_p{*count} to
+ the number of discarded event records of the channel summarized
+ by \lt_p{channel}.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{channel}
+@pre
+ You obtained \lt_p{channel} with lttng_list_channels().
+@pre
+ The lttng_channel_attr::overwrite member of \lt_p{channel->attr}
+ is 0.
+@lt_pre_not_null{count}
+
+@sa lttng_channel_get_lost_packet_count() --
+ Returns the number of discarded packets (sub-buffers) of a channel.
+*/
+LTTNG_EXPORT extern int lttng_channel_get_discarded_event_count(struct lttng_channel *channel,
+ uint64_t *count);
+
+/*!
+@brief
+ Sets \lt_p{*count} to the number of discarded packets (sub-buffers)
+ of the \lt_obj_channel summarized by \lt_p{channel}.
+
+@ingroup api_channel
+
+In \ref api-channel-overwrite-mode "overwrite mode", LTTng discards a
+whole sub-buffer when there's no sub-buffer left to record an event.
+
+lttng_list_channels() sets a pointer to an array of all the
+channel summaries of a given \lt_obj_session and \lt_obj_domain.
+
+@param[in] channel
+ Summary of the channel of which to get the number of discarded
+ packets.
+@param[out] count
+ <strong>On success</strong>, this function sets \lt_p{*count} to
+ the number of discarded packets of the channel summarized
+ by \lt_p{channel}.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{channel}
+@pre
+ You obtained \lt_p{channel} with lttng_list_channels().
+@pre
+ The lttng_channel_attr::overwrite member of \lt_p{channel->attr}
+ is 1.
+@lt_pre_not_null{count}
+
+@sa lttng_channel_get_discarded_event_count() --
+ Returns the number of discarded event records of a channel.
+*/
+LTTNG_EXPORT extern int lttng_channel_get_lost_packet_count(struct lttng_channel *channel,
+ uint64_t *count);
+
+/*!
+@brief
+ Sets \lt_p{period} to the
+ \ref api-channel-monitor-timer "monitor timer" period (µs)
+ property of the \lt_obj_channel summary \lt_p{channel}.
+
+@ingroup api_channel
+
+@param[in] channel
+ Summary of the channel of which to get the monitor timer period.
+@param[out] period
+ <strong>On success</strong>, this function sets \lt_p{*period} to
+ the monitor timer period (µs) property of \lt_p{channel}.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{channel}
+@lt_pre_not_null{period}
+
+@sa lttng_channel_set_monitor_timer_interval() --
+ Sets the monitor timer period property of a channel summary.
+*/
+LTTNG_EXPORT extern int lttng_channel_get_monitor_timer_interval(struct lttng_channel *channel,
+ uint64_t *period);
+
+/*!
+@brief
+ Sets the \ref api-channel-monitor-timer "monitor timer" period
+ property of the channel summary \lt_p{channel} to
+ \lt_p{period} µs.
+
+@ingroup api_channel
+
+@param[in] channel
+ Channel summary of which to set the monitor timer period
+ to \lt_p{period} µs.
+@param[in] period
+ Monitor timer period property to set.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{channel}
+@pre
+ \lt_p{period} ≥ 1
+
+@sa lttng_channel_get_monitor_timer_interval() --
+ Returns the monitor timer period property of a channel summary.
+*/
+LTTNG_EXPORT extern int lttng_channel_set_monitor_timer_interval(struct lttng_channel *channel,
+ uint64_t period);
+
+/*!
+@brief
+ Sets \lt_p{timeout} to the
+ \ref api-channel-blocking-timeout "blocking timeout"
+ property of the \lt_obj_channel summary \lt_p{channel}.
+
+@ingroup api_channel
+
+This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink
+channels.
+
+@param[in] channel
+ Summary of the channel of which to get the blocking timeout.
+@param[out] timeout
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*timeout} to
+ one of:
+
+ <dl>
+ <dt>-1
+ <dd>
+ The blocking timeout of \lt_p{channel} is infinite.
+
+ <dt>0
+ <dd>
+ Blocking is disabled for \lt_p{channel}.
+
+ <dt>Otherwise
+ <dd>
+ The blocking timeout of \lt_p{channel} is
+ \lt_p{*timeout} µs.
+ </dl>
+ @endparblock
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{channel}
+@pre
+ The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST.
+@lt_pre_not_null{timeout}
+
+@sa lttng_channel_set_blocking_timeout() --
+ Sets the blocking timeout property of a channel summary.
+*/
+LTTNG_EXPORT extern int lttng_channel_get_blocking_timeout(struct lttng_channel *channel,
+ int64_t *timeout);
+
+/*!
+@brief
+ Sets the \ref api-channel-blocking-timeout "blocking timeout"
+ property of the channel summary \lt_p{channel} to
+ \lt_p{timeout}.
+
+@ingroup api_channel
+
+This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink
+channels.
+
+@param[in] channel
+ Channel summary of which to set the blocking timeout
+ to \lt_p{timeout}.
+@param[in] timeout
+ @parblock
+ One of:
+
+ <dl>
+ <dt>-1
+ <dd>
+ The blocking timeout of \lt_p{channel} is infinite.
+
+ <dt>0
+ <dd>
+ Blocking is disabled for \lt_p{channel}.
-LTTNG_EXPORT extern int lttng_channel_get_monitor_timer_interval(struct lttng_channel *chan,
- uint64_t *monitor_timer_interval);
+ <dt>Otherwise
+ <dd>
+ The blocking timeout of \lt_p{channel} is
+ \lt_p{timeout} µs.
+ </dl>
+ @endparblock
-LTTNG_EXPORT extern int lttng_channel_set_monitor_timer_interval(struct lttng_channel *chan,
- uint64_t monitor_timer_interval);
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
-LTTNG_EXPORT extern int lttng_channel_get_blocking_timeout(struct lttng_channel *chan,
- int64_t *blocking_timeout);
+@lt_pre_not_null{channel}
+@pre
+ The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST.
+@pre
+ \lt_p{timeout} ≥ -1
-LTTNG_EXPORT extern int lttng_channel_set_blocking_timeout(struct lttng_channel *chan,
- int64_t blocking_timeout);
+@sa lttng_channel_get_blocking_timeout() --
+ Returns the blocking timeout property of a channel summary.
+*/
+LTTNG_EXPORT extern int lttng_channel_set_blocking_timeout(struct lttng_channel *channel,
+ int64_t timeout);
#ifdef __cplusplus
}
projects / lttng-tools.git / blobdiff