-/* liblttd header file
+/*
+ * liblttd header file
*
- * Copyright 2005 -
+ * Copyright 2005-2010 -
* Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
* Copyright 2010-
* Oumarou Dicko <oumarou.dicko@polymtl.ca>
* Michael Sills-Lavoie <michael.sills-lavoie@polymtl.ca>
*
- * 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
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.
*
* 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.
/**
* 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);
*
* 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 */
-
projects / ltt-control.git / blobdiff