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
33 * struct fd_pair - Contains the data associated with the channel file
34 * descriptor. The lib user can use user_data to store the data associated to
35 * the specified channel. The lib user can read but MUST NOT change the other
37 * @channel: channel file descriptor
38 * @n_sb: the number of subbuffer for this channel
39 * @max_sb_size: the subbuffer size for this channel
40 * @mmap: Not used anymore.
41 * @mutex: a mutex for internal library usage
42 * @user_data: library user data
43 * @offset: write position in the output file descriptor (optional)
48 unsigned int max_sb_size
;
50 pthread_mutex_t mutex
;
55 struct channel_trace_fd
{
60 struct inotify_watch
{
62 char path_channel
[PATH_MAX
];
63 char *base_path_channel
;
66 struct inotify_watch_array
{
67 struct inotify_watch
*elem
;
71 struct liblttd_callbacks
;
74 * struct liblttd_instance - Contains the data associated with a trace instance.
75 * The lib user can read but MUST NOT change any attributes but callbacks.
76 * @callbacks: Contains the necessary callbacks for a tracing session.
78 struct liblttd_instance
{
79 struct liblttd_callbacks
*callbacks
;
82 struct channel_trace_fd fd_pairs
;
83 struct inotify_watch_array inotify_watch_array
;
85 /* protects fd_pairs and inotify_watch_array */
86 pthread_rwlock_t fd_pairs_lock
;
88 char channel_name
[PATH_MAX
];
89 unsigned long num_threads
;
97 * struct liblttd_callbacks - Contains the necessary callbacks for a tracing
98 * session. The user can set the unnecessary functions to NULL if he does not
101 struct liblttd_callbacks
{
103 * on_open_channel - Is called after a channel file is open.
105 * @data: pointer to the callbacks structure that has been passed to
107 * @pair: structure that contains the data associated with the
108 * channel file descriptor. The library user can use user_data to
109 * store the data associated to the specified channel.
110 * @relative_channel_path:
111 * represents a relative path to the channel file. This path is
112 * relative to the root folder of the trace channels.
114 * Returns 0 if the callback succeeds else not 0.
116 int (*on_open_channel
)(struct liblttd_callbacks
*data
,
117 struct fd_pair
*pair
,
118 char *relative_channel_path
);
121 * on_close_channel - Is called after a channel file is closed.
123 * @data: pointer to the callbacks structure that has been passed to the
125 * @pair: structure that contains the data associated with the channel
126 * file descriptor. The lib user should clean user_data at this
129 * Returns 0 if the callback succeeds else not 0.
131 * After a channel file has been closed, it will never be read again.
133 int (*on_close_channel
)(struct liblttd_callbacks
*data
,
134 struct fd_pair
*pair
);
137 * on_new_channels_folder - Is called when the library enter in a new
138 * subfolder while it is scanning the trace channel tree. It can be used
139 * to create the output file structure of the trace.
141 * @data: pointer to the callbacks structure that has been passed to the
143 * @relative_folder_path:
144 * represents a relative path to the channel folder. This path is
145 * relative to the root folder of the trace channels.
147 * Returns 0 if the callback succeeds else not 0.
149 int (*on_new_channels_folder
)(struct liblttd_callbacks
*data
,
150 char *relative_folder_path
);
153 * on_read_subbuffer - Is called after a subbuffer is a reserved.
155 * @data: pointer to the callbacks structure that has been passed to the
157 * @pair: structure that contains the data associated with the channel
159 * @len: represents the length the data that has to be read.
161 * Returns 0 if the callback succeeds else not 0.
163 * It has to be thread safe, because it is called by many threads.
165 int (*on_read_subbuffer
)(struct liblttd_callbacks
*data
,
166 struct fd_pair
*pair
, unsigned int len
);
169 * on_trace_en - Is called at the very end of the tracing session. At
170 * this time, all the channels have been closed and the threads have
173 * @instance: pointer to the instance structure that has been passed to
176 * Returns 0 if the callback succeeds else not 0.
178 * After this callback is called, no other callback will be called
179 * again and the tracing instance will be deleted automatically by
180 * liblttd. After this call, the user must not use the liblttd instance.
182 int (*on_trace_end
)(struct liblttd_instance
*instance
);
185 * on_new_thread - Is called after a new thread has been created.
187 * @data: pointer to the callbacks structure that has been passed to the
189 * @thread_num: represents the id of the thread.
191 * Returns 0 if the callback succeeds else not 0.
193 * It has to be thread safe, because it is called by many threads.
195 int (*on_new_thread
)(struct liblttd_callbacks
*data
,
196 unsigned long thread_num
);
199 * on_close_thread - Is called just before a thread is destroyed.
201 * @data: pointer to the callbacks structure that has been passed to the
203 * @thread_num: represents the number of the thread.
205 * Returns 0 if the callback succeeds else not 0.
207 * It has to be thread safe, because it is called by many threads.
209 int (*on_close_thread
)(struct liblttd_callbacks
*data
,
210 unsigned long thread_num
);
213 * The library's data.
219 * liblttd_new_instance - Is called to create a new tracing session.
221 * @callbacks: Pointer to a callbacks structure that contain the user
222 * callbacks and data.
223 * @channel_path: This argument is a path to the root folder of the trace's
225 * @n_threads: This argument represents the number of threads that will be
226 * used by the library.
227 * @flight_only: If this argument to set to 1, only the channel that are in
228 * flight recorder mode will be recorded.
229 * @normal_only: If this argument to set to 1, only the channel that are in
230 * normal mode will be recorded.
231 * @verbose: If this argument to set to 1, more informations will be
234 * Returns the instance if the function succeeds else NULL.
236 struct liblttd_instance
*
237 liblttd_new_instance(struct liblttd_callbacks
*callbacks
, char *channel_path
,
238 unsigned long n_threads
, int flight_only
, int normal_only
,
242 * liblttd_start - Is called to start a new tracing session.
244 * @instance: The tracing session instance that needs to be started.
246 * Returns 0 if the function succeeds.
248 * This is a blocking function. The caller will be blocked on it until the
249 * tracing session is stopped by the user using liblttd_stop_instance or until
250 * the trace is stopped by LTTng directly.
252 int liblttd_start_instance(struct liblttd_instance
*instance
);
255 * liblttd_stop - Is called to stop a tracing session.
257 * @instance: The tracing session instance that needs to be stoped.
259 * Returns 0 if the function succeeds.
261 * This function returns immediately, it only tells liblttd to stop the
262 * instance. The on_trace_end callback will be called when the tracing session
263 * will really be stopped (after every thread has finished using it). The
264 * instance is deleted automatically by liblttd after on_trace_end is called.
266 int liblttd_stop_instance(struct liblttd_instance
*instance
);
268 #endif /*_LIBLTTD_H */