fix: relayd: unaligned access in trace_chunk_registry_ht_key_hash

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

diff --git a/include/lttng/domain.h b/include/lttng/domain.h
index a9c4e6399653f2441ba18d73419d86853b85add3..26e9da93206ec2128a64f81688210c21425c14c4 100644 (file)
--- a/include/lttng/domain.h
+++ b/include/lttng/domain.h
@@ -1,18 +1,8 @@
 /*
- * Copyright (C) 2014 - David Goulet <dgoulet@efficios.com>
+ * Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
  *
- * This library is free software; you can redistribute it and/or modify it
- * under the terms of the GNU Lesser General Public License, version 2.1 only,
- * as published by the Free Software Foundation.
+ * SPDX-License-Identifier: LGPL-2.1-only
  *
- * This library is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- * for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this library; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
 #ifndef LTTNG_DOMAIN_H
@@ -22,51 +12,138 @@
 extern "C" {
 #endif
 
+/*!
+@addtogroup api_channel
+@{
+*/
+
 #include <lttng/constant.h>
+#include <lttng/lttng-export.h>
 
-/*
- * Domain types: the different possible tracers.
- */
+/*!
+@brief
+    Tracing domain type (tracer type).
+*/
 enum lttng_domain_type {
-       LTTNG_DOMAIN_KERNEL                   = 1,      /* Linux Kernel tracer. */
-       LTTNG_DOMAIN_UST                      = 2,      /* Global Userspace tracer. */
-       LTTNG_DOMAIN_JUL                      = 3,      /* Java Util Logging. */
+       /// 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,
 };
 
-/* Buffer type for a specific domain. */
+/*!
+@brief
+    Buffering scheme of a channel.
+
+See \ref api-channel-buf-scheme "Buffering scheme" to learn more.
+*/
 enum lttng_buffer_type {
-       LTTNG_BUFFER_PER_PID,   /* Only supported by UST being the default. */
-       LTTNG_BUFFER_PER_UID,   /* Only supported by UST. */
-       LTTNG_BUFFER_GLOBAL,    /* Only supported by the Kernel. */
+       /// 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
+#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[NAME_MAX];
+               char exec_name[LTTNG_NAME_MAX];
                char padding[LTTNG_DOMAIN_PADDING2];
        } attr;
 };
 
-/*
- * List the registered domain(s) of a session.
- *
- * Session name CAN NOT be NULL.
- *
- * Return the size (number of entries) of the "lttng_domain" array. Caller
- * must free domains. On error, a negative LTTng error code is returned.
- */
-extern int lttng_list_domains(const char *session_name,
-               struct lttng_domain **domains);
+/// @}
+
+/*!
+@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
 }