X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=liblttd%2Fliblttd.h;fp=liblttd%2Fliblttd.h;h=bd76eeb58cc7e68053ac53cb582b94177b039766;hb=008e25154ca2db688516bafcb134c984f08a5f10;hp=0000000000000000000000000000000000000000;hpb=ca18ef2e5710af15e3f8b5ed424cf969bf564e07;p=ltt-control.git diff --git a/liblttd/liblttd.h b/liblttd/liblttd.h new file mode 100644 index 0000000..bd76eeb --- /dev/null +++ b/liblttd/liblttd.h @@ -0,0 +1,218 @@ +/* liblttd header file + * + * Copyright 2010- + * Oumarou Dicko + * Michael Sills-Lavoie + * + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + */ + +#ifndef _LIBLTTD_H +#define _LIBLTTD_H + +#include + +/** +* This structure contains the data associated with the channel file descriptor. +* The lib user can use user_data to store the data associated to the specified +* channel. The lib user can read but MUST NOT change the other attributes. +*/ +struct fd_pair { + /** + * This is the channel file descriptor. + */ + int channel; + + /** + * This is the number of subbuffer for this channel. + */ + unsigned int n_sb; + + /** + * This is the subbuffer size for this channel. + */ + unsigned int max_sb_size; + + /** + * Not used anymore. + */ + void *mmap; + + /** + * This is a mutex for internal library usage. + */ + pthread_mutex_t mutex; + + /** + * Library user data. + */ + void *user_data; +}; + +/** +* This structure contains the necessary callbacks for a tracing session. The +* user can set the unnecessary functions to NULL if he does not need them. +*/ +struct liblttd_callbacks { + /** + * This callback is called after a channel file is open. + * + * @args data This argument is a pointeur to the callbacks struct that + * has been passed to the lib. + * @args pair This structure contains the data associated with the + * channel file descriptor. The lib user can use user_data to + * store the data associated to the specified channel. + * @args relative_channel_path This argument represents a relative path + * to the channel file. This path is relative to the root + * folder of the trace channels. + * + * @return Should return 0 if the callback succeeds else not 0. + */ + int(*on_open_channel)(struct liblttd_callbacks *data, + struct fd_pair *pair, char *relative_channel_path); + + /** + * This callback is called after a channel file is closed. + * + * @remarks After a channel file has been closed, it will never be read + * again. + * + * @args data This argument is a pointeur to the callbacks struct that + * has been passed to the lib. + * @args pair This structure contains the data associated with the + * channel file descriptor. The lib user should clean + * user_data at this time. + * + * @return Should return 0 if the callback succeeds else not 0. + */ + int(*on_close_channel)(struct liblttd_callbacks *data, + struct fd_pair *pair); + + + /** + * This callback is called when the library enter in a new subfolder + * while it is scanning the trace channel tree. It can be used to create + * the output file structure of the trace. + * + * @args data This argument is a pointeur to the callbacks struct that + * has been passed to the lib. + * @args relative_folder_path This argument represents a relative path + * to the channel folder. This path is relative to the root + * folder of the trace channels. + * + * @return Should return 0 if the callback succeeds else not 0. + */ + int(*on_new_channels_folder)(struct liblttd_callbacks *data, + char *relative_folder_path); + + /** + * This callback is called after a subbuffer is a reserved. + * + * @attention It has to be thread safe, it'll be called by many threads. + * + * @args data This argument is a pointeur to the callbacks struct that + * has been passed to the lib. + * @args pair This structure contains the data associated with the + * channel file descriptor. The lib user should clean + * user_data at this time. + * @args len This argument represents the length the data that has to be + * read. + * + * @return Should return 0 if the callback succeeds else not 0. + */ + int(*on_read_subbuffer)(struct liblttd_callbacks *data, + struct fd_pair *pair, unsigned int len); + + /** + * This callback is called at the very end of the tracing session. At + * this time, all the channels have been closed and the threads have been + * destroyed. + * + * @remarks After this callback is called, no other callback will be + * called again. + * + * @attention It has to be thread safe, it'll be called by many threads. + * + * @args data This argument is a pointeur to the callbacks struct that + * has been passed to the lib. + * + * @return Should return 0 if the callback succeeds else not 0. + */ + int(*on_trace_end)(struct liblttd_callbacks *data); + + /** + * This callback is called after a new thread has been created. + * + * @attention It has to be thread safe, it'll be called by many threads. + * + * @args data This argument is a pointeur to the callbacks struct that + * has been passed to the lib. + * @args thread_num This argument represents the id of the thread. + * + * @return Should return 0 if the callback succeeds else not 0. + */ + int(*on_new_thread)(struct liblttd_callbacks *data, + unsigned long thread_num); + + /** + * This callback is called just before a thread is destroyed. + * + * @attention It has to be thread safe, it'll be called by many threads. + * + * @args data This argument is a pointeur to the callbacks struct that + * has been passed to the lib. + * @args thread_num This argument represents the number of the thread. + * + * @return Should return 0 if the callback succeeds else not 0. + */ + int(*on_close_thread)(struct liblttd_callbacks *data, + unsigned long thread_num); + + /** + * This is where the user can put the library's data. + */ + void *user_data; +}; + +/** +* This function is called to start a new tracing session. +* +* @attention It has to be thread safe, it'll be called by many threads. +* +* @args channel_path This argument is a path to the root folder of the trace's +* channels. +* @args n_threads This argument represents the number of threads that will be +* used by the library. +* @args flight_only If this argument to set to 1, only the channel that are in +* flight recorder mode will be recorded. +* @args normal_only If this argument to set to 1, only the channel that are in +* normal mode will be recorded. +* @args verbose If this argument to set to 1, more informations will be printed. +* @args user_data This argument is a pointeur to the callbacks struct that +* contains the user's functions. +* +* @return Return 0 if the function succeeds else not 0. +*/ +int liblttd_start(char *channel_path, unsigned long n_threads, + int flight_only, int normal_only, int verbose, + struct liblttd_callbacks *user_data); + +/** +* This function is called to stop a tracing session. +* +* @return Return 0 if the function succeeds. +*/ +int liblttd_stop(); + +#endif /*_LIBLTTD_H */ +