1 #ifndef BABELTRACE_CTF_IR_TRACE_H
2 #define BABELTRACE_CTF_IR_TRACE_H
5 * BabelTrace - CTF IR: Trace
7 * Copyright 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
33 #include <babeltrace/ctf-ir/field-types.h>
34 #include <babeltrace/ctf-ir/visitor.h>
35 #include <babeltrace/values.h>
36 #include <babeltrace/graph/notification.h>
44 @defgroup ctfirtraceclass CTF IR trace class
46 @brief CTF IR trace class.
49 #include <babeltrace/ctf-ir/trace.h>
52 A CTF IR <strong><em>trace class</em></strong> is a descriptor of
55 You can obtain a trace class in two different modes:
57 - <strong>Normal mode</strong>: use bt_ctf_trace_create() to create a
58 default, empty trace class.
59 - <strong>CTF writer mode</strong>: use bt_ctf_writer_get_trace() to
60 get the trace class created by a given CTF writer object.
62 A trace class has the following properties:
65 - A <strong>default byte order</strong>: all the
66 \link ctfirfieldtypes field types\endlink eventually part of the trace
67 class with a byte order set to #BT_CTF_BYTE_ORDER_NATIVE have this
70 - An \b environment, which is a custom key-value mapping. Keys are
71 strings and values can be strings or integers.
73 In the Babeltrace CTF IR system, a trace class contains zero or more
74 \link ctfirstreamclass stream classes\endlink, and a stream class
75 contains zero or more \link ctfireventclass event classes\endlink. You
76 can add an event class to a stream class with
77 bt_ctf_stream_class_add_event_class(). You can add a stream class to a
78 trace class with bt_ctf_trace_add_stream_class().
80 You can access the streams of a trace, that is, the streams which were
81 created from the trace's stream classes with bt_ctf_stream_create(),
82 with bt_ctf_trace_get_stream_by_index().
84 A trace class owns the <strong>trace packet header</strong>
85 \link ctfirfieldtypes field type\endlink, which represents the
86 \c trace.packet.header CTF scope. This field type describes the
87 trace packet header fields of the traces that this trace class
90 The trace packet header field type \em must be a structure field type as
91 of Babeltrace \btversion.
93 As per the CTF specification, the trace packet header field type \em
94 must contain a field named \c stream_id if the trace class contains more
95 than one stream class.
97 As a reminder, here's the structure of a CTF packet:
101 A trace class also contains zero or more
102 \link ctfirclockclass CTF IR clock classes\endlink.
105 Elaborate about clock classes irt clock values.
107 As with any Babeltrace object, CTF IR trace class objects have
108 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
109 counts</a>. See \ref refs to learn more about the reference counting
110 management of Babeltrace objects.
112 The following functions \em freeze their trace class parameter on
115 - bt_ctf_trace_add_stream_class()
116 - bt_ctf_writer_create_stream()
117 (\link ctfwriter CTF writer\endlink mode only)
119 You cannot modify a frozen trace class: it is considered immutable,
122 - Adding a stream class to it with
123 bt_ctf_trace_add_stream_class().
124 - Adding a CTF IR clock class to it with bt_ctf_trace_add_clock_class().
125 - \link refs Reference counting\endlink.
127 You can add a custom listener with bt_ctf_trace_add_listener() to get
128 notified if anything changes in a trace class, that is, if an event
129 class is added to one of its stream class, if a stream class is added,
130 or if a clock class is added.
137 @brief CTF IR trace class type and functions.
140 @addtogroup ctfirtraceclass
146 @brief A CTF IR trace class.
150 struct bt_ctf_stream
;
151 struct bt_ctf_stream_class
;
152 struct bt_ctf_clock_class
;
155 @name Creation function
160 @brief Creates a default CTF IR trace class.
162 On success, the trace packet header field type of the created trace
163 class has the following fields:
165 - <code>magic</code>: a 32-bit unsigned integer field type.
166 - <code>uuid</code>: an array field type of 16 8-bit unsigned integer
168 - <code>stream_id</code>: a 32-bit unsigned integer field type.
170 You can modify this default trace packet header field type after the
171 trace class is created with bt_ctf_trace_set_packet_header_type().
173 The created trace class has the following initial properties:
175 - <strong>Name</strong>: none. You can set a name
176 with bt_ctf_trace_set_name().
177 - <strong>Default byte order</strong>: #BT_CTF_BYTE_ORDER_NATIVE. You
178 can set a default byte order with bt_ctf_trace_set_native_byte_order().
180 Note that you \em must set the default byte order if any field type
181 contained in the created trace class, in its stream classes, or in
182 its event classes, has a byte order set to #BT_CTF_BYTE_ORDER_NATIVE.
183 - <strong>Environment</strong>: empty. You can add environment entries
184 with bt_ctf_trace_set_environment_field(),
185 bt_ctf_trace_set_environment_field_integer(), and
186 bt_ctf_trace_set_environment_field_string().
188 @returns Created trace class, or \c NULL on error.
190 @postsuccessrefcountret1
192 extern struct bt_ctf_trace
*bt_ctf_trace_create(void);
197 @name Properties functions
202 @brief Returns the name of the CTF IR trace class \p trace_class.
204 On success, \p trace_class remains the sole owner of the returned
205 string. The returned string is valid as long as \p trace_class exists
208 @param[in] trace_class Trace class of which to get the name.
209 @returns Name of trace class \p trace_class, or
210 \c NULL if \p trace_class is unnamed or
213 @prenotnull{trace_class}
214 @postrefcountsame{trace_class}
216 @sa bt_ctf_trace_set_name(): Sets the name of a given trace class.
218 extern const char *bt_ctf_trace_get_name(struct bt_ctf_trace
*trace_class
);
221 @brief Sets the name of the CTF IR trace class \p trace_class
224 @param[in] trace_class Trace class of which to set the name.
225 @param[in] name Name of the trace class (copied on success).
226 @returns 0 on success, or a negative value on error.
228 @prenotnull{trace_class}
231 @postrefcountsame{trace_class}
233 @sa bt_ctf_trace_get_name(): Returns the name of a given trace class.
235 extern int bt_ctf_trace_set_name(struct bt_ctf_trace
*trace_class
,
239 @brief Returns the default byte order of the CTF IR trace class
242 @param[in] trace_class Trace class of which to get the default byte
244 @returns Default byte order of trace class
245 \p trace_class, or #BT_CTF_BYTE_ORDER_UNKNOWN
248 @prenotnull{trace_class}
249 @postrefcountsame{trace_class}
251 @sa bt_ctf_trace_set_name(): Sets the name of a given trace class.
253 extern enum bt_ctf_byte_order
bt_ctf_trace_get_byte_order(
254 struct bt_ctf_trace
*trace_class
);
257 @brief Sets the default byte order of the CTF IR trace class
258 \p trace_class to \p native_byte_order.
260 \p native_byte_order \em must be one of:
262 - #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
263 - #BT_CTF_BYTE_ORDER_BIG_ENDIAN
264 - #BT_CTF_BYTE_ORDER_NETWORK
266 @param[in] trace_class Trace class of which to set the default byte
268 @param[in] native_byte_order Default byte order of the trace class.
269 @returns 0 on success, or a negative value on error.
271 @prenotnull{trace_class}
274 @pre \p native_byte_order is either #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
275 #BT_CTF_BYTE_ORDER_BIG_ENDIAN, or
276 #BT_CTF_BYTE_ORDER_NETWORK.
277 @postrefcountsame{trace_class}
279 @sa bt_ctf_trace_get_name(): Returns the name of a given trace class.
281 extern int bt_ctf_trace_set_native_byte_order(struct bt_ctf_trace
*trace_class
,
282 enum bt_ctf_byte_order native_byte_order
);
285 @brief Returns the UUID of the CTF IR trace class \p trace_class.
287 On success, the return value is an array of 16 bytes.
289 @param[in] trace_class Trace class of which to get the UUID.
290 @returns UUID of trace class \p trace_class, or
291 \c NULL if \p trace_class has no UUID or on error.
293 @prenotnull{trace_class}
294 @postrefcountsame{trace_class}
296 @sa bt_ctf_trace_set_uuid(): Sets the UUID of a given trace class.
298 extern const unsigned char *bt_ctf_trace_get_uuid(
299 struct bt_ctf_trace
*trace_class
);
302 @brief Sets the UUID of the CTF IR trace class \p trace_class to
305 \p uuid \em must be an array of 16 bytes.
307 @param[in] trace_class Trace class of which to set the UUID.
308 @param[in] uuid UUID of the \p trace_class (copied on
310 @returns 0 on success, or a negative value on error.
312 @prenotnull{trace_class}
315 @pre \p uuid is an array of 16 bytes.
316 @postrefcountsame{trace_class}
318 @sa bt_ctf_trace_get_uuid(): Returns the UUID of a given trace class.
320 extern int bt_ctf_trace_set_uuid(struct bt_ctf_trace
*trace_class
,
321 const unsigned char *uuid
);
324 @brief Returns the number of entries contained in the environment of
325 the CTF IR trace class \p trace_class.
327 @param[in] trace_class Trace class of which to get the number
328 of environment entries.
329 @returns Number of environment entries
330 contained in \p trace_class, or
331 a negative value on error.
333 @prenotnull{trace_class}
334 @postrefcountsame{trace_class}
336 extern int64_t bt_ctf_trace_get_environment_field_count(
337 struct bt_ctf_trace
*trace_class
);
340 @brief Returns the field name of the environment entry at index
341 \p index in the CTF IR trace class \p trace_class.
343 On success, the returned string is valid as long as this trace class
344 exists and is \em not modified. \p trace_class remains the sole owner of
347 @param[in] trace_class Trace class of which to get the name of the
348 environment entry at index \p index.
349 @param[in] index Index of environment entry to find.
350 @returns Name of the environment entry at index \p index
351 in \p trace_class, or \c NULL on error.
353 @prenotnull{trace_class}
354 @pre \p index is lesser than the number of environment entries in
355 \p trace_class (see bt_ctf_trace_get_environment_field_count()).
356 @postrefcountsame{trace_class}
358 @sa bt_ctf_trace_get_environment_field_value_by_index(): Finds a trace class's
359 environment entry by index.
360 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
361 class's environment entry by name.
362 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
363 class's environment entry.
366 bt_ctf_trace_get_environment_field_name_by_index(
367 struct bt_ctf_trace
*trace_class
, uint64_t index
);
370 @brief Returns the value of the environment entry at index
371 \p index in the CTF IR trace class \p trace_class.
373 @param[in] trace_class Trace class of which to get the value of the
374 environment entry at index \p index.
375 @param[in] index Index of the environment entry to find.
376 @returns Value of the environment entry at index \p index
377 in \p trace_class, or \c NULL on error.
379 @prenotnull{trace_class}
380 @pre \p index is lesser than the number of environment entries in
381 \p trace_class (see bt_ctf_trace_get_environment_field_count()).
382 @postrefcountsame{trace_class}
383 @postsuccessrefcountretinc
385 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
386 class's environment entry by name.
387 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
388 class's environment entry.
390 extern struct bt_value
*
391 bt_ctf_trace_get_environment_field_value_by_index(struct bt_ctf_trace
*trace_class
,
395 @brief Returns the value of the environment entry named \p name
396 in the CTF IR trace class \p trace_class.
398 @param[in] trace_class Trace class of which to get the value of the
399 environment entry named \p name.
400 @param[in] name Name of the environment entry to find.
401 @returns Value of the environment entry named \p name
402 in \p trace_class, or \c NULL if there's no such
405 @prenotnull{trace_class}
407 @postrefcountsame{trace_class}
408 @postsuccessrefcountretinc
410 @sa bt_ctf_trace_get_environment_field_value_by_index(): Finds a trace class's
411 environment entry by index.
412 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
413 class's environment entry.
415 extern struct bt_value
*
416 bt_ctf_trace_get_environment_field_value_by_name(
417 struct bt_ctf_trace
*trace_class
, const char *name
);
420 @brief Sets the environment entry named \p name in the
421 CTF IR trace class \p trace_class to \p value.
423 If an environment entry named \p name exists in \p trace_class, its
424 value is first put, and then replaced by \p value.
426 @param[in] trace_class Trace class of which to set the environment
428 @param[in] name Name of the environment entry to set (copied
430 @param[in] value Value of the environment entry named \p name.
431 @returns 0 on success, or a negative value on error.
433 @prenotnull{trace_class}
438 \link bt_value_integer_create() integer value object\endlink
440 \link bt_value_string_create() string value object\endlink.
441 @postrefcountsame{trace_class}
442 @postsuccessrefcountinc{value}
444 @sa bt_ctf_trace_get_environment_field_value_by_index(): Finds a trace class's
445 environment entry by index.
446 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
447 class's environment entry by name.
449 extern int bt_ctf_trace_set_environment_field(
450 struct bt_ctf_trace
*trace_class
, const char *name
,
451 struct bt_value
*value
);
454 @brief Sets the environment entry named \p name in the
455 CTF IR trace class \p trace_class to \p value.
457 If an environment entry named \p name exists in \p trace_class, its
458 value is first put, and then replaced by a new
459 \link bt_value_integer_create() integer value object\endlink
462 @param[in] trace_class Trace class of which to set the environment
464 @param[in] name Name of the environment entry to set (copied
466 @param[in] value Value of the environment entry named \p name.
467 @returns 0 on success, or a negative value on error.
469 @prenotnull{trace_class}
472 @postrefcountsame{trace_class}
474 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
475 class's environment entry.
477 extern int bt_ctf_trace_set_environment_field_integer(
478 struct bt_ctf_trace
*trace_class
, const char *name
,
482 @brief Sets the environment entry named \p name in the
483 CTF IR trace class \p trace_class to \p value.
485 If an environment entry named \p name exists in \p trace_class, its
486 value is first put, and then replaced by a new
487 \link bt_value_string_create() string value object\endlink
490 @param[in] trace_class Trace class of which to set the environment
492 @param[in] name Name of the environment entry to set (copied
494 @param[in] value Value of the environment entry named \p name
496 @returns 0 on success, or a negative value on error.
498 @prenotnull{trace_class}
502 @postrefcountsame{trace_class}
504 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
505 class's environment entry.
507 extern int bt_ctf_trace_set_environment_field_string(
508 struct bt_ctf_trace
*trace_class
, const char *name
,
514 @name Contained field types functions
519 @brief Returns the packet header field type of the CTF IR trace class
522 @param[in] trace_class Trace class of which to get the packet
524 @returns Packet header field type of \p trace_class,
525 or \c NULL if \p trace_class has no packet header field
528 @prenotnull{trace_class}
529 @postrefcountsame{trace_class}
530 @post <strong>On success, if the return value is a field type</strong>, its
531 reference count is incremented.
533 @sa bt_ctf_trace_set_packet_header_type(): Sets the packet
534 header field type of a given trace class.
536 extern struct bt_ctf_field_type
*bt_ctf_trace_get_packet_header_type(
537 struct bt_ctf_trace
*trace_class
);
540 @brief Sets the packet header field type of the CTF IR trace class
541 \p trace_class to \p packet_header_type, or unsets the current packet
542 header field type from \p trace_class.
544 If \p packet_header_type is \c NULL, then this function unsets the current
545 packet header field type from \p trace_class, effectively making \p trace_class
546 a trace without a packet header field type.
548 As of Babeltrace \btversion, if \p packet_header_type is not \c NULL,
549 \p packet_header_type \em must be a CTF IR structure field type object.
551 @param[in] trace_class Trace class of which to set the packet
553 @param[in] packet_header_type Packet header field type, or \c NULL to unset
554 the current packet header field type.
555 @returns 0 on success, or a negative value on error.
557 @prenotnull{trace_class}
559 @pre <strong>\p packet_header_type, if not \c NULL</strong>, is a CTF IR
560 structure field type.
561 @postrefcountsame{trace_class}
562 @post <strong>On success, if \p packet_header_type is not \c NULL</strong>,
563 the reference count of \p packet_header_type is incremented.
565 @sa bt_ctf_trace_get_packet_header_type(): Returns the packet
566 header field type of a given trace class.
568 extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace
*trace_class
,
569 struct bt_ctf_field_type
*packet_header_type
);
574 @name Contained clock classes functions
579 @brief Returns the number of CTF IR clock classes contained in the
580 CTF IR trace class \p trace_class.
582 @param[in] trace_class Trace class of which to get the number
583 of contained clock classes.
584 @returns Number of contained clock classes
585 contained in \p trace_class, or a negative
588 @prenotnull{trace_class}
589 @postrefcountsame{trace_class}
591 extern int64_t bt_ctf_trace_get_clock_class_count(
592 struct bt_ctf_trace
*trace_class
);
595 @brief Returns the CTF IR clock class at index \p index in the CTF
596 IR trace class \p trace_class.
598 @param[in] trace_class Trace class of which to get the clock class
599 contained at index \p index.
600 @param[in] index Index of the clock class to find in
602 @returns Clock class at index \p index in \p trace_class,
605 @prenotnull{trace_class}
606 @pre \p index is lesser than the number of clock classes contained in
607 the trace class \p trace_class (see
608 bt_ctf_trace_get_clock_class_count()).
609 @postrefcountsame{trace_class}
610 @postsuccessrefcountretinc
612 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
613 in a given trace class.
614 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
616 extern struct bt_ctf_clock_class
*bt_ctf_trace_get_clock_class_by_index(
617 struct bt_ctf_trace
*trace_class
, uint64_t index
);
620 @brief Returns the CTF IR clock class named \c name found in the CTF
621 IR trace class \p trace_class.
623 @param[in] trace_class Trace class of which to get the clock class
625 @param[in] name Name of the clock class to find in \p trace_class.
626 @returns Clock class named \p name in \p trace_class,
629 @prenotnull{trace_class}
631 @postrefcountsame{trace_class}
632 @postsuccessrefcountretinc
634 @sa bt_ctf_trace_get_clock_class_by_index(): Returns the clock class contained
635 in a given trace class at a given index.
636 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
638 extern struct bt_ctf_clock_class
*bt_ctf_trace_get_clock_class_by_name(
639 struct bt_ctf_trace
*trace_class
, const char *name
);
642 @brief Adds the CTF IR clock class \p clock_class to the CTF IR
643 trace class \p trace_class.
645 On success, \p trace_class contains \p clock_class.
647 You can call this function even if \p trace_class or \p clock_class
650 @param[in] trace_class Trace class to which to add \p clock_class.
651 @param[in] clock_class Clock class to add to \p trace_class.
652 @returns 0 on success, or a negative value on error.
654 @prenotnull{trace_class}
655 @prenotnull{clock_class}
656 @postrefcountsame{trace_class}
657 @postsuccessrefcountinc{clock_class}
658 @post <strong>On success, if \p trace_class is frozen</strong>,
659 \p clock_class is frozen.
661 @sa bt_ctf_trace_get_clock_class_by_index(): Returns the clock class contained
662 in a given trace class at a given index.
663 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
664 in a given trace class.
666 extern int bt_ctf_trace_add_clock_class(struct bt_ctf_trace
*trace_class
,
667 struct bt_ctf_clock_class
*clock_class
);
672 @name Stream class children functions
677 @brief Returns the number of stream classes contained in the
678 CTF IR trace class \p trace_class.
680 @param[in] trace_class Trace class of which to get the number
681 of children stream classes.
682 @returns Number of children stream classes
683 contained in \p trace_class, or a negative
686 @prenotnull{trace_class}
687 @postrefcountsame{trace_class}
689 extern int64_t bt_ctf_trace_get_stream_class_count(
690 struct bt_ctf_trace
*trace_class
);
693 @brief Returns the stream class at index \p index in the CTF IR trace
694 class \p trace_class.
696 @param[in] trace_class Trace class of which to get the stream class.
697 @param[in] index Index of the stream class to find.
698 @returns Stream class at index \p index, or \c NULL
701 @prenotnull{trace_class}
702 @pre \p index is lesser than the number of stream classes contained in
703 the trace class \p trace_class (see
704 bt_ctf_trace_get_stream_class_count()).
705 @postrefcountsame{trace_class}
707 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
708 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
710 extern struct bt_ctf_stream_class
*bt_ctf_trace_get_stream_class_by_index(
711 struct bt_ctf_trace
*trace_class
, uint64_t index
);
714 @brief Returns the stream class with ID \c id found in the CTF IR
715 trace class \p trace_class.
717 @param[in] trace_class Trace class of which to get the stream class.
718 @param[in] id ID of the stream class to find.
719 @returns Stream class with ID \p id, or \c NULL
722 @prenotnull{trace_class}
723 @postrefcountsame{trace_class}
724 @postsuccessrefcountretinc
726 @sa bt_ctf_trace_get_stream_class_by_index(): Returns the stream class contained
727 in a given trace class at a given index.
728 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
730 extern struct bt_ctf_stream_class
*bt_ctf_trace_get_stream_class_by_id(
731 struct bt_ctf_trace
*trace_class
, uint64_t id
);
734 @brief Adds the CTF IR stream class \p stream_class to the
735 CTF IR trace class \p trace_class.
737 On success, \p stream_class becomes the child of \p trace_class.
739 You can only add a given stream class to one trace class.
741 You can call this function even if \p trace_class is frozen.
743 This function tries to resolve the needed
744 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
745 types that are found anywhere in the root field types of
746 \p stream_class and of all its currently contained
747 \link ctfireventclass CTF IR event classes\endlink. If any automatic
748 resolving fails, then this function fails.
750 @param[in] trace_class Trace class to which to add \p stream_class.
751 @param[in] stream_class Stream class to add to \p trace_class.
752 @returns 0 on success, or a negative value on error.
754 @prenotnull{trace_class}
755 @prenotnull{stream_class}
756 @postrefcountsame{trace_class}
757 @postsuccessrefcountinc{stream_class}
758 @postsuccessfrozen{stream_class}
760 @sa bt_ctf_trace_get_stream_class_by_index(): Returns the stream class contained
761 in a given trace class at a given index.
762 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
764 extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace
*trace_class
,
765 struct bt_ctf_stream_class
*stream_class
);
770 @name Stream children functions
775 @brief Returns the number of streams contained in the CTF IR trace
776 class \p trace_class.
778 @param[in] trace_class Trace class of which to get the number
780 @returns Number of children streams
781 contained in \p trace_class, or a negative
784 @prenotnull{trace_class}
785 @postrefcountsame{trace_class}
787 extern int64_t bt_ctf_trace_get_stream_count(struct bt_ctf_trace
*trace_class
);
790 @brief Returns the stream at index \p index in the CTF IR trace
791 class \p trace_class.
793 @param[in] trace_class Trace class of which to get the stream.
794 @param[in] index Index of the stream to find.
795 @returns Stream at index \p index, or \c NULL
798 @prenotnull{trace_class}
799 @pre \p index is lesser than the number of streams contained in
800 the trace class \p trace_class (see
801 bt_ctf_trace_get_stream_count()).
802 @postrefcountsame{trace_class}
804 extern struct bt_ctf_stream
*bt_ctf_trace_get_stream_by_index(
805 struct bt_ctf_trace
*trace_class
, uint64_t index
);
810 @name Misc. functions
815 @brief Returns whether or not the CTF IR trace class \p trace_class
818 It is guaranteed that a static trace class will never contain new
819 streams, stream classes, or clock classes. A static class is always
822 This function returns \c true if bt_ctf_trace_set_is_static() was
823 previously called on it.
825 @param[in] trace_class Trace class to check.
826 @returns \c true if \p trace_class is static,
828 @sa bt_ctf_trace_set_is_static(): Makes a trace class static.
830 extern bool bt_ctf_trace_is_static(struct bt_ctf_trace
*trace_class
);
833 @brief Makes the CTF IR trace class \p trace_class static.
835 A static trace class is frozen and you cannot call any modifying
838 - bt_ctf_trace_add_stream_class()
839 - bt_ctf_trace_add_clock_class()
841 You cannot create a stream with bt_ctf_stream_create() with any of the
842 stream classes of a static trace class.
844 @param[in] trace_class Trace class to make static.
845 @returns 0 on success, or a negative value on error.
847 @prenotnull{trace_class}
848 @postrefcountsame{trace_class}
849 @postsuccessfrozen{trace_class}
851 @sa bt_ctf_trace_is_static(): Checks whether or not a given trace class
854 extern int bt_ctf_trace_set_is_static(struct bt_ctf_trace
*trace_class
);
857 @brief Accepts the visitor \p visitor to visit the hierarchy of the
858 CTF IR trace class \p trace_class.
860 This function traverses the hierarchy of \p trace_class in pre-order
861 and calls \p visitor on each element.
863 The trace class itself is visited first, then, for each children stream
864 class, the stream class itself, and all its children event classes.
866 @param[in] trace_class Trace class to visit.
867 @param[in] visitor Visiting function.
868 @param[in] data User data.
869 @returns 0 on success, or a negative value on error.
871 @prenotnull{trace_class}
874 extern int bt_ctf_trace_visit(struct bt_ctf_trace
*trace_class
,
875 bt_ctf_visitor visitor
, void *data
);
882 * bt_ctf_trace_get_metadata_string: get metadata string.
884 * Get the trace's TSDL metadata. The caller assumes the ownership of the
887 * @param trace Trace instance.
889 * Returns the metadata string on success, NULL on error.
891 extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace
*trace
);
897 #endif /* BABELTRACE_CTF_IR_TRACE_H */