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

/*
 * Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_DOMAIN_H
#define LTTNG_DOMAIN_H

#ifdef __cplusplus
extern "C" {
#endif

/*!
@addtogroup api_channel
@{
*/

#include <lttng/constant.h>
#include <lttng/lttng-export.h>

/*!
@brief
    Tracing domain type (tracer type).
*/
enum lttng_domain_type {
	/// None.
	LTTNG_DOMAIN_NONE = 0,

	/// Linux kernel.
	LTTNG_DOMAIN_KERNEL = 1,

	/// User space.
	LTTNG_DOMAIN_UST = 2,

	/// <code>java.util.logging</code> (JUL).
	LTTNG_DOMAIN_JUL = 3,

	/// Apache Log4j 1.x.
	LTTNG_DOMAIN_LOG4J = 4,

	/// Python logging.
	LTTNG_DOMAIN_PYTHON = 5,

	/// Apache Log4j 2.
	LTTNG_DOMAIN_LOG4J2 = 6,
};

/*!
@brief
    Buffering scheme of a channel.

See \ref api-channel-buf-scheme "Buffering scheme" to learn more.
*/
enum lttng_buffer_type {
	/// Per-process buffering.
	LTTNG_BUFFER_PER_PID,

	/// Per-user buffering.
	LTTNG_BUFFER_PER_UID,

	/// Global (Linux kernel) buffering.
	LTTNG_BUFFER_GLOBAL,
};

/*
 * The structures should be initialized to zero before use.
 */
#define LTTNG_DOMAIN_PADDING1 12
#define LTTNG_DOMAIN_PADDING2 (LTTNG_SYMBOL_NAME_LEN + 32)

/*!
@brief
    Tracing domain summary.

Such a structure is involved:

- As a member of a \link #lttng_handle recording session handle\endlink.

  Some functions which require both a \lt_obj_session
  and a tracing domain accept an #lttng_handle structure.

- When you list the tracing domains of a recording session with
  lttng_list_domains().

- When you create a \link #lttng_channel channel summary
  structure\endlink with lttng_channel_create().

You must initialize such a structure to zeros before setting its
members and using it, for example:

@code
struct lttng_domain domain;

memset(&domain, 0, sizeof(domain));
@endcode
*/
struct lttng_domain {
	/// Tracing domain type.
	enum lttng_domain_type type;

	/*!
	@brief
	    Buffering scheme of all the channels associated to this tracing
	    domain.
	*/
	enum lttng_buffer_type buf_type;

	char padding[LTTNG_DOMAIN_PADDING1];

	union {
		pid_t pid;
		char exec_name[LTTNG_NAME_MAX];
		char padding[LTTNG_DOMAIN_PADDING2];
	} attr;
};

/// @}

