4 * Copyright 2005-2010 -
5 * Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
7 * Oumarou Dicko <oumarou.dicko@polymtl.ca>
8 * Michael Sills-Lavoie <michael.sills-lavoie@polymtl.ca>
10 * This library is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public
12 * License as published by the Free Software Foundation; either
13 * version 2.1 of the License, or (at your option) any later version.
15 * This library is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with this library; if not, write to the Free Software
22 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
32 * struct fd_pair - Contains the data associated with the channel file
33 * descriptor. The lib user can use user_data to store the data associated to
34 * the specified channel. The lib user can read but MUST NOT change the other
36 * @channel: channel file descriptor
37 * @n_sb: the number of subbuffer for this channel
38 * @max_sb_size: the subbuffer size for this channel
39 * @mmap: Not used anymore.
40 * @mutex: a mutex for internal library usage
41 * @user_data: library user data
46 unsigned int max_sb_size
;
48 pthread_mutex_t mutex
;
52 struct channel_trace_fd
{
57 struct inotify_watch
{
59 char path_channel
[PATH_MAX
];
60 char *base_path_channel
;
63 struct inotify_watch_array
{
64 struct inotify_watch
*elem
;
68 struct liblttd_callbacks
;
71 * struct liblttd_instance - Contains the data associated with a trace instance.
72 * The lib user can read but MUST NOT change any attributes but callbacks.
73 * @callbacks: Contains the necessary callbacks for a tracing session.
75 struct liblttd_instance
{
76 struct liblttd_callbacks
*callbacks
;
79 struct channel_trace_fd fd_pairs
;
80 struct inotify_watch_array inotify_watch_array
;
82 /* protects fd_pairs and inotify_watch_array */
83 pthread_rwlock_t fd_pairs_lock
;
85 char channel_name
[PATH_MAX
];
86 unsigned long num_threads
;
94 * struct liblttd_callbacks - Contains the necessary callbacks for a tracing
95 * session. The user can set the unnecessary functions to NULL if he does not
98 struct liblttd_callbacks
{
100 * on_open_channel - Is called after a channel file is open.
102 * @data: pointer to the callbacks structure that has been passed to
104 * @pair: structure that contains the data associated with the
105 * channel file descriptor. The library user can use user_data to
106 * store the data associated to the specified channel.
107 * @relative_channel_path:
108 * represents a relative path to the channel file. This path is
109 * relative to the root folder of the trace channels.
111 * Returns 0 if the callback succeeds else not 0.
113 int (*on_open_channel
)(struct liblttd_callbacks
*data
,
114 struct fd_pair
*pair
,
115 char *relative_channel_path
);
118 * on_close_channel - Is called after a channel file is closed.
120 * @data: pointer to the callbacks structure that has been passed to the
122 * @pair: structure that contains the data associated with the channel
123 * file descriptor. The lib user should clean user_data at this
126 * Returns 0 if the callback succeeds else not 0.
128 * After a channel file has been closed, it will never be read again.
130 int (*on_close_channel
)(struct liblttd_callbacks
*data
,
131 struct fd_pair
*pair
);
134 * on_new_channels_folder - Is called when the library enter in a new
135 * subfolder while it is scanning the trace channel tree. It can be used
136 * to create the output file structure of the trace.
138 * @data: pointer to the callbacks structure that has been passed to the
140 * @relative_folder_path:
141 * represents a relative path to the channel folder. This path is
142 * relative to the root folder of the trace channels.
144 * Returns 0 if the callback succeeds else not 0.
146 int (*on_new_channels_folder
)(struct liblttd_callbacks
*data
,
147 char *relative_folder_path
);
150 * on_read_subbuffer - Is called after a subbuffer is a reserved.
152 * @data: pointer to the callbacks structure that has been passed to the
154 * @pair: structure that contains the data associated with the channel
156 * @len: represents the length the data that has to be read.
158 * Returns 0 if the callback succeeds else not 0.
160 * It has to be thread safe, because it is called by many threads.
162 int (*on_read_subbuffer
)(struct liblttd_callbacks
*data
,
163 struct fd_pair
*pair
, unsigned int len
);
166 * on_trace_en - Is called at the very end of the tracing session. At
167 * this time, all the channels have been closed and the threads have
170 * @instance: pointer to the instance structure that has been passed to
173 * Returns 0 if the callback succeeds else not 0.
175 * After this callback is called, no other callback will be called
176 * again and the tracing instance will be deleted automatically by
177 * liblttd. After this call, the user must not use the liblttd instance.
179 int (*on_trace_end
)(struct liblttd_instance
*instance
);
182 * on_new_thread - Is called after a new thread has been created.
184 * @data: pointer to the callbacks structure that has been passed to the
186 * @thread_num: represents the id of the thread.
188 * Returns 0 if the callback succeeds else not 0.
190 * It has to be thread safe, because it is called by many threads.
192 int (*on_new_thread
)(struct liblttd_callbacks
*data
,
193 unsigned long thread_num
);
196 * on_close_thread - Is called just before a thread is destroyed.
198 * @data: pointer to the callbacks structure that has been passed to the
200 * @thread_num: represents the number of the thread.
202 * Returns 0 if the callback succeeds else not 0.
204 * It has to be thread safe, because it is called by many threads.
206 int (*on_close_thread
)(struct liblttd_callbacks
*data
,
207 unsigned long thread_num
);
210 * The library's data.
216 * liblttd_new_instance - Is called to create a new tracing session.
218 * @callbacks: Pointer to a callbacks structure that contain the user
219 * callbacks and data.
220 * @channel_path: This argument is a path to the root folder of the trace's
222 * @n_threads: This argument represents the number of threads that will be
223 * used by the library.
224 * @flight_only: If this argument to set to 1, only the channel that are in
225 * flight recorder mode will be recorded.
226 * @normal_only: If this argument to set to 1, only the channel that are in
227 * normal mode will be recorded.
228 * @verbose: If this argument to set to 1, more informations will be
231 * Returns the instance if the function succeeds else NULL.
233 struct liblttd_instance
*
234 liblttd_new_instance(struct liblttd_callbacks
*callbacks
, char *channel_path
,
235 unsigned long n_threads
, int flight_only
, int normal_only
,
239 * liblttd_start - Is called to start a new tracing session.
241 * @instance: The tracing session instance that needs to be started.
243 * Returns 0 if the function succeeds.
245 * This is a blocking function. The caller will be blocked on it until the
246 * tracing session is stopped by the user using liblttd_stop_instance or until
247 * the trace is stopped by LTTng directly.
249 int liblttd_start_instance(struct liblttd_instance
*instance
);
252 * liblttd_stop - Is called to stop a tracing session.
254 * @instance: The tracing session instance that needs to be stoped.
256 * Returns 0 if the function succeeds.
258 * This function returns immediately, it only tells liblttd to stop the
259 * instance. The on_trace_end callback will be called when the tracing session
260 * will really be stopped (after every thread has finished using it). The
261 * instance is deleted automatically by liblttd after on_trace_end is called.
263 int liblttd_stop_instance(struct liblttd_instance
*instance
);
265 #endif /*_LIBLTTD_H */