Commit | Line | Data |
---|---|---|
1239a312 | 1 | /* |
ab5be9fa | 2 | * Copyright (C) 2014 David Goulet <dgoulet@efficios.com> |
1239a312 | 3 | * |
ab5be9fa | 4 | * SPDX-License-Identifier: LGPL-2.1-only |
1239a312 | 5 | * |
1239a312 DG |
6 | */ |
7 | ||
8 | #ifndef LTTNG_CHANNEL_H | |
9 | #define LTTNG_CHANNEL_H | |
10 | ||
11 | #include <lttng/domain.h> | |
12 | #include <lttng/event.h> | |
4bd69c5f | 13 | #include <lttng/lttng-export.h> |
28f23191 | 14 | |
5ba3702f | 15 | #include <stdint.h> |
1239a312 DG |
16 | |
17 | #ifdef __cplusplus | |
18 | extern "C" { | |
19 | #endif | |
20 | ||
21 | /* | |
22 | * Tracer channel attributes. For both kernel and user-space. | |
23 | * | |
24 | * The structures should be initialized to zero before use. | |
25 | */ | |
28f23191 | 26 | #define LTTNG_CHANNEL_ATTR_PADDING1 LTTNG_SYMBOL_NAME_LEN + 12 |
048f01ef PP |
27 | |
28 | /*! | |
29 | @brief | |
30 | Attributes of a \link #lttng_channel channel summary\endlink. | |
31 | ||
32 | @ingroup api_channel | |
33 | ||
34 | The lttng_channel::attr member is an instance of such a structure. | |
35 | ||
36 | lttng_channel_set_default_attr() sets the members of such a structure | |
37 | to their default values given a specific \lt_obj_domain summary. | |
38 | ||
39 | \anchor api-channel-valid-attr-struct A \em valid #lttng_channel_attr | |
40 | structure satisfies the following constraints: | |
41 | ||
42 | <table> | |
43 | <tr> | |
44 | <th>Member | |
45 | <th>Constraints | |
46 | <tr> | |
47 | <td>lttng_channel_attr::overwrite | |
48 | <td>0, 1, or -1 | |
49 | <tr> | |
50 | <td>lttng_channel_attr::subbuf_size | |
51 | <td> | |
52 | - Greater than 0 | |
53 | - Power of two | |
54 | <tr> | |
55 | <td>lttng_channel_attr::num_subbuf | |
56 | <td> | |
57 | - Greater than 0 | |
58 | - Power of two | |
59 | </table> | |
60 | */ | |
1239a312 | 61 | struct lttng_channel_attr { |
048f01ef PP |
62 | /*! |
63 | @brief | |
64 | \ref api-channel-er-loss-mode "Event record loss mode". | |
65 | ||
66 | One of: | |
67 | ||
68 | <dl> | |
69 | <dt>0 | |
70 | <dd> | |
71 | The \ref api-channel-er-loss-mode "event record loss mode" | |
72 | of the channel is | |
73 | <em>\ref api-channel-discard-mode "discard"</em>. | |
74 | ||
75 | <dt>1 | |
76 | <dd> | |
77 | The event record loss mode of the channel is | |
78 | <em>\ref api-channel-overwrite-mode "overwrite"</em>. | |
79 | ||
80 | <dt>-1 | |
81 | <dd> | |
82 | The event record loss mode of the channel is the default | |
83 | value of its \lt_obj_session: | |
84 | ||
85 | <dl> | |
86 | <dt>\ref api-session-snapshot-mode "Snapshot mode" | |
87 | <dd>Overwrite mode | |
88 | ||
89 | <dt>Other modes | |
90 | <dd>Discard mode | |
91 | </dl> | |
92 | </dl> | |
93 | */ | |
28f23191 | 94 | int overwrite; /* -1: session default, 1: overwrite, 0: discard */ |
048f01ef PP |
95 | |
96 | /*! | |
97 | @brief | |
98 | \ref api-channel-sub-buf-size-count "Sub-buffer size" | |
99 | (bytes). | |
100 | */ | |
28f23191 | 101 | uint64_t subbuf_size; /* bytes, power of 2 */ |
048f01ef PP |
102 | |
103 | /*! | |
104 | @brief | |
105 | \ref api-channel-sub-buf-size-count "Sub-buffer count". | |
106 | */ | |
28f23191 | 107 | uint64_t num_subbuf; /* power of 2 */ |
048f01ef PP |
108 | |
109 | /*! | |
110 | @brief | |
111 | \ref api-channel-switch-timer "Switch timer period" (µs), | |
112 | if applicable. | |
113 | ||
114 | Only available if the \lt_obj_session which | |
115 | owns this channel is \em not in | |
116 | \ref api-session-live-mode "live mode". | |
117 | */ | |
1239a312 | 118 | unsigned int switch_timer_interval; /* usec */ |
048f01ef PP |
119 | |
120 | /// \ref api-channel-read-timer "Read timer period" (µs). | |
28f23191 | 121 | unsigned int read_timer_interval; /* usec */ |
048f01ef PP |
122 | |
123 | /// Output type (Linux kernel channel). | |
28f23191 | 124 | enum lttng_event_output output; /* splice, mmap */ |
048f01ef | 125 | |
1239a312 | 126 | /* LTTng 2.1 padding limit */ |
048f01ef PP |
127 | |
128 | /*! | |
129 | @brief | |
130 | \ref api-channel-max-trace-file-size-count "Maximum trace file size" | |
131 | (bytes), or 0 for unlimited. | |
132 | */ | |
28f23191 | 133 | uint64_t tracefile_size; /* bytes */ |
048f01ef PP |
134 | |
135 | /*! | |
136 | @brief | |
137 | \ref api-channel-max-trace-file-size-count "Maximum trace file count", | |
138 | or 0 for unlimited. | |
139 | */ | |
28f23191 | 140 | uint64_t tracefile_count; /* number of tracefiles */ |
048f01ef | 141 | |
1239a312 | 142 | /* LTTng 2.3 padding limit */ |
048f01ef PP |
143 | |
144 | /*! | |
145 | @brief | |
146 | \ref api-channel-live-timer "Live timer period" (µs), if | |
147 | applicable. | |
148 | ||
149 | You may \em not set this member: use the | |
150 | \lt_p{live_timer_period} parameter of | |
151 | lttng_session_descriptor_live_network_create() when you create | |
152 | the descriptor of a \ref api-session-live-mode "live" recording | |
153 | session to contain the channel to create. | |
154 | ||
155 | Only available if the \lt_obj_session which | |
156 | owns this channel is in \ref api-session-live-mode "live mode". | |
157 | */ | |
28f23191 | 158 | unsigned int live_timer_interval; /* usec */ |
048f01ef | 159 | |
67487150 JG |
160 | /* LTTng 2.7 padding limit */ |
161 | uint32_t align_to_64; | |
162 | union { | |
163 | uint64_t padding; | |
164 | void *ptr; | |
165 | } extended; | |
1239a312 DG |
166 | |
167 | char padding[LTTNG_CHANNEL_ATTR_PADDING1]; | |
168 | }; | |
169 | ||
170 | /* | |
171 | * Channel information structure. For both kernel and user-space. | |
172 | * | |
173 | * The structures should be initialized to zero before use. | |
174 | */ | |
28f23191 | 175 | #define LTTNG_CHANNEL_PADDING1 16 |
048f01ef PP |
176 | |
177 | /*! | |
178 | @brief | |
179 | \lt_obj_c_channel summary. | |
180 | ||
181 | @ingroup api_channel | |
182 | ||
183 | The purpose of such a structure is to provide information about a | |
184 | channel itself, but not about its \lt_obj_rers | |
185 | (use lttng_list_events() for this). | |
186 | ||
187 | lttng_list_channels() sets a pointer to an array of all the | |
188 | channel summaries of a given \lt_obj_session and \lt_obj_domain. | |
189 | ||
190 | Most properties are part of the lttng_channel::attr member, but the | |
191 | following ones have their own dedicated accessors: | |
192 | ||
193 | <dl> | |
194 | <dt>\ref api-channel-monitor-timer "Monitor timer" period | |
195 | <dd> | |
196 | - lttng_channel_get_monitor_timer_interval() | |
197 | - lttng_channel_set_monitor_timer_interval() | |
198 | ||
199 | <dt>\ref api-channel-blocking-timeout "Blocking timeout" | |
200 | <dd> | |
201 | - lttng_channel_get_blocking_timeout() | |
202 | - lttng_channel_set_blocking_timeout() | |
203 | </dl> | |
204 | ||
205 | Create a channel summary with lttng_channel_create(). | |
206 | ||
207 | Destroy a channel summary with lttng_channel_destroy(). | |
208 | */ | |
1239a312 | 209 | struct lttng_channel { |
048f01ef | 210 | /// Name. |
1239a312 | 211 | char name[LTTNG_SYMBOL_NAME_LEN]; |
048f01ef PP |
212 | |
213 | /*! | |
214 | @brief | |
215 | 1 if this \lt_obj_channel is enabled, or 0 otherwise. | |
216 | ||
217 | @sa lttng_enable_channel() -- | |
218 | Creates or enables a channel. | |
219 | @sa lttng_disable_channel() -- | |
220 | Disables a channel. | |
221 | */ | |
1239a312 | 222 | uint32_t enabled; |
048f01ef PP |
223 | |
224 | /// Other properties. | |
1239a312 DG |
225 | struct lttng_channel_attr attr; |
226 | ||
227 | char padding[LTTNG_CHANNEL_PADDING1]; | |
228 | }; | |
229 | ||
048f01ef PP |
230 | /*! |
231 | @brief | |
232 | Creates and returns a \lt_obj_channel summary, | |
233 | setting the members of its lttng_channel::attr member to default | |
234 | values according to the \lt_obj_domain summary \lt_p{domain}. | |
235 | ||
236 | @ingroup api_channel | |
237 | ||
238 | This function internally calls | |
239 | ||
240 | @code | |
241 | lttng_channel_set_default_attr(domain, &channel->attr); | |
242 | @endcode | |
243 | ||
244 | where \c channel is the returned channel summary. | |
245 | ||
246 | After you create a channel summary with this function, you can modify | |
247 | its \ref api-channel-channel-props "properties" and call | |
248 | lttng_enable_channel() to create and enable a channel. | |
249 | ||
250 | @param[in] domain | |
251 | Tracing domain summary to consider to set the members of the | |
252 | lttng_channel::attr member of the returned structure to default | |
253 | values. | |
254 | ||
255 | @returns | |
256 | @parblock | |
257 | New channel summary. | |
258 | ||
259 | Destroy the returned channel summary with lttng_channel_destroy(). | |
260 | @endparblock | |
261 | ||
262 | @lt_pre_not_null{domain} | |
263 | ||
264 | @sa lttng_channel_destroy() -- | |
265 | Destroys a channel summary. | |
266 | */ | |
4bd69c5f | 267 | LTTNG_EXPORT extern struct lttng_channel *lttng_channel_create(struct lttng_domain *domain); |
cf0bcb51 | 268 | |
048f01ef PP |
269 | /*! |
270 | @brief | |
271 | Destroys the \lt_obj_channel summary \lt_p{channel}. | |
272 | ||
273 | @ingroup api_channel | |
274 | ||
275 | @note | |
276 | This function doesn't destroy the \lt_obj_channel | |
277 | which \lt_p{channel} summarizes: the only way to destroy a channel | |
278 | is to \link lttng_destroy_session_ext() destroy its recording | |
279 | session\endlink. | |
280 | ||
281 | @param[in] channel | |
282 | @parblock | |
283 | Channel summary to destroy. | |
284 | ||
285 | May be \c NULL. | |
286 | @endparblock | |
287 | */ | |
4bd69c5f | 288 | LTTNG_EXPORT extern void lttng_channel_destroy(struct lttng_channel *channel); |
cf0bcb51 | 289 | |
048f01ef PP |
290 | /*! |
291 | @brief | |
292 | Sets \lt_p{*channels} to the summaries of the | |
293 | \lt_obj_channels of the recording session handle \lt_p{handle}. | |
294 | ||
295 | @ingroup api_session | |
296 | ||
297 | @param[in] handle | |
298 | Recording session handle which contains the name of the recording | |
299 | session and the summary of the \lt_obj_domain which own the channels | |
300 | of which to get the summaries. | |
301 | @param[out] channels | |
302 | @parblock | |
303 | <strong>On success</strong>, this function sets \lt_p{*channels} to | |
304 | the summaries of the channels. | |
305 | ||
306 | Free \lt_p{*channels} with <code>free()</code>. | |
307 | @endparblock | |
308 | ||
309 | @returns | |
310 | The number of items in \lt_p{*channels} on success, or a \em | |
311 | negative #lttng_error_code enumerator otherwise. | |
312 | ||
313 | @lt_pre_conn | |
314 | @lt_pre_not_null{handle} | |
315 | @lt_pre_valid_c_str{handle->session_name} | |
316 | @lt_pre_sess_exists{handle->session_name} | |
317 | @pre | |
318 | \lt_p{handle->domain} is valid as per the documentation of | |
319 | #lttng_domain. | |
320 | @lt_pre_not_null{channels} | |
321 | */ | |
4bd69c5f | 322 | LTTNG_EXPORT extern int lttng_list_channels(struct lttng_handle *handle, |
28f23191 | 323 | struct lttng_channel **channels); |
1239a312 | 324 | |
048f01ef PP |
325 | /*! |
326 | @brief | |
327 | Creates or enables a \lt_obj_channel summarized by \lt_p{channel} | |
328 | within the recording session handle \lt_p{handle}. | |
329 | ||
330 | @ingroup api_channel | |
331 | ||
332 | This function, depending on \lt_p{channel->name}: | |
333 | ||
334 | <dl> | |
335 | <dt> | |
336 | \lt_p{channel->name} names an existing | |
337 | channel within the \lt_obj_session and | |
338 | \lt_obj_domain of \lt_p{handle} | |
339 | <dd> | |
340 | Enables the existing channel. | |
341 | ||
342 | In this case, this function only uses \lt_p{channel->name}, ignoring | |
343 | all the other properties of \lt_p{channel}. | |
344 | ||
345 | <dt>Otherwise | |
346 | <dd> | |
347 | Creates and enables a new channel, considering all the properties of | |
348 | \lt_p{channel}. | |
349 | </dl> | |
350 | ||
351 | @param[in] handle | |
352 | Recording session handle which contains the name of the | |
353 | recording session and the summary of the \lt_obj_domain which own | |
354 | the channel to create or enable. | |
355 | @param[in] channel | |
356 | Summary of the channel to create or enable. | |
357 | ||
358 | @returns | |
359 | 0 on success, or a \em negative #lttng_error_code enumerator | |
360 | otherwise. | |
361 | ||
362 | @lt_pre_conn | |
363 | @lt_pre_not_null{handle} | |
364 | @lt_pre_valid_c_str{handle->session_name} | |
365 | @lt_pre_sess_exists{handle->session_name} | |
366 | @pre | |
367 | \lt_p{handle->domain} is valid as per the documentation of | |
368 | #lttng_domain. | |
369 | @lt_pre_not_null{channel} | |
370 | @pre | |
371 | <strong>If this function must create a new channel</strong>, then | |
372 | \lt_p{channel->attr} is \ref api-channel-valid-attr-struct "valid". | |
373 | @pre | |
374 | <strong>If this function must create a new channel</strong>, then | |
375 | \lt_p{handle->session_name} names a | |
376 | \lt_obj_session which never became | |
377 | \link lttng_session::enabled active\endlink (started) since its | |
378 | creation. | |
379 | @pre | |
380 | <strong>If this function must create a new channel</strong>, then | |
381 | all the existing channels of \lt_p{handle} have the same | |
382 | \ref api-channel-buf-scheme "buffering scheme". | |
383 | ||
384 | @sa lttng_disable_channel() -- | |
385 | Disables a channel. | |
386 | */ | |
4bd69c5f | 387 | LTTNG_EXPORT extern int lttng_enable_channel(struct lttng_handle *handle, |
048f01ef | 388 | struct lttng_channel *channel); |
1239a312 | 389 | |
048f01ef PP |
390 | /*! |
391 | @brief | |
392 | Disables the \lt_obj_channel named \lt_p{channel_name} within the | |
393 | recording session handle \lt_p{handle}. | |
1239a312 | 394 | |
048f01ef PP |
395 | @ingroup api_channel |
396 | ||
397 | @param[in] handle | |
398 | Recording session handle which contains the name of the | |
399 | recording session and the summary of the \lt_obj_domain which own | |
400 | the channel to disable. | |
401 | @param[in] channel_name | |
402 | Name of the channel to disable within \lt_p{handle}. | |
403 | ||
404 | @returns | |
405 | 0 on success, or a \em negative #lttng_error_code enumerator | |
406 | otherwise. | |
407 | ||
408 | @lt_pre_conn | |
409 | @lt_pre_not_null{handle} | |
410 | @lt_pre_valid_c_str{handle->session_name} | |
411 | @lt_pre_sess_exists{handle->session_name} | |
412 | @pre | |
413 | \lt_p{handle->domain} is valid as per the documentation of | |
414 | #lttng_domain. | |
415 | @lt_pre_not_null{channel_name} | |
416 | @pre | |
417 | \lt_p{channel_name} names an existing channel within the recording | |
418 | session and tracing domain of \lt_p{handle}. | |
419 | ||
420 | @sa lttng_enable_channel() -- | |
421 | Creates or enables a channel. | |
422 | */ | |
423 | LTTNG_EXPORT extern int lttng_disable_channel(struct lttng_handle *handle, | |
424 | const char *channel_name); | |
425 | ||
426 | /*! | |
427 | @brief | |
428 | Sets the members of \lt_p{attr} to their default values considering | |
429 | the \lt_obj_domain summary \lt_p{domain}. | |
430 | ||
431 | @ingroup api_channel | |
432 | ||
433 | Use this function on an lttng_channel::attr member. | |
434 | ||
435 | @param[in] domain | |
436 | Tracing domain summary to consider to set the members of \lt_p{attr} | |
437 | to their default values. | |
438 | @param[in] attr | |
439 | Structure of which to set the members to their default values. | |
440 | ||
441 | @lt_pre_not_null{domain} | |
442 | @lt_pre_not_null{attr} | |
443 | */ | |
4bd69c5f | 444 | LTTNG_EXPORT extern void lttng_channel_set_default_attr(struct lttng_domain *domain, |
28f23191 | 445 | struct lttng_channel_attr *attr); |
1239a312 | 446 | |
048f01ef PP |
447 | /*! |
448 | @brief | |
449 | Sets \lt_p{*count} to the number of discarded event | |
450 | records of the \lt_obj_channel summarized by \lt_p{channel}. | |
5ba3702f | 451 | |
048f01ef PP |
452 | @ingroup api_channel |
453 | ||
454 | In \ref api-channel-discard-mode "discard mode", LTTng discards an event | |
455 | record when there's no sub-buffer left to write it. | |
456 | ||
457 | lttng_list_channels() sets a pointer to an array of all the | |
458 | channel summaries of a given \lt_obj_session and \lt_obj_domain. | |
459 | ||
460 | @param[in] channel | |
461 | Summary of the channel of which to get the number of discarded | |
462 | event records. | |
463 | @param[out] count | |
464 | <strong>On success</strong>, this function sets \lt_p{*count} to | |
465 | the number of discarded event records of the channel summarized | |
466 | by \lt_p{channel}. | |
467 | ||
468 | @returns | |
469 | 0 on success, or a \em negative #lttng_error_code enumerator | |
470 | otherwise. | |
471 | ||
472 | @lt_pre_not_null{channel} | |
473 | @pre | |
474 | You obtained \lt_p{channel} with lttng_list_channels(). | |
475 | @pre | |
476 | The lttng_channel_attr::overwrite member of \lt_p{channel->attr} | |
477 | is 0. | |
478 | @lt_pre_not_null{count} | |
479 | ||
480 | @sa lttng_channel_get_lost_packet_count() -- | |
481 | Returns the number of discarded packets (sub-buffers) of a channel. | |
482 | */ | |
483 | LTTNG_EXPORT extern int lttng_channel_get_discarded_event_count(struct lttng_channel *channel, | |
484 | uint64_t *count); | |
485 | ||
486 | /*! | |
487 | @brief | |
488 | Sets \lt_p{*count} to the number of discarded packets (sub-buffers) | |
489 | of the \lt_obj_channel summarized by \lt_p{channel}. | |
490 | ||
491 | @ingroup api_channel | |
492 | ||
493 | In \ref api-channel-overwrite-mode "overwrite mode", LTTng discards a | |
494 | whole sub-buffer when there's no sub-buffer left to record an event. | |
495 | ||
496 | lttng_list_channels() sets a pointer to an array of all the | |
497 | channel summaries of a given \lt_obj_session and \lt_obj_domain. | |
498 | ||
499 | @param[in] channel | |
500 | Summary of the channel of which to get the number of discarded | |
501 | packets. | |
502 | @param[out] count | |
503 | <strong>On success</strong>, this function sets \lt_p{*count} to | |
504 | the number of discarded packets of the channel summarized | |
505 | by \lt_p{channel}. | |
506 | ||
507 | @returns | |
508 | 0 on success, or a \em negative #lttng_error_code enumerator | |
509 | otherwise. | |
510 | ||
511 | @lt_pre_not_null{channel} | |
512 | @pre | |
513 | You obtained \lt_p{channel} with lttng_list_channels(). | |
514 | @pre | |
515 | The lttng_channel_attr::overwrite member of \lt_p{channel->attr} | |
516 | is 1. | |
517 | @lt_pre_not_null{count} | |
518 | ||
519 | @sa lttng_channel_get_discarded_event_count() -- | |
520 | Returns the number of discarded event records of a channel. | |
521 | */ | |
522 | LTTNG_EXPORT extern int lttng_channel_get_lost_packet_count(struct lttng_channel *channel, | |
523 | uint64_t *count); | |
524 | ||
525 | /*! | |
526 | @brief | |
527 | Sets \lt_p{period} to the | |
528 | \ref api-channel-monitor-timer "monitor timer" period (µs) | |
529 | property of the \lt_obj_channel summary \lt_p{channel}. | |
530 | ||
531 | @ingroup api_channel | |
532 | ||
533 | @param[in] channel | |
534 | Summary of the channel of which to get the monitor timer period. | |
535 | @param[out] period | |
536 | <strong>On success</strong>, this function sets \lt_p{*period} to | |
537 | the monitor timer period (µs) property of \lt_p{channel}. | |
538 | ||
539 | @returns | |
540 | 0 on success, or a \em negative #lttng_error_code enumerator | |
541 | otherwise. | |
542 | ||
543 | @lt_pre_not_null{channel} | |
544 | @lt_pre_not_null{period} | |
545 | ||
546 | @sa lttng_channel_set_monitor_timer_interval() -- | |
547 | Sets the monitor timer period property of a channel summary. | |
548 | */ | |
549 | LTTNG_EXPORT extern int lttng_channel_get_monitor_timer_interval(struct lttng_channel *channel, | |
550 | uint64_t *period); | |
551 | ||
552 | /*! | |
553 | @brief | |
554 | Sets the \ref api-channel-monitor-timer "monitor timer" period | |
555 | property of the channel summary \lt_p{channel} to | |
556 | \lt_p{period} µs. | |
557 | ||
558 | @ingroup api_channel | |
559 | ||
560 | @param[in] channel | |
561 | Channel summary of which to set the monitor timer period | |
562 | to \lt_p{period} µs. | |
563 | @param[in] period | |
564 | Monitor timer period property to set. | |
565 | ||
566 | @returns | |
567 | 0 on success, or a \em negative #lttng_error_code enumerator | |
568 | otherwise. | |
569 | ||
570 | @lt_pre_not_null{channel} | |
571 | @pre | |
572 | \lt_p{period} ≥ 1 | |
573 | ||
574 | @sa lttng_channel_get_monitor_timer_interval() -- | |
575 | Returns the monitor timer period property of a channel summary. | |
576 | */ | |
577 | LTTNG_EXPORT extern int lttng_channel_set_monitor_timer_interval(struct lttng_channel *channel, | |
578 | uint64_t period); | |
579 | ||
580 | /*! | |
581 | @brief | |
582 | Sets \lt_p{timeout} to the | |
583 | \ref api-channel-blocking-timeout "blocking timeout" | |
584 | property of the \lt_obj_channel summary \lt_p{channel}. | |
585 | ||
586 | @ingroup api_channel | |
587 | ||
588 | This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink | |
589 | channels. | |
590 | ||
591 | @param[in] channel | |
592 | Summary of the channel of which to get the blocking timeout. | |
593 | @param[out] timeout | |
594 | @parblock | |
595 | <strong>On success</strong>, this function sets \lt_p{*timeout} to | |
596 | one of: | |
597 | ||
598 | <dl> | |
599 | <dt>-1 | |
600 | <dd> | |
601 | The blocking timeout of \lt_p{channel} is infinite. | |
602 | ||
603 | <dt>0 | |
604 | <dd> | |
605 | Blocking is disabled for \lt_p{channel}. | |
606 | ||
607 | <dt>Otherwise | |
608 | <dd> | |
609 | The blocking timeout of \lt_p{channel} is | |
610 | \lt_p{*timeout} µs. | |
611 | </dl> | |
612 | @endparblock | |
613 | ||
614 | @returns | |
615 | 0 on success, or a \em negative #lttng_error_code enumerator | |
616 | otherwise. | |
617 | ||
618 | @lt_pre_not_null{channel} | |
619 | @pre | |
620 | The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST. | |
621 | @lt_pre_not_null{timeout} | |
622 | ||
623 | @sa lttng_channel_set_blocking_timeout() -- | |
624 | Sets the blocking timeout property of a channel summary. | |
625 | */ | |
626 | LTTNG_EXPORT extern int lttng_channel_get_blocking_timeout(struct lttng_channel *channel, | |
627 | int64_t *timeout); | |
628 | ||
629 | /*! | |
630 | @brief | |
631 | Sets the \ref api-channel-blocking-timeout "blocking timeout" | |
632 | property of the channel summary \lt_p{channel} to | |
633 | \lt_p{timeout}. | |
634 | ||
635 | @ingroup api_channel | |
636 | ||
637 | This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink | |
638 | channels. | |
639 | ||
640 | @param[in] channel | |
641 | Channel summary of which to set the blocking timeout | |
642 | to \lt_p{timeout}. | |
643 | @param[in] timeout | |
644 | @parblock | |
645 | One of: | |
646 | ||
647 | <dl> | |
648 | <dt>-1 | |
649 | <dd> | |
650 | The blocking timeout of \lt_p{channel} is infinite. | |
651 | ||
652 | <dt>0 | |
653 | <dd> | |
654 | Blocking is disabled for \lt_p{channel}. | |
5ba3702f | 655 | |
048f01ef PP |
656 | <dt>Otherwise |
657 | <dd> | |
658 | The blocking timeout of \lt_p{channel} is | |
659 | \lt_p{timeout} µs. | |
660 | </dl> | |
661 | @endparblock | |
cf0bcb51 | 662 | |
048f01ef PP |
663 | @returns |
664 | 0 on success, or a \em negative #lttng_error_code enumerator | |
665 | otherwise. | |
cf0bcb51 | 666 | |
048f01ef PP |
667 | @lt_pre_not_null{channel} |
668 | @pre | |
669 | The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST. | |
670 | @pre | |
671 | \lt_p{timeout} ≥ -1 | |
491d1539 | 672 | |
048f01ef PP |
673 | @sa lttng_channel_get_blocking_timeout() -- |
674 | Returns the blocking timeout property of a channel summary. | |
675 | */ | |
676 | LTTNG_EXPORT extern int lttng_channel_set_blocking_timeout(struct lttng_channel *channel, | |
677 | int64_t timeout); | |
491d1539 | 678 | |
1239a312 DG |
679 | #ifdef __cplusplus |
680 | } | |
681 | #endif | |
682 | ||
683 | #endif /* LTTNG_CHANNEL_H */ |