liblttd/liblttd.h

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