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.
  41         LTTNG_DOMAIN_LOG4J = 4,
  42
  43         /// Python logging.
  44         LTTNG_DOMAIN_PYTHON = 5,
  45 };
  46
  47 /*!
  48 @brief
  49     Buffering scheme of a channel.
  50
  51 See \ref api-channel-buf-scheme "Buffering scheme" to learn more.
  52 */
  53 enum lttng_buffer_type {
  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,
  62 };
  63
  64 /*
  65  * The structures should be initialized to zero before use.
  66  */
  67 #define LTTNG_DOMAIN_PADDING1 12
  68 #define LTTNG_DOMAIN_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
  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 */
  96 struct lttng_domain {
  97         /// Tracing domain type.
  98         enum lttng_domain_type type;
  99
 100         /*!
 101         @brief
 102             Buffering scheme of all the channels associated to this tracing
 103             domain.
 104         */
 105         enum lttng_buffer_type buf_type;
 106
 107         char padding[LTTNG_DOMAIN_PADDING1];
 108
 109         union {
 110                 pid_t pid;
 111                 char exec_name[LTTNG_NAME_MAX];
 112                 char padding[LTTNG_DOMAIN_PADDING2];
 113         } attr;
 114 };
 115
 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 */
 146 LTTNG_EXPORT extern int lttng_list_domains(const char *session_name, struct lttng_domain **domains);
 147
 148 #ifdef __cplusplus
 149 }
 150 #endif
 151
 152 #endif /* LTTNG_DOMAIN_H */