/*!
@brief
    Sets \lt_p{*domains} to the summaries of the tracing domains which
    contain at least one channel within the recording session
    named \lt_p{session_name}.

@ingroup api_session

@param[in] session_name
    Name of the recording session for which to get the tracing domain
    summaries.
@param[out] domains
    @parblock
    <strong>On success</strong>, this function sets \lt_p{*domains} to
    the summaries of the tracing domains.

    Free \lt_p{*domains} with <code>free()</code>.
    @endparblock

@returns
    The number of items in \lt_p{*domains} 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_not_null{domains}
*/
LTTNG_EXPORT extern int lttng_list_domains(const char *session_name, struct lttng_domain **domains);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_DOMAIN_H */
Commit	Line	Data
1239a312	1	/*
ab5be9fa	2	* Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
1239a312	3	*
ab5be9fa	4	* SPDX-License-Identifier: LGPL-2.1-only
1239a312	5	*
1239a312 DG	6	*/
	7
	8	#ifndef LTTNG_DOMAIN_H
	9	#define LTTNG_DOMAIN_H
	10
	11	#ifdef __cplusplus
	12	extern "C" {
	13	#endif
	14
048f01ef PP	15	/*!
	16	@addtogroup api_channel
	17	@{
	18	*/
	19
1239a312	20	#include <lttng/constant.h>
4bd69c5f	21	#include <lttng/lttng-export.h>
1239a312	22
048f01ef PP	23	/*!
	24	@brief
	25	Tracing domain type (tracer type).
	26	*/
1239a312	27	enum lttng_domain_type {
048f01ef PP	28	/// None.
	29	LTTNG_DOMAIN_NONE = 0,
	30
	31	/// Linux kernel.
	32	LTTNG_DOMAIN_KERNEL = 1,
	33
	34	/// User space.
	35	LTTNG_DOMAIN_UST = 2,
	36
	37	/// <code>java.util.logging</code> (JUL).
	38	LTTNG_DOMAIN_JUL = 3,
	39
47abf22b	40	/// Apache Log4j 1.x.
048f01ef PP	41	LTTNG_DOMAIN_LOG4J = 4,
	42
	43	/// Python logging.
	44	LTTNG_DOMAIN_PYTHON = 5,
47abf22b MJ	45
	46	/// Apache Log4j 2.
	47	LTTNG_DOMAIN_LOG4J2 = 6,
1239a312 DG	48	};
1239a312 DG	49
048f01ef PP	50	/*!
	51	@brief
	52	Buffering scheme of a channel.
	53
	54	See \ref api-channel-buf-scheme "Buffering scheme" to learn more.
	55	*/
1239a312	56	enum lttng_buffer_type {
048f01ef PP	57	/// Per-process buffering.
	58	LTTNG_BUFFER_PER_PID,
	59
	60	/// Per-user buffering.
	61	LTTNG_BUFFER_PER_UID,
	62
	63	/// Global (Linux kernel) buffering.
	64	LTTNG_BUFFER_GLOBAL,
1239a312 DG	65	};
	66
	67	/*
	68	* The structures should be initialized to zero before use.
	69	*/
28f23191	70	#define LTTNG_DOMAIN_PADDING1 12
07c4863f	71	#define LTTNG_DOMAIN_PADDING2 (LTTNG_SYMBOL_NAME_LEN + 32)
048f01ef PP	72
	73	/*!
	74	@brief
	75	Tracing domain summary.
	76
	77	Such a structure is involved:
	78
	79	- As a member of a \link #lttng_handle recording session handle\endlink.
	80
	81	Some functions which require both a \lt_obj_session
	82	and a tracing domain accept an #lttng_handle structure.
	83
	84	- When you list the tracing domains of a recording session with
	85	lttng_list_domains().
	86
	87	- When you create a \link #lttng_channel channel summary
	88	structure\endlink with lttng_channel_create().
	89
	90	You must initialize such a structure to zeros before setting its
	91	members and using it, for example:
	92
	93	@code
	94	struct lttng_domain domain;
	95
	96	memset(&domain, 0, sizeof(domain));
	97	@endcode
	98	*/
1239a312	99	struct lttng_domain {
048f01ef	100	/// Tracing domain type.
1239a312	101	enum lttng_domain_type type;
048f01ef PP	102
	103	/*!
	104	@brief
	105	Buffering scheme of all the channels associated to this tracing
	106	domain.
	107	*/
1239a312	108	enum lttng_buffer_type buf_type;
048f01ef	109
1239a312 DG	110	char padding[LTTNG_DOMAIN_PADDING1];
	111
	112	union {
	113	pid_t pid;
36d2e35d	114	char exec_name[LTTNG_NAME_MAX];
1239a312 DG	115	char padding[LTTNG_DOMAIN_PADDING2];
	116	} attr;
	117	};
	118
048f01ef PP	119	/// @}
	120
	121	/*!
	122	@brief
	123	Sets \lt_p{*domains} to the summaries of the tracing domains which
	124	contain at least one channel within the recording session
	125	named \lt_p{session_name}.
	126
	127	@ingroup api_session
	128
	129	@param[in] session_name
	130	Name of the recording session for which to get the tracing domain
	131	summaries.
	132	@param[out] domains
	133	@parblock
	134	<strong>On success</strong>, this function sets \lt_p{*domains} to
	135	the summaries of the tracing domains.
	136
	137	Free \lt_p{*domains} with <code>free()</code>.
	138	@endparblock
	139
	140	@returns
	141	The number of items in \lt_p{*domains} on success, or a \em negative
	142	#lttng_error_code enumerator otherwise.
	143
	144	@lt_pre_conn
	145	@lt_pre_not_null{session_name}
	146	@lt_pre_sess_exists{session_name}
	147	@lt_pre_not_null{domains}
	148	*/
28f23191	149	LTTNG_EXPORT extern int lttng_list_domains(const char session_name, struct lttng_domain *domains);
1239a312 DG	150
	151	#ifdef __cplusplus
	152	}
	153	#endif
	154
	155	#endif /* LTTNG_DOMAIN_H */