liblttd/liblttd.h

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