include/lttng/domain.h

   1 /*
   2  * Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_DOMAIN_H
   9 #define LTTNG_DOMAIN_H
  10
  11 #ifdef __cplusplus
  12 extern "C" {
  13 #endif
  14
  15 /*!
  16 @addtogroup api_channel
  17 @{
  18 */
  19
  20 #include <lttng/constant.h>
  21 #include <lttng/lttng-export.h>
  22
  23 /*!
  24 @brief
  25     Tracing domain type (tracer type).
  26 */
  27 enum lttng_domain_type {
  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 1.x.
  41         LTTNG_DOMAIN_LOG4J = 4,
  42
  43         /// Python logging.
  44         LTTNG_DOMAIN_PYTHON = 5,
  45
  46         /// Apache Log4j 2.
  47         LTTNG_DOMAIN_LOG4J2 = 6,
  48 };
  49
  50 /*!
  51 @brief
  52     Buffering scheme of a channel.
  53
  54 See \ref api-channel-buf-scheme "Buffering scheme" to learn more.
  55 */
  56 enum lttng_buffer_type {
  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,
  65 };
  66
  67 /*
  68  * The structures should be initialized to zero before use.
  69  */
  70 #define LTTNG_DOMAIN_PADDING1 12
  71 #define LTTNG_DOMAIN_PADDING2 (LTTNG_SYMBOL_NAME_LEN + 32)
  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 */
  99 struct lttng_domain {
 100         /// Tracing domain type.
 101         enum lttng_domain_type type;
 102
 103         /*!
 104         @brief
 105             Buffering scheme of all the channels associated to this tracing
 106             domain.
 107         */
 108         enum lttng_buffer_type buf_type;
 109
 110         char padding[LTTNG_DOMAIN_PADDING1];
 111
 112         union {
 113                 pid_t pid;
 114                 char exec_name[LTTNG_NAME_MAX];
 115                 char padding[LTTNG_DOMAIN_PADDING2];
 116         } attr;
 117 };
 118
 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 */
 149 LTTNG_EXPORT extern int lttng_list_domains(const char *session_name, struct lttng_domain **domains);
 150
 151 #ifdef __cplusplus
 152 }
 153 #endif
 154
 155 #endif /* LTTNG_DOMAIN_H */