[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.
	LTTNG_DOMAIN_LOG4J = 4,

	/// Python logging.
	LTTNG_DOMAIN_PYTHON = 5,
};

/*!
@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
	40	/// Apache log4j.
	41	LTTNG_DOMAIN_LOG4J = 4,
	42
	43	/// Python logging.
	44	LTTNG_DOMAIN_PYTHON = 5,
1239a312 DG	45	};
1239a312 DG	46
048f01ef PP	47	/*!
	48	@brief
	49	Buffering scheme of a channel.
	50
	51	See \ref api-channel-buf-scheme "Buffering scheme" to learn more.
	52	*/
1239a312	53	enum lttng_buffer_type {
048f01ef PP	54	/// Per-process buffering.
	55	LTTNG_BUFFER_PER_PID,
	56
	57	/// Per-user buffering.
	58	LTTNG_BUFFER_PER_UID,
	59
	60	/// Global (Linux kernel) buffering.
	61	LTTNG_BUFFER_GLOBAL,
1239a312 DG	62	};
	63
	64	/*
	65	* The structures should be initialized to zero before use.
	66	*/
28f23191 JG	67	#define LTTNG_DOMAIN_PADDING1 12
28f23191 JG	68	#define LTTNG_DOMAIN_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
048f01ef PP	69
	70	/*!
	71	@brief
	72	Tracing domain summary.
	73
	74	Such a structure is involved:
	75
	76	- As a member of a \link #lttng_handle recording session handle\endlink.
	77
	78	Some functions which require both a \lt_obj_session
	79	and a tracing domain accept an #lttng_handle structure.
	80
	81	- When you list the tracing domains of a recording session with
	82	lttng_list_domains().
	83
	84	- When you create a \link #lttng_channel channel summary
	85	structure\endlink with lttng_channel_create().
	86
	87	You must initialize such a structure to zeros before setting its
	88	members and using it, for example:
	89
	90	@code
	91	struct lttng_domain domain;
	92
	93	memset(&domain, 0, sizeof(domain));
	94	@endcode
	95	*/
1239a312	96	struct lttng_domain {
048f01ef	97	/// Tracing domain type.
1239a312	98	enum lttng_domain_type type;
048f01ef PP	99
	100	/*!
	101	@brief
	102	Buffering scheme of all the channels associated to this tracing
	103	domain.
	104	*/
1239a312	105	enum lttng_buffer_type buf_type;
048f01ef	106
1239a312 DG	107	char padding[LTTNG_DOMAIN_PADDING1];
	108
	109	union {
	110	pid_t pid;
36d2e35d	111	char exec_name[LTTNG_NAME_MAX];
1239a312 DG	112	char padding[LTTNG_DOMAIN_PADDING2];
	113	} attr;
	114	};
	115
048f01ef PP	116	/// @}
	117
	118	/*!
	119	@brief
	120	Sets \lt_p{*domains} to the summaries of the tracing domains which
	121	contain at least one channel within the recording session
	122	named \lt_p{session_name}.
	123
	124	@ingroup api_session
	125
	126	@param[in] session_name
	127	Name of the recording session for which to get the tracing domain
	128	summaries.
	129	@param[out] domains
	130	@parblock
	131	<strong>On success</strong>, this function sets \lt_p{*domains} to
	132	the summaries of the tracing domains.
	133
	134	Free \lt_p{*domains} with <code>free()</code>.
	135	@endparblock
	136
	137	@returns
	138	The number of items in \lt_p{*domains} on success, or a \em negative
	139	#lttng_error_code enumerator otherwise.
	140
	141	@lt_pre_conn
	142	@lt_pre_not_null{session_name}
	143	@lt_pre_sess_exists{session_name}
	144	@lt_pre_not_null{domains}
	145	*/
28f23191	146	LTTNG_EXPORT extern int lttng_list_domains(const char session_name, struct lttng_domain *domains);
1239a312 DG	147
	148	#ifdef __cplusplus
	149	}
	150	#endif
	151
	152	#endif /* LTTNG_DOMAIN_H */