02e7e9ce178056f52b3aecf8ed124741a83199f4
4 * Oumarou Dicko <oumarou.dicko@polymtl.ca>
5 * Michael Sills-Lavoie <michael.sills-lavoie@polymtl.ca>
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.
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.
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
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
40 unsigned int max_sb_size
;
42 pthread_mutex_t mutex
;
46 struct liblttd_instance
;
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
53 struct liblttd_callbacks
{
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
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.
64 * Returns 0 if the callback succeeds else not 0.
66 int(*on_open_channel
)(struct liblttd_callbacks
*data
,
67 struct fd_pair
*pair
, char *relative_channel_path
);
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
73 * @pair: structure that contains the data associated with the channel
74 * file descriptor. The lib user should clean user_data at this time.
76 * Returns 0 if the callback succeeds else not 0.
78 * After a channel file has been closed, it will never be read again.
80 int(*on_close_channel
)(struct liblttd_callbacks
*data
,
81 struct fd_pair
*pair
);
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
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.
93 * Returns 0 if the callback succeeds else not 0.
95 int(*on_new_channels_folder
)(struct liblttd_callbacks
*data
,
96 char *relative_folder_path
);
99 * on_read_subbuffer - Is called after a subbuffer is a reserved.
101 * @data: pointeur to the callbacks struct that has been passed to the
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.
107 * Returns 0 if the callback succeeds else not 0.
109 * It has to be thread safe, it'll be called by many threads.
111 int(*on_read_subbuffer
)(struct liblttd_callbacks
*data
,
112 struct fd_pair
*pair
, unsigned int len
);
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
119 * @data: pointeur to the callbacks struct that has been passed to the
122 * Returns 0 if the callback succeeds else not 0.
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.
129 int(*on_trace_end
)(struct liblttd_callbacks
*data
);
132 * on_new_thread - Is called after a new thread has been created.
134 * @data: pointeur to the callbacks struct that has been passed to the
136 * @thread_num: represents the id of the thread.
138 * Returns 0 if the callback succeeds else not 0.
140 * It has to be thread safe, it'll be called by many threads.
142 int(*on_new_thread
)(struct liblttd_callbacks
*data
,
143 unsigned long thread_num
);
146 * on_close_thread - Is Called just before a thread is destroyed.
148 * @data: pointeur to the callbacks struct that has been passed to the
150 * @thread_num: represents the number of the thread.
152 * Returns 0 if the callback succeeds else not 0.
154 * It has to be thread safe, it'll be called by many threads.
156 int(*on_close_thread
)(struct liblttd_callbacks
*data
,
157 unsigned long thread_num
);
160 * The library's data.
166 * liblttd_new_instance - Is called to create a new tracing session.
168 * @callbacks: Pointer to a callbacks struct that contain the user callbacks and
170 * @channel_path: This argument is a path to the root folder of the trace's
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.
180 * Returns the instance if the function succeeds else NULL.
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
);
187 * liblttd_start - Is called to start a new tracing session.
189 * @instance: The tracing session instance that needs to be starded.
191 * Returns 0 if the function succeeds.
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.
197 int liblttd_start_instance(struct liblttd_instance
*instance
);
200 * liblttd_stop - Is called to stop a tracing session.
202 * @instance: The tracing session instance that needs to be stoped.
204 * Returns 0 if the function succeeds.
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.
211 int liblttd_stop_instance(struct liblttd_instance
*instance
);
213 #endif /*_LIBLTTD_H */
This page took 0.033067 seconds and 4 git commands to generate.