X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=liblttd%2Fliblttd.h;h=aac1e5dcd0b2bc74d095a2765ab573aa8a565cae;hb=HEAD;hp=d871dd726870a1ea26238b32b5bd1c6f1b9f7f9e;hpb=d9cbca2728d5c8df929fe464e698abc07d1876ab;p=ltt-control.git diff --git a/liblttd/liblttd.h b/liblttd/liblttd.h index d871dd7..aac1e5d 100644 --- a/liblttd/liblttd.h +++ b/liblttd/liblttd.h @@ -1,21 +1,25 @@ -/* liblttd header file +/* + * liblttd header file * - * Copyright 2005 - + * Copyright 2005-2010 - * Mathieu Desnoyers * 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 library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. * - * This program is distributed in the hope that it will be useful, + * This library 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. + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef _LIBLTTD_H @@ -23,6 +27,7 @@ #include #include +#include /** * struct fd_pair - Contains the data associated with the channel file @@ -35,6 +40,7 @@ * @mmap: Not used anymore. * @mutex: a mutex for internal library usage * @user_data: library user data + * @offset: write position in the output file descriptor (optional) */ struct fd_pair { int channel; @@ -43,6 +49,7 @@ struct fd_pair { void *mmap; pthread_mutex_t mutex; void *user_data; + off_t offset; }; struct channel_trace_fd { @@ -94,71 +101,77 @@ struct liblttd_instance { struct liblttd_callbacks { /** * on_open_channel - Is called after a channel file is open. - * @data: pointeur to the callbacks struct that has been passed to the - * lib. + * + * @data: pointer to the callbacks structure that has been passed to + * the lib. * @pair: structure that 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. - * @relative_channel_path: represents a relative path to the channel - * file. This path is relative to the root folder of the trace channels. + * channel file descriptor. The library user can use user_data to + * store the data associated to the specified channel. + * @relative_channel_path: + * represents a relative path to the channel file. This path is + * relative to the root folder of the trace channels. * * Returns 0 if the callback succeeds else not 0. */ - int(*on_open_channel)(struct liblttd_callbacks *data, - struct fd_pair *pair, char *relative_channel_path); + int (*on_open_channel)(struct liblttd_callbacks *data, + struct fd_pair *pair, + char *relative_channel_path); /** * on_close_channel - Is called after a channel file is closed. - * @data: pointeur to the callbacks struct that has been passed to the - * lib. + * + * @data: pointer to the callbacks structure that has been passed to the + * lib. * @pair: structure that contains the data associated with the channel - * file descriptor. The lib user should clean user_data at this time. + * file descriptor. The lib user should clean user_data at this + * time. * * Returns 0 if the callback succeeds else not 0. * * After a channel file has been closed, it will never be read again. */ - int(*on_close_channel)(struct liblttd_callbacks *data, - struct fd_pair *pair); + int (*on_close_channel)(struct liblttd_callbacks *data, + struct fd_pair *pair); /** * on_new_channels_folder - 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. - * @data: pointeur to the callbacks struct that has been passed to the - * lib. - * @relative_folder_path: represents a relative path - * to the channel folder. This path is relative to the root - * folder of the trace channels. + * + * @data: pointer to the callbacks structure that has been passed to the + * library. + * @relative_folder_path: + * represents a relative path to the channel folder. This path is + * relative to the root folder of the trace channels. * * Returns 0 if the callback succeeds else not 0. */ - int(*on_new_channels_folder)(struct liblttd_callbacks *data, - char *relative_folder_path); + int (*on_new_channels_folder)(struct liblttd_callbacks *data, + char *relative_folder_path); /** * on_read_subbuffer - Is called after a subbuffer is a reserved. * - * @data: pointeur to the callbacks struct that has been passed to the - * lib. - * @pair: structure that contains the data associated with the - * channel file descriptor. - * @len: represents the length the data that has to be read. + * @data: pointer to the callbacks structure that has been passed to the + * library. + * @pair: structure that contains the data associated with the channel + * file descriptor. + * @len: represents the length the data that has to be read. * * Returns 0 if the callback succeeds else not 0. * - * It has to be thread safe, it'll be called by many threads. + * It has to be thread safe, because it is called by many threads. */ - int(*on_read_subbuffer)(struct liblttd_callbacks *data, - struct fd_pair *pair, unsigned int len); + int (*on_read_subbuffer)(struct liblttd_callbacks *data, + struct fd_pair *pair, unsigned int len); /** * on_trace_en - 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. * - * @instance: pointeur to the instance struct that has been passed to - * the lib. + * @instance: pointer to the instance structure that has been passed to + * the library. * * Returns 0 if the callback succeeds else not 0. * @@ -166,35 +179,35 @@ struct liblttd_callbacks { * again and the tracing instance will be deleted automatically by * liblttd. After this call, the user must not use the liblttd instance. */ - int(*on_trace_end)(struct liblttd_instance *instance); + int (*on_trace_end)(struct liblttd_instance *instance); /** * on_new_thread - Is called after a new thread has been created. * - * @data: pointeur to the callbacks struct that has been passed to the - * lib. + * @data: pointer to the callbacks structure that has been passed to the + * lib. * @thread_num: represents the id of the thread. * * Returns 0 if the callback succeeds else not 0. * - * It has to be thread safe, it'll be called by many threads. + * It has to be thread safe, because it is called by many threads. */ - int(*on_new_thread)(struct liblttd_callbacks *data, - unsigned long thread_num); + int (*on_new_thread)(struct liblttd_callbacks *data, + unsigned long thread_num); /** - * on_close_thread - Is Called just before a thread is destroyed. + * on_close_thread - Is called just before a thread is destroyed. * - * @data: pointeur to the callbacks struct that has been passed to the - * lib. + * @data: pointer to the callbacks structure that has been passed to the + * library. * @thread_num: represents the number of the thread. * * Returns 0 if the callback succeeds else not 0. * - * It has to be thread safe, it'll be called by many threads. + * It has to be thread safe, because it is called by many threads. */ - int(*on_close_thread)(struct liblttd_callbacks *data, - unsigned long thread_num); + int (*on_close_thread)(struct liblttd_callbacks *data, + unsigned long thread_num); /** * The library's data. @@ -205,34 +218,36 @@ struct liblttd_callbacks { /** * liblttd_new_instance - Is called to create a new tracing session. * - * @callbacks: Pointer to a callbacks struct that contain the user callbacks and - * data. + * @callbacks: Pointer to a callbacks structure that contain the user + * callbacks and data. * @channel_path: This argument is a path to the root folder of the trace's - * channels. - * @n_threads: This argument represents the number of threads that will be - * used by the library. - * @flight_only: If this argument to set to 1, only the channel that are in - * flight recorder mode will be recorded. - * @normal_only: If this argument to set to 1, only the channel that are in - * normal mode will be recorded. - * @verbose: If this argument to set to 1, more informations will be printed. + * channels. + * @n_threads: This argument represents the number of threads that will be + * used by the library. + * @flight_only: If this argument to set to 1, only the channel that are in + * flight recorder mode will be recorded. + * @normal_only: If this argument to set to 1, only the channel that are in + * normal mode will be recorded. + * @verbose: If this argument to set to 1, more informations will be + * printed. * * Returns the instance if the function succeeds else NULL. */ -struct liblttd_instance * liblttd_new_instance( - struct liblttd_callbacks *callbacks, char *channel_path, - unsigned long n_threads, int flight_only, int normal_only, int verbose); +struct liblttd_instance * +liblttd_new_instance(struct liblttd_callbacks *callbacks, char *channel_path, + unsigned long n_threads, int flight_only, int normal_only, + int verbose); /** * liblttd_start - Is called to start a new tracing session. * - * @instance: The tracing session instance that needs to be starded. + * @instance: The tracing session instance that needs to be started. * * Returns 0 if the function succeeds. * - * This is a blocking function. The caller will be bloked on it until the - * tracing session is stoped by the user usign liblttd_stop_instance or until - * the trace is stoped by LTTng directly. + * This is a blocking function. The caller will be blocked on it until the + * tracing session is stopped by the user using liblttd_stop_instance or until + * the trace is stopped by LTTng directly. */ int liblttd_start_instance(struct liblttd_instance *instance); @@ -243,12 +258,11 @@ int liblttd_start_instance(struct liblttd_instance *instance); * * Returns 0 if the function succeeds. * - * This function return immediately, it only tells liblttd to stop the instance. - * The on_trace_end callback will be called when the tracing session will really - * be stoped (after every thread will be done). The instance is deleted - * automatically by liblttd after on_trace_end is called. + * This function returns immediately, it only tells liblttd to stop the + * instance. The on_trace_end callback will be called when the tracing session + * will really be stopped (after every thread has finished using it). The + * instance is deleted automatically by liblttd after on_trace_end is called. */ int liblttd_stop_instance(struct liblttd_instance *instance); #endif /*_LIBLTTD_H */ -