include/lttng/handle.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_HANDLE_H
   9 #define LTTNG_HANDLE_H
  10
  11 #include <lttng/domain.h>
  12 #include <lttng/lttng-export.h>
  13
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 /*!
  19 @addtogroup api_session
  20 @{
  21 */
  22
  23 /*
  24  * Handle used as a context for commands.
  25  *
  26  * The structures should be initialized to zero before use.
  27  */
  28 #define LTTNG_HANDLE_PADDING1 16
  29
  30 /*!
  31 @brief
  32     Recording session handle.
  33
  34 Such a structure is a pair of a \ref api_session "recording session"
  35 name and a \ref api-channel-domain "tracing domain" summary.
  36
  37 Some functions which accept a recording session handle parameter ignore
  38 the recording session name or the tracing domain summary.
  39
  40 Create a recording session handle with lttng_create_handle().
  41
  42 Destroy a recording session handle with lttng_destroy_handle().
  43 */
  44 struct lttng_handle {
  45         /// \ref api_session "Recording session" name.
  46         char session_name[LTTNG_NAME_MAX];
  47
  48         /// \ref api-channel-domain "Tracing domain" summary.
  49         struct lttng_domain domain;
  50
  51         char padding[LTTNG_HANDLE_PADDING1];
  52 };
  53
  54 /*!
  55 @brief
  56     Creates and returns a recording session handle from the
  57     \ref api_session "recording session" name
  58     \lt_p{session_name} and the optional
  59     \ref api-channel-domain "tracing domain" summary \lt_p{domain}.
  60
  61 @param[in] session_name
  62     @parblock
  63     Recording session name part of the recording session handle to
  64     create.
  65
  66     May be \c NULL.
  67     @endparblock
  68 @param[in] domain
  69     @parblock
  70     Tracing domain summary part of the recording session handle to
  71     create.
  72
  73     May be \c NULL.
  74     @endparblock
  75
  76 @returns
  77     @parblock
  78     New recording session handle.
  79
  80     Destroy the returned handle with lttng_destroy_handle().
  81     @endparblock
  82
  83 @sa lttng_destroy_handle() --
  84     Destroys a recording session handle.
  85 */
  86 LTTNG_EXPORT extern struct lttng_handle *lttng_create_handle(const char *session_name,
  87                                                              struct lttng_domain *domain);
  88
  89 /*!
  90 @brief
  91     Destroys the recording session handle \lt_p{handle}.
  92
  93 @note
  94     @parblock
  95     This function doesn't destroy the recording session named
  96     \lt_p{handle->session_name}, but only the handle itself.
  97
  98     Use lttng_destroy_session_ext() to destroy a recording session.
  99     @endparblock
 100
 101 @param[in] handle
 102     @parblock
 103     Recording session handle to destroy.
 104
 105     May be \c NULL.
 106     @endparblock
 107 */
 108 LTTNG_EXPORT extern void lttng_destroy_handle(struct lttng_handle *handle);
 109
 110 /// @}
 111
 112 #ifdef __cplusplus
 113 }
 114 #endif
 115
 116 #endif /* LTTNG_HANDLE_H */