4 * Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
6 * Oumarou Dicko <oumarou.dicko@polymtl.ca>
7 * Michael Sills-Lavoie <michael.sills-lavoie@polymtl.ca>
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
28 * struct fd_pair - Contains the data associated with the channel file
29 * descriptor. The lib user can use user_data to store the data associated to
30 * the specified channel. The lib user can read but MUST NOT change the other
32 * @channel: channel file descriptor
33 * @n_sb: the number of subbuffer for this channel
34 * @max_sb_size: the subbuffer size for this channel
35 * @mmap: Not used anymore.
36 * @mutex: a mutex for internal library usage
37 * @user_data: library user data
42 unsigned int max_sb_size
;
44 pthread_mutex_t mutex
;
48 struct channel_trace_fd
{
53 struct inotify_watch
{
55 char path_channel
[PATH_MAX
];
56 char *base_path_channel
;
59 struct inotify_watch_array
{
60 struct inotify_watch
*elem
;
64 struct liblttd_callbacks
;
67 * struct liblttd_instance - Contains the data associated with a trace instance.
68 * The lib user can read but MUST NOT change any attributes but callbacks.
69 * @callbacks: Contains the necessary callbacks for a tracing session.
71 struct liblttd_instance
{
72 struct liblttd_callbacks
*callbacks
;
75 struct channel_trace_fd fd_pairs
;
76 struct inotify_watch_array inotify_watch_array
;
78 /* protects fd_pairs and inotify_watch_array */
79 pthread_rwlock_t fd_pairs_lock
;
81 char channel_name
[PATH_MAX
];
82 unsigned long num_threads
;
90 * struct liblttd_callbacks - Contains the necessary callbacks for a tracing
91 * session. The user can set the unnecessary functions to NULL if he does not
94 struct liblttd_callbacks
{
96 * on_open_channel - Is called after a channel file is open.
97 * @data: pointeur to the callbacks struct that has been passed to the
99 * @pair: structure that contains the data associated with the
100 * channel file descriptor. The lib user can use user_data to
101 * store the data associated to the specified channel.
102 * @relative_channel_path: represents a relative path to the channel
103 * file. This path is relative to the root folder of the trace channels.
105 * Returns 0 if the callback succeeds else not 0.
107 int(*on_open_channel
)(struct liblttd_callbacks
*data
,
108 struct fd_pair
*pair
, char *relative_channel_path
);
111 * on_close_channel - Is called after a channel file is closed.
112 * @data: pointeur to the callbacks struct that has been passed to the
114 * @pair: structure that contains the data associated with the channel
115 * file descriptor. The lib user should clean user_data at this time.
117 * Returns 0 if the callback succeeds else not 0.
119 * After a channel file has been closed, it will never be read again.
121 int(*on_close_channel
)(struct liblttd_callbacks
*data
,
122 struct fd_pair
*pair
);
125 * on_new_channels_folder - Is called when the library enter in a new
126 * subfolder while it is scanning the trace channel tree. It can be used
127 * to create the output file structure of the trace.
128 * @data: pointeur to the callbacks struct that has been passed to the
130 * @relative_folder_path: represents a relative path
131 * to the channel folder. This path is relative to the root
132 * folder of the trace channels.
134 * Returns 0 if the callback succeeds else not 0.
136 int(*on_new_channels_folder
)(struct liblttd_callbacks
*data
,
137 char *relative_folder_path
);
140 * on_read_subbuffer - Is called after a subbuffer is a reserved.
142 * @data: pointeur to the callbacks struct that has been passed to the
144 * @pair: structure that contains the data associated with the
145 * channel file descriptor.
146 * @len: represents the length the data that has to be read.
148 * Returns 0 if the callback succeeds else not 0.
150 * It has to be thread safe, it'll be called by many threads.
152 int(*on_read_subbuffer
)(struct liblttd_callbacks
*data
,
153 struct fd_pair
*pair
, unsigned int len
);
156 * on_trace_en - Is called at the very end of the tracing session. At
157 * this time, all the channels have been closed and the threads have
160 * @instance: pointeur to the instance struct that has been passed to
163 * Returns 0 if the callback succeeds else not 0.
165 * After this callback is called, no other callback will be called
166 * again and the tracing instance will be deleted automatically by
167 * liblttd. After this call, the user must not use the liblttd instance.
169 int(*on_trace_end
)(struct liblttd_instance
*instance
);
172 * on_new_thread - Is called after a new thread has been created.
174 * @data: pointeur to the callbacks struct that has been passed to the
176 * @thread_num: represents the id of the thread.
178 * Returns 0 if the callback succeeds else not 0.
180 * It has to be thread safe, it'll be called by many threads.
182 int(*on_new_thread
)(struct liblttd_callbacks
*data
,
183 unsigned long thread_num
);
186 * on_close_thread - Is Called just before a thread is destroyed.
188 * @data: pointeur to the callbacks struct that has been passed to the
190 * @thread_num: represents the number of the thread.
192 * Returns 0 if the callback succeeds else not 0.
194 * It has to be thread safe, it'll be called by many threads.
196 int(*on_close_thread
)(struct liblttd_callbacks
*data
,
197 unsigned long thread_num
);
200 * The library's data.
206 * liblttd_new_instance - Is called to create a new tracing session.
208 * @callbacks: Pointer to a callbacks struct that contain the user callbacks and
210 * @channel_path: This argument is a path to the root folder of the trace's
212 * @n_threads: This argument represents the number of threads that will be
213 * used by the library.
214 * @flight_only: If this argument to set to 1, only the channel that are in
215 * flight recorder mode will be recorded.
216 * @normal_only: If this argument to set to 1, only the channel that are in
217 * normal mode will be recorded.
218 * @verbose: If this argument to set to 1, more informations will be printed.
220 * Returns the instance if the function succeeds else NULL.
222 struct liblttd_instance
* liblttd_new_instance(
223 struct liblttd_callbacks
*callbacks
, char *channel_path
,
224 unsigned long n_threads
, int flight_only
, int normal_only
, int verbose
);
227 * liblttd_start - Is called to start a new tracing session.
229 * @instance: The tracing session instance that needs to be starded.
231 * Returns 0 if the function succeeds.
233 * This is a blocking function. The caller will be bloked on it until the
234 * tracing session is stoped by the user usign liblttd_stop_instance or until
235 * the trace is stoped by LTTng directly.
237 int liblttd_start_instance(struct liblttd_instance
*instance
);
240 * liblttd_stop - Is called to stop a tracing session.
242 * @instance: The tracing session instance that needs to be stoped.
244 * Returns 0 if the function succeeds.
246 * This function return immediately, it only tells liblttd to stop the instance.
247 * The on_trace_end callback will be called when the tracing session will really
248 * be stoped (after every thread will be done). The instance is deleted
249 * automatically by liblttd after on_trace_end is called.
251 int liblttd_stop_instance(struct liblttd_instance
*instance
);
253 #endif /*_LIBLTTD_H */