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 * This structure contains the data associated with the channel file descriptor.
  27 * The lib user can use user_data to store the data associated to the specified
  28 * channel. The lib user can read but MUST NOT change the other attributes.
  29 */
  30 struct fd_pair {
  31         /**
  32         * This is the channel file descriptor.
  33         */
  34         int channel;
  35
  36         /**
  37         * This is the number of subbuffer for this channel.
  38         */
  39         unsigned int n_sb;
  40
  41         /**
  42         * This is the subbuffer size for this channel.
  43         */
  44         unsigned int max_sb_size;
  45
  46         /**
  47         * Not used anymore.
  48         */
  49         void *mmap;
  50
  51         /**
  52         * This is a mutex for internal library usage.
  53         */
  54         pthread_mutex_t mutex;
  55
  56         /**
  57         * Library user data.
  58         */
  59         void *user_data;
  60 };
  61
  62 /**
  63 * This structure contains the necessary callbacks for a tracing session. The
  64 * user can set the unnecessary functions to NULL if he does not need them.
  65 */
  66 struct liblttd_callbacks {
  67         /**
  68         * This callback is called after a channel file is open.
  69         *
  70         * @args data This argument is a pointeur to the callbacks struct that
  71         *            has been passed to the lib.
  72         * @args pair This structure contains the data associated with the
  73         *            channel file descriptor. The lib user can use user_data to
  74         *            store the data associated to the specified channel.
  75         * @args relative_channel_path This argument represents a relative path
  76         *            to the channel file. This path is relative to the root
  77         *            folder of the trace channels.
  78         *
  79         * @return Should return 0 if the callback succeeds else not 0.
  80         */
  81         int(*on_open_channel)(struct liblttd_callbacks *data,
  82                 struct fd_pair *pair, char *relative_channel_path);
  83
  84         /**
  85         * This callback is called after a channel file is closed.
  86         *
  87         * @remarks After a channel file has been closed, it will never be read
  88         *            again.
  89         *
  90         * @args data This argument is a pointeur to the callbacks struct that
  91         *            has been passed to the lib.
  92         * @args pair This structure contains the data associated with the
  93         *            channel file descriptor. The lib user should clean
  94         *            user_data at this time.
  95         *
  96         * @return Should return 0 if the callback succeeds else not 0.
  97         */
  98         int(*on_close_channel)(struct liblttd_callbacks *data,
  99                 struct fd_pair *pair);
 100
 101
 102         /**
 103         * This callback is called when the library enter in a new subfolder
 104         * while it is scanning the trace channel tree. It can be used to create
 105         * the output file structure of the trace.
 106         *
 107         * @args data This argument is a pointeur to the callbacks struct that
 108         *            has been passed to the lib.
 109         * @args relative_folder_path This argument represents a relative path
 110         *            to the channel folder. This path is relative to the root
 111         *            folder of the trace channels.
 112         *
 113         * @return Should return 0 if the callback succeeds else not 0.
 114         */
 115         int(*on_new_channels_folder)(struct liblttd_callbacks *data,
 116                 char *relative_folder_path);
 117
 118         /**
 119         * This callback is called after a subbuffer is a reserved.
 120         *
 121         * @attention It has to be thread safe, it'll be called by many threads.
 122         *
 123         * @args data This argument is a pointeur to the callbacks struct that
 124         *            has been passed to the lib.
 125         * @args pair This structure contains the data associated with the
 126         *            channel file descriptor. The lib user should clean
 127         *            user_data at this time.
 128         * @args len This argument represents the length the data that has to be
 129         *            read.
 130         *
 131         * @return Should return 0 if the callback succeeds else not 0.
 132         */
 133         int(*on_read_subbuffer)(struct liblttd_callbacks *data,
 134                 struct fd_pair *pair, unsigned int len);
 135
 136         /**
 137         * This callback is called at the very end of the tracing session. At
 138         * this time, all the channels have been closed and the threads have been
 139         * destroyed.
 140         *
 141         * @remarks After this callback is called, no other callback will be
 142         *            called again.
 143         *
 144         * @attention It has to be thread safe, it'll be called by many threads.
 145         *
 146         * @args data This argument is a pointeur to the callbacks struct that
 147         *            has been passed to the lib.
 148         *
 149         * @return Should return 0 if the callback succeeds else not 0.
 150         */
 151         int(*on_trace_end)(struct liblttd_callbacks *data);
 152
 153         /**
 154         * This callback is called after a new thread has been created.
 155         *
 156         * @attention It has to be thread safe, it'll be called by many threads.
 157         *
 158         * @args data This argument is a pointeur to the callbacks struct that
 159         *            has been passed to the lib.
 160         * @args thread_num This argument represents the id of the thread.
 161         *
 162         * @return Should return 0 if the callback succeeds else not 0.
 163         */
 164         int(*on_new_thread)(struct liblttd_callbacks *data,
 165                 unsigned long thread_num);
 166
 167         /**
 168         * This callback is called just before a thread is destroyed.
 169         *
 170         * @attention It has to be thread safe, it'll be called by many threads.
 171         *
 172         * @args data This argument is a pointeur to the callbacks struct that
 173         *            has been passed to the lib.
 174         * @args thread_num This argument represents the number of the thread.
 175         *
 176         * @return Should return 0 if the callback succeeds else not 0.
 177         */
 178         int(*on_close_thread)(struct liblttd_callbacks *data,
 179                 unsigned long thread_num);
 180
 181         /**
 182         * This is where the user can put the library's data.
 183         */
 184         void *user_data;
 185 };
 186
 187 /**
 188 * This function is called to start a new tracing session.
 189 *
 190 * @attention It has to be thread safe, it'll be called by many threads.
 191 *
 192 * @args channel_path This argument is a path to the root folder of the trace's
 193 *            channels.
 194 * @args n_threads This argument represents the number of threads that will be
 195 *            used by the library.
 196 * @args flight_only If this argument to set to 1, only the channel that are in
 197 *            flight recorder mode will be recorded.
 198 * @args normal_only If this argument to set to 1, only the channel that are in
 199 *            normal mode will be recorded.
 200 * @args verbose If this argument to set to 1, more informations will be printed.
 201 * @args user_data This argument is a pointeur to the callbacks struct that
 202 *            contains the user's functions.
 203 *
 204 * @return Return 0 if the function succeeds else not 0.
 205 */
 206 int liblttd_start(char *channel_path, unsigned long n_threads,
 207         int flight_only, int normal_only, int verbose,
 208         struct liblttd_callbacks *user_data);
 209
 210 /**
 211 * This function is called to stop a tracing session.
 212 *
 213 * @return Return 0 if the function succeeds.
 214 */
 215 int liblttd_stop();
 216
 217 #endif /*_LIBLTTD_H */
 218