liblttd/liblttd.h

   1 /*
   2  * liblttd header file
   3  *
   4  * Copyright 2005-2010 -
   5  *               Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
   6  * Copyright 2010-
   7  *               Oumarou Dicko <oumarou.dicko@polymtl.ca>
   8  *               Michael Sills-Lavoie <michael.sills-lavoie@polymtl.ca>
   9  *
  10  * This library is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public
  12  * License as published by the Free Software Foundation; either
  13  * version 2.1 of the License, or (at your option) any later version.
  14  *
  15  * This library is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with this library; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  23  */
  24
  25 #ifndef _LIBLTTD_H
  26 #define _LIBLTTD_H
  27
  28 #include <pthread.h>
  29 #include <dirent.h>
  30 #include <fcntl.h>
  31
  32 /**
  33  * struct fd_pair - Contains the data associated with the channel file
  34  * descriptor. The lib user can use user_data to store the data associated to
  35  * the specified channel. The lib user can read but MUST NOT change the other
  36  * attributes.
  37  * @channel: channel file descriptor
  38  * @n_sb: the number of subbuffer for this channel
  39  * @max_sb_size: the subbuffer size for this channel
  40  * @mmap: Not used anymore.
  41  * @mutex: a mutex for internal library usage
  42  * @user_data: library user data
  43  * @offset: write position in the output file descriptor (optional)
  44  */
  45 struct fd_pair {
  46         int channel;
  47         unsigned int n_sb;
  48         unsigned int max_sb_size;
  49         void *mmap;
  50         pthread_mutex_t mutex;
  51         void *user_data;
  52         off_t offset;
  53 };
  54
  55 struct channel_trace_fd {
  56         struct fd_pair *pair;
  57         int num_pairs;
  58 };
  59
  60 struct inotify_watch {
  61         int wd;
  62         char path_channel[PATH_MAX];
  63         char *base_path_channel;
  64 };
  65
  66 struct inotify_watch_array {
  67         struct inotify_watch *elem;
  68         int num;
  69 };
  70
  71 struct liblttd_callbacks;
  72
  73 /**
  74  * struct liblttd_instance - Contains the data associated with a trace instance.
  75  * The lib user can read but MUST NOT change any attributes but callbacks.
  76  * @callbacks: Contains the necessary callbacks for a tracing session.
  77  */
  78 struct liblttd_instance {
  79         struct liblttd_callbacks *callbacks;
  80
  81         int inotify_fd;
  82         struct channel_trace_fd fd_pairs;
  83         struct inotify_watch_array inotify_watch_array;
  84
  85         /* protects fd_pairs and inotify_watch_array */
  86         pthread_rwlock_t fd_pairs_lock;
  87
  88         char channel_name[PATH_MAX];
  89         unsigned long num_threads;
  90         int quit_program;
  91         int dump_flight_only;
  92         int dump_normal_only;
  93         int verbose_mode;
  94 };
  95
  96 /**
  97 * struct liblttd_callbacks - Contains the necessary callbacks for a tracing
  98 * session. The user can set the unnecessary functions to NULL if he does not
  99 * need them.
 100 */
 101 struct liblttd_callbacks {
 102         /**
 103          * on_open_channel - Is called after a channel file is open.
 104          *
 105          * @data: pointer to the callbacks structure that has been passed to
 106          *        the lib.
 107          * @pair: structure that contains the data associated with the
 108          *        channel file descriptor. The library user can use user_data to
 109          *        store the data associated to the specified channel.
 110          * @relative_channel_path:
 111          *        represents a relative path to the channel file. This path is
 112          *        relative to the root folder of the trace channels.
 113          *
 114          * Returns 0 if the callback succeeds else not 0.
 115          */
 116         int (*on_open_channel)(struct liblttd_callbacks *data,
 117                                struct fd_pair *pair,
 118                                char *relative_channel_path);
 119
 120         /**
 121          * on_close_channel - Is called after a channel file is closed.
 122          *
 123          * @data: pointer to the callbacks structure that has been passed to the
 124          *        lib.
 125          * @pair: structure that contains the data associated with the channel
 126          *        file descriptor. The lib user should clean user_data at this
 127          *        time.
 128          *
 129          * Returns 0 if the callback succeeds else not 0.
 130          *
 131          * After a channel file has been closed, it will never be read again.
 132          */
 133         int (*on_close_channel)(struct liblttd_callbacks *data,
 134                                 struct fd_pair *pair);
 135
 136         /**
 137          * on_new_channels_folder - Is called when the library enter in a new
 138          * subfolder while it is scanning the trace channel tree. It can be used
 139          * to create the output file structure of the trace.
 140          *
 141          * @data: pointer to the callbacks structure that has been passed to the
 142          *        library.
 143          * @relative_folder_path:
 144          *        represents a relative path to the channel folder. This path is
 145          *        relative to the root folder of the trace channels.
 146          *
 147          * Returns 0 if the callback succeeds else not 0.
 148          */
 149         int (*on_new_channels_folder)(struct liblttd_callbacks *data,
 150                                       char *relative_folder_path);
 151
 152         /**
 153          * on_read_subbuffer - Is called after a subbuffer is a reserved.
 154          *
 155          * @data: pointer to the callbacks structure that has been passed to the
 156          *        library.
 157          * @pair: structure that contains the data associated with the channel
 158          *        file descriptor.
 159          * @len:  represents the length the data that has to be read.
 160          *
 161          * Returns 0 if the callback succeeds else not 0.
 162          *
 163          * It has to be thread safe, because it is called by many threads.
 164          */
 165         int (*on_read_subbuffer)(struct liblttd_callbacks *data,
 166                                 struct fd_pair *pair, unsigned int len);
 167
 168         /**
 169          * on_trace_en - Is called at the very end of the tracing session. At
 170          * this time, all the channels have been closed and the threads have
 171          * been destroyed.
 172          *
 173          * @instance: pointer to the instance structure that has been passed to
 174          *            the library.
 175          *
 176          * Returns 0 if the callback succeeds else not 0.
 177          *
 178          * After this callback is called, no other callback will be called
 179          * again and the tracing instance will be deleted automatically by
 180          * liblttd. After this call, the user must not use the liblttd instance.
 181          */
 182         int (*on_trace_end)(struct liblttd_instance *instance);
 183
 184         /**
 185          * on_new_thread - Is called after a new thread has been created.
 186          *
 187          * @data: pointer to the callbacks structure that has been passed to the
 188          *        lib.
 189          * @thread_num: represents the id of the thread.
 190          *
 191          * Returns 0 if the callback succeeds else not 0.
 192          *
 193          * It has to be thread safe, because it is called by many threads.
 194          */
 195         int (*on_new_thread)(struct liblttd_callbacks *data,
 196                              unsigned long thread_num);
 197
 198         /**
 199          * on_close_thread - Is called just before a thread is destroyed.
 200          *
 201          * @data: pointer to the callbacks structure that has been passed to the
 202          *        library.
 203          * @thread_num: represents the number of the thread.
 204          *
 205          * Returns 0 if the callback succeeds else not 0.
 206          *
 207          * It has to be thread safe, because it is called by many threads.
 208          */
 209         int (*on_close_thread)(struct liblttd_callbacks *data,
 210                                unsigned long thread_num);
 211
 212         /**
 213          * The library's data.
 214          */
 215         void *user_data;
 216 };
 217
 218 /**
 219  * liblttd_new_instance - Is called to create a new tracing session.
 220  *
 221  * @callbacks:    Pointer to a callbacks structure that contain the user
 222  *                callbacks and data.
 223  * @channel_path: This argument is a path to the root folder of the trace's
 224  *                channels.
 225  * @n_threads:    This argument represents the number of threads that will be
 226  *                used by the library.
 227  * @flight_only:  If this argument to set to 1, only the channel that are in
 228  *                flight recorder mode will be recorded.
 229  * @normal_only:  If this argument to set to 1, only the channel that are in
 230  *                normal mode will be recorded.
 231  * @verbose:      If this argument to set to 1, more informations will be
 232  *                printed.
 233  *
 234  * Returns the instance if the function succeeds else NULL.
 235  */
 236 struct liblttd_instance *
 237 liblttd_new_instance(struct liblttd_callbacks *callbacks, char *channel_path,
 238                      unsigned long n_threads, int flight_only, int normal_only,
 239                      int verbose);
 240
 241 /**
 242  * liblttd_start - Is called to start a new tracing session.
 243  *
 244  * @instance: The tracing session instance that needs to be started.
 245  *
 246  * Returns 0 if the function succeeds.
 247  *
 248  * This is a blocking function. The caller will be blocked on it until the
 249  * tracing session is stopped by the user using liblttd_stop_instance or until
 250  * the trace is stopped by LTTng directly.
 251  */
 252 int liblttd_start_instance(struct liblttd_instance *instance);
 253
 254 /**
 255  * liblttd_stop - Is called to stop a tracing session.
 256  *
 257  * @instance: The tracing session instance that needs to be stoped.
 258  *
 259  * Returns 0 if the function succeeds.
 260  *
 261  * This function returns immediately, it only tells liblttd to stop the
 262  * instance. The on_trace_end callback will be called when the tracing session
 263  * will really be stopped (after every thread has finished using it). The
 264  * instance is deleted automatically by liblttd after on_trace_end is called.
 265  */
 266 int liblttd_stop_instance(struct liblttd_instance *instance);
 267
 268 #endif /*_LIBLTTD_H */