4 * Babeltrace Python Module interface file
6 * Copyright 2012 EfficiOS Inc.
8 * Author: Danny Serres <danny.serres@efficios.com>
10 * Permission is hereby granted, free of charge, to any person obtaining a copy
11 * of this software and associated documentation files (the "Software"), to deal
12 * in the Software without restriction, including without limitation the rights
13 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14 * copies of the Software, and to permit persons to whom the Software is
15 * furnished to do so, subject to the following conditions:
17 * The above copyright notice and this permission notice shall be included in
18 * all copies or substantial portions of the Software.
23 "BABELTRACE_VERSION_STR
25 Babeltrace is a trace viewer and converter reading and writing the
26 Common Trace Format (CTF). Its main use is to pretty-print CTF
27 traces into a human-readable text output.
29 To use this module, the first step is to create a Context and add a
33 %module(docstring=DOCSTRING) babeltrace
37 #define SWIG_FILE_WITH_INIT
38 #include <babeltrace/babeltrace.h>
39 #include <babeltrace/babeltrace-internal.h>
40 #include <babeltrace/trace-handle.h>
41 #include <babeltrace/trace-handle-internal.h>
42 #include <babeltrace/context.h>
43 #include <babeltrace/context-internal.h>
44 #include <babeltrace/iterator.h>
45 #include <babeltrace/iterator-internal.h>
46 #include <babeltrace/format.h>
47 #include <babeltrace/list.h>
48 #include <babeltrace/types.h>
49 #include <babeltrace/ctf/iterator.h>
50 #include "python-complements.h"
53 typedef unsigned long long uint64_t;
54 typedef long long int64_t;
55 typedef int bt_intern_str;
57 /* =================================================================
58 CONTEXT.H, CONTEXT-INTERNAL.H
59 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
62 %rename("_bt_context_create") bt_context_create(void);
63 %rename("_bt_context_add_trace") bt_context_add_trace(
64 struct bt_context *ctx, const char *path, const char *format,
65 void (*packet_seek)(struct bt_stream_pos *pos, size_t index, int whence),
66 struct bt_mmap_stream_list *stream_list, FILE *metadata);
67 %rename("_bt_context_remove_trace") bt_context_remove_trace(
68 struct bt_context *ctx, int trace_id);
69 %rename("_bt_context_get") bt_context_get(struct bt_context *ctx);
70 %rename("_bt_context_put") bt_context_put(struct bt_context *ctx);
71 %rename("_bt_ctf_event_get_context") bt_ctf_event_get_context(
72 const struct bt_ctf_event *event);
74 struct bt_context *bt_context_create(void);
75 int bt_context_add_trace(struct bt_context *ctx, const char *path, const char *format,
76 void (*packet_seek)(struct bt_stream_pos *pos, size_t index, int whence),
77 struct bt_mmap_stream_list *stream_list, FILE *metadata);
78 void bt_context_remove_trace(struct bt_context *ctx, int trace_id);
79 void bt_context_get(struct bt_context *ctx);
80 void bt_context_put(struct bt_context *ctx);
81 struct bt_context *bt_ctf_event_get_context(const struct bt_ctf_event *event);
83 // class Context to prevent direct access to struct bt_context
87 The context represents the object in which a trace_collection is
88 open. As long as this structure is allocated, the trace_collection
89 is open and the traces it contains can be read and seeked by the
90 iterators and callbacks.
94 self._c = _bt_context_create()
97 _bt_context_put(self._c)
99 def add_trace(self, path, format_str,
100 packet_seek=None, stream_list=None, metadata=None):
102 Add a trace by path to the context.
106 path is the path to the trace, it is not recursive.
107 If "path" is None, stream_list is used instead as a list
108 of mmap streams to open for the trace.
110 format is a string containing the format name in which the trace was
113 packet_seek is not implemented for Python. Should be left None to
114 use the default packet_seek handler provided by the trace format.
116 stream_list is a linked list of streams, it is used to open a trace
117 where the trace data is located in memory mapped areas instead of
118 trace files, this argument should be None when path is not None.
120 The metadata parameter acts as a metadata override when not None,
121 otherwise the format handles the metadata opening.
123 Return: the corresponding TraceHandle on success or None on error.
125 if metadata is not None:
126 metadata = metadata._file
128 ret = _bt_context_add_trace(self._c, path, format_str, packet_seek,
129 stream_list, metadata)
133 th = TraceHandle.__new__(TraceHandle)
137 def add_traces_recursive(self, path, format_str):
139 Open a trace recursively.
141 Find each trace present in the subdirectory starting from the given
142 path, and add them to the context.
144 Return a dict of TraceHandle instances (the full path is the key).
145 Return None on error.
155 for fullpath, dirs, files in os.walk(path):
156 if "metadata" in files:
157 trace_handle = self.add_trace(fullpath, format_str)
158 if trace_handle is None:
162 trace_handles[fullpath] = trace_handle
165 if noTrace and error:
169 def remove_trace(self, trace_handle):
171 Remove a trace from the context.
172 Effectively closing the trace.
175 _bt_context_remove_trace(self._c, trace_handle._id)
176 except AttributeError:
177 raise TypeError("in remove_trace, "
178 "argument 2 must be a TraceHandle instance")
183 /* =================================================================
188 %rename("lookup_format") bt_lookup_format(bt_intern_str qname);
189 %rename("_bt_print_format_list") bt_fprintf_format_list(FILE *fp);
190 %rename("register_format") bt_register_format(struct format *format);
191 %rename("unregister_format") bt_unregister_format(struct bt_format *format);
193 extern struct format *bt_lookup_format(bt_intern_str qname);
194 extern void bt_fprintf_format_list(FILE *fp);
195 extern int bt_register_format(struct bt_format *format);
196 extern void bt_unregister_format(struct bt_format *format);
200 def print_format_list(babeltrace_file):
202 Print a list of available formats to file.
204 babeltrace_file must be a File instance opened in write mode.
207 if babeltrace_file._file is not None:
208 _bt_print_format_list(babeltrace_file._file)
209 except AttributeError:
210 raise TypeError("in print_format_list, "
211 "argument 1 must be a File instance")
216 /* =================================================================
217 ITERATOR.H, ITERATOR-INTERNAL.H
218 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
221 %rename("_bt_iter_create") bt_iter_create(struct bt_context *ctx,
222 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
223 %rename("_bt_iter_destroy") bt_iter_destroy(struct bt_iter *iter);
224 %rename("_bt_iter_next") bt_iter_next(struct bt_iter *iter);
225 %rename("_bt_iter_get_pos") bt_iter_get_pos(struct bt_iter *iter);
226 %rename("_bt_iter_free_pos") bt_iter_free_pos(struct bt_iter_pos *pos);
227 %rename("_bt_iter_set_pos") bt_iter_set_pos(struct bt_iter *iter,
228 const struct bt_iter_pos *pos);
229 %rename("_bt_iter_create_time_pos") bt_iter_create_time_pos(struct bt_iter *iter,
232 struct bt_iter *bt_iter_create(struct bt_context *ctx,
233 const struct bt_iter_pos *begin_pos, const struct bt_iter_pos *end_pos);
234 void bt_iter_destroy(struct bt_iter *iter);
235 int bt_iter_next(struct bt_iter *iter);
236 struct bt_iter_pos *bt_iter_get_pos(struct bt_iter *iter);
237 void bt_iter_free_pos(struct bt_iter_pos *pos);
238 int bt_iter_set_pos(struct bt_iter *iter, const struct bt_iter_pos *pos);
239 struct bt_iter_pos *bt_iter_create_time_pos(struct bt_iter *iter, uint64_t timestamp);
241 %rename("_bt_iter_pos") bt_iter_pos;
242 %rename("SEEK_TIME") BT_SEEK_TIME;
243 %rename("SEEK_RESTORE") BT_SEEK_RESTORE;
244 %rename("SEEK_CUR") BT_SEEK_CUR;
245 %rename("SEEK_BEGIN") BT_SEEK_BEGIN;
246 %rename("SEEK_LAST") BT_SEEK_LAST;
248 // This struct is taken from iterator.h
249 // All changes to the struct must also be made here
252 BT_SEEK_TIME, /* uses u.seek_time */
253 BT_SEEK_RESTORE, /* uses u.restore */
260 struct bt_saved_pos *restore;
268 """This class represents the position where to set an iterator."""
272 def __init__(self, seek_type, seek_time = None):
274 seek_type represents the type of seek to use.
275 seek_time is the timestamp to seek to when using SEEK_TIME, it
276 is expressed in nanoseconds
277 Only use SEEK_RESTORE on IterPos obtained from the get_pos function
281 self._pos = _bt_iter_pos()
282 self._pos.type = seek_type
283 if seek_time and seek_type == SEEK_TIME:
284 self._pos.u.seek_time = seek_time
285 self.__can_access = True
288 if not self.__can_access:
289 _bt_iter_free_pos(self._pos)
293 raise AttributeError("seek_type is not available")
294 return self._pos.type
296 def _set_type(self, seek_type):
298 raise AttributeError("seek_type is not available")
299 self._pos.type = seek_type
303 raise AttributeError("seek_time is not available")
305 elif self._pos.type is not SEEK_TIME:
306 raise TypeError("seek_type is not SEEK_TIME")
308 return self._pos.u.seek_time
310 def _set_time(self, time):
312 raise AttributeError("seek_time is not available")
314 elif self._pos.type is not SEEK_TIME:
315 raise TypeError("seek_type is not SEEK_TIME")
317 self._pos.u.seek_time = time
323 seek_type = property(_get_type, _set_type)
324 seek_time = property(_get_time, _set_time)
331 def __init__(self, context, begin_pos = None, end_pos = None, _no_init = None):
333 Allocate a trace collection iterator.
335 begin_pos and end_pos are optional parameters to specify the
336 position at which the trace collection should be seeked upon
337 iterator creation, and the position at which iteration will
338 start returning "EOF".
340 By default, if begin_pos is None, a BT_SEEK_CUR is performed at
341 creation. By default, if end_pos is None, a BT_SEEK_END (end of
342 trace) is the EOF criterion.
345 if begin_pos is None:
350 except AttributeError:
351 raise TypeError("in __init__, "
352 "argument 3 must be a IterPos instance")
359 except AttributeError:
360 raise TypeError("in __init__, "
361 "argument 4 must be a IterPos instance")
364 self._bi = _bt_iter_create(context._c, bp, ep)
365 except AttributeError:
366 raise TypeError("in __init__, "
367 "argument 2 must be a Context instance")
369 self.__with_init = True
376 _bt_iter_destroy(self._bi)
380 Move trace collection position to the next event.
381 Returns 0 on success, a negative value on error.
383 return _bt_iter_next(self._bi)
386 """Return a IterPos class of the current iterator position."""
388 ret.__can_access = False
389 ret._pos = _bt_iter_get_pos(self._bi)
392 def set_pos(self, pos):
394 Move the iterator to a given position.
396 On error, the stream_heap is reinitialized and returned empty.
397 Return 0 for success.
398 Return EOF if the position requested is after the last event of the
400 Return -EINVAL when called with invalid parameter.
401 Return -ENOMEM if the stream_heap could not be properly initialized.
404 return _bt_iter_set_pos(self._bi, pos._pos)
405 except AttributeError:
406 raise TypeError("in set_pos, "
407 "argument 2 must be a IterPos instance")
409 def create_time_pos(self, timestamp):
411 Create a position based on time
412 This function allocates and returns a new IterPos to be able to
413 restore an iterator position based on a timestamp.
417 raise TypeError("timestamp must be an unsigned int")
420 ret.__can_access = False
421 ret._pos = _bt_iter_create_time_pos(self._bi, timestamp)
426 /* =================================================================
429 *** Enum copied from clock-type.h
430 All changes must also be made here
432 %rename("CLOCK_CYCLES") BT_CLOCK_CYCLES;
433 %rename("CLOCK_REAL") BT_CLOCK_REAL;
440 /* =================================================================
441 TRACE-HANDLE.H, TRACE-HANDLE-INTERNAL.H
442 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
445 %rename("_bt_trace_handle_create") bt_trace_handle_create(struct bt_context *ctx);
446 %rename("_bt_trace_handle_destroy") bt_trace_handle_destroy(struct bt_trace_handle *bt);
447 struct bt_trace_handle *bt_trace_handle_create(struct bt_context *ctx);
448 void bt_trace_handle_destroy(struct bt_trace_handle *bt);
450 %rename("_bt_trace_handle_get_path") bt_trace_handle_get_path(struct bt_context *ctx,
452 %rename("_bt_trace_handle_get_timestamp_begin") bt_trace_handle_get_timestamp_begin(
453 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
454 %rename("_bt_trace_handle_get_timestamp_end") bt_trace_handle_get_timestamp_end(
455 struct bt_context *ctx, int handle_id, enum bt_clock_type type);
456 const char *bt_trace_handle_get_path(struct bt_context *ctx, int handle_id);
457 uint64_t bt_trace_handle_get_timestamp_begin(struct bt_context *ctx, int handle_id,
458 enum bt_clock_type type);
459 uint64_t bt_trace_handle_get_timestamp_end(struct bt_context *ctx, int handle_id,
460 enum bt_clock_type type);
462 %rename("_bt_ctf_event_get_handle_id") bt_ctf_event_get_handle_id(
463 const struct bt_ctf_event *event);
464 int bt_ctf_event_get_handle_id(const struct bt_ctf_event *event);
469 class TraceHandle(object):
471 The TraceHandle allows the user to manipulate a trace file directly.
472 It is a unique identifier representing a trace file.
477 raise NotImplementedError("TraceHandle cannot be instantiated")
480 return "Babeltrace TraceHandle: trace_id('{0}')".format(self._id)
483 """Return the TraceHandle id."""
486 def get_path(self, context):
487 """Return the path of a TraceHandle."""
489 return _bt_trace_handle_get_path(context._c, self._id)
490 except AttributeError:
491 raise TypeError("in get_path, "
492 "argument 2 must be a Context instance")
494 def get_timestamp_begin(self, context, clock_type):
495 """Return the creation time of the buffers of a trace."""
497 return _bt_trace_handle_get_timestamp_begin(
498 context._c, self._id,clock_type)
499 except AttributeError:
500 raise TypeError("in get_timestamp_begin, "
501 "argument 2 must be a Context instance")
503 def get_timestamp_end(self, context, clock_type):
504 """Return the destruction timestamp of the buffers of a trace."""
506 return _bt_trace_handle_get_timestamp_end(
507 context._c, self._id, clock_type)
508 except AttributeError:
509 raise TypeError("in get_timestamp_end, "
510 "argument 2 must be a Context instance")
516 // =================================================================
518 // =================================================================
520 /* =================================================================
526 %rename("_bt_ctf_iter_create") bt_ctf_iter_create(struct bt_context *ctx,
527 const struct bt_iter_pos *begin_pos,
528 const struct bt_iter_pos *end_pos);
529 %rename("_bt_ctf_get_iter") bt_ctf_get_iter(struct bt_ctf_iter *iter);
530 %rename("_bt_ctf_iter_destroy") bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
531 %rename("_bt_ctf_iter_read_event") bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
533 struct bt_ctf_iter *bt_ctf_iter_create(struct bt_context *ctx,
534 const struct bt_iter_pos *begin_pos,
535 const struct bt_iter_pos *end_pos);
536 struct bt_iter *bt_ctf_get_iter(struct bt_ctf_iter *iter);
537 void bt_ctf_iter_destroy(struct bt_ctf_iter *iter);
538 struct bt_ctf_event *bt_ctf_iter_read_event(struct bt_ctf_iter *iter);
543 %rename("_bt_ctf_get_top_level_scope") bt_ctf_get_top_level_scope(const struct
544 bt_ctf_event *event, enum bt_ctf_scope scope);
545 %rename("_bt_ctf_event_name") bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
546 %rename("_bt_ctf_get_timestamp") bt_ctf_get_timestamp(
547 const struct bt_ctf_event *ctf_event);
548 %rename("_bt_ctf_get_cycles") bt_ctf_get_cycles(
549 const struct bt_ctf_event *ctf_event);
551 %rename("_bt_ctf_get_field") bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
552 const struct bt_definition *scope, const char *field);
553 %rename("_bt_ctf_get_index") bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
554 const struct bt_definition *field, unsigned int index);
555 %rename("_bt_ctf_field_name") bt_ctf_field_name(const struct bt_definition *field);
556 %rename("_bt_ctf_field_type") bt_ctf_field_type(const struct bt_declaration *field);
557 %rename("_bt_ctf_get_int_signedness") bt_ctf_get_int_signedness(
558 const struct bt_declaration *field);
559 %rename("_bt_ctf_get_int_base") bt_ctf_get_int_base(const struct bt_declaration *field);
560 %rename("_bt_ctf_get_int_byte_order") bt_ctf_get_int_byte_order(
561 const struct bt_declaration *field);
562 %rename("_bt_ctf_get_int_len") bt_ctf_get_int_len(const struct bt_declaration *field);
563 %rename("_bt_ctf_get_enum_int") bt_ctf_get_enum_int(const struct bt_definition *field);
564 %rename("_bt_ctf_get_enum_str") bt_ctf_get_enum_str(const struct bt_definition *field);
565 %rename("_bt_ctf_get_encoding") bt_ctf_get_encoding(const struct bt_declaration *field);
566 %rename("_bt_ctf_get_array_len") bt_ctf_get_array_len(const struct bt_declaration *field);
567 %rename("_bt_ctf_get_uint64") bt_ctf_get_uint64(const struct bt_definition *field);
568 %rename("_bt_ctf_get_int64") bt_ctf_get_int64(const struct bt_definition *field);
569 %rename("_bt_ctf_get_char_array") bt_ctf_get_char_array(const struct bt_definition *field);
570 %rename("_bt_ctf_get_string") bt_ctf_get_string(const struct bt_definition *field);
571 %rename("_bt_ctf_field_get_error") bt_ctf_field_get_error(void);
572 %rename("_bt_ctf_get_decl_event_name") bt_ctf_get_decl_event_name(const struct
573 bt_ctf_event_decl *event);
574 %rename("_bt_ctf_get_decl_field_name") bt_ctf_get_decl_field_name(
575 const struct bt_ctf_field_decl *field);
576 %rename("_bt_ctf_get_decl_from_def") bt_ctf_get_decl_from_def(
577 const struct bt_definition *field);
578 %rename("_bt_array_index") bt_array_index(struct definition_array *array, uint64_t i);
580 const struct bt_definition *bt_ctf_get_top_level_scope(const struct bt_ctf_event *ctf_event,
581 enum bt_ctf_scope scope);
582 const char *bt_ctf_event_name(const struct bt_ctf_event *ctf_event);
583 uint64_t bt_ctf_get_timestamp(const struct bt_ctf_event *ctf_event);
584 uint64_t bt_ctf_get_cycles(const struct bt_ctf_event *ctf_event);
585 const struct bt_definition *bt_ctf_get_field(const struct bt_ctf_event *ctf_event,
586 const struct bt_definition *scope,
588 const struct bt_definition *bt_ctf_get_index(const struct bt_ctf_event *ctf_event,
589 const struct bt_definition *field,
591 const char *bt_ctf_field_name(const struct bt_definition *field);
592 enum ctf_type_id bt_ctf_field_type(const struct bt_declaration *field);
593 int bt_ctf_get_int_signedness(const struct bt_declaration *field);
594 int bt_ctf_get_int_base(const struct bt_declaration *field);
595 int bt_ctf_get_int_byte_order(const struct bt_declaration *field);
596 ssize_t bt_ctf_get_int_len(const struct bt_declaration *field);
597 const struct bt_definition *bt_ctf_get_enum_int(const struct bt_definition *field);
598 const char *bt_ctf_get_enum_str(const struct bt_definition *field);
599 enum ctf_string_encoding bt_ctf_get_encoding(const struct bt_declaration *field);
600 int bt_ctf_get_array_len(const struct bt_declaration *field);
601 struct bt_definition *bt_array_index(struct definition_array *array, uint64_t i);
602 uint64_t bt_ctf_get_uint64(const struct bt_definition *field);
603 int64_t bt_ctf_get_int64(const struct bt_definition *field);
604 char *bt_ctf_get_char_array(const struct bt_definition *field);
605 char *bt_ctf_get_string(const struct bt_definition *field);
606 int bt_ctf_field_get_error(void);
607 const char *bt_ctf_get_decl_event_name(const struct bt_ctf_event_decl *event);
608 const char *bt_ctf_get_decl_field_name(const struct bt_ctf_field_decl *field);
609 const struct bt_declaration *bt_ctf_get_decl_from_def(const struct bt_definition *field);
615 #enum equivalent, accessible constants
616 #These are taken directly from ctf/events.h
617 #All changes to enums must also be made here
632 TRACE_PACKET_HEADER = 0
633 STREAM_PACKET_CONTEXT = 1
634 STREAM_EVENT_HEADER = 2
635 STREAM_EVENT_CONTEXT = 3
639 class string_encoding:
645 class Iterator(Iterator, object):
647 Allocate a CTF trace collection iterator.
649 begin_pos and end_pos are optional parameters to specify the
650 position at which the trace collection should be seeked upon
651 iterator creation, and the position at which iteration will
652 start returning "EOF".
654 By default, if begin_pos is None, a SEEK_CUR is performed at
655 creation. By default, if end_pos is None, a SEEK_END (end of
656 trace) is the EOF criterion.
658 Only one iterator can be created against a context. If more than one
659 iterator is being created for the same context, the second creation
660 will return None. The previous iterator must be destroyed before
661 creation of the new iterator for this function to succeed.
664 def __new__(cls, context, begin_pos = None, end_pos = None):
665 # __new__ is used to control the return value
666 # as the ctf.Iterator class should return None
667 # if bt_ctf_iter_create returns NULL
669 if begin_pos is None:
678 it = _bt_ctf_iter_create(context._c, bp, ep)
679 except AttributeError:
680 raise TypeError("in __init__, "
681 "argument 2 must be a Context instance")
685 ret_class = super(ctf.Iterator, cls).__new__(cls)
689 def __init__(self, context, begin_pos = None, end_pos = None):
690 Iterator.__init__(self, None, None, None,
691 _bt_ctf_get_iter(self._i))
694 _bt_ctf_iter_destroy(self._i)
696 def read_event(self):
698 Read the iterator's current event data.
699 Return current event on success, None on end of trace.
701 ret = _bt_ctf_iter_read_event(self._i)
704 ev = ctf.Event.__new__(ctf.Event)
711 This class represents an event from the trace.
712 It is obtained with read_event() from ctf.Iterator.
717 raise NotImplementedError("ctf.Event cannot be instantiated")
719 def get_top_level_scope(self, scope):
721 Return a definition of the top-level scope
722 Top-level scopes are defined in ctf.scope.
723 In order to get a field or a field list, the user needs to pass a
724 scope as argument, this scope can be a top-level scope or a scope
725 relative to an arbitrary field. This function provides the mapping
726 between the scope and the actual definition of top-level scopes.
727 On error return None.
729 evDef = ctf.Definition.__new__(ctf.Definition)
730 evDef._d = _bt_ctf_get_top_level_scope(self._e, scope)
736 """Return the name of the event or None on error."""
737 return _bt_ctf_event_name(self._e)
739 def get_cycles(self):
741 Return the timestamp of the event as written in
742 the packet (in cycles) or -1ULL on error.
744 return _bt_ctf_get_cycles(self._e)
746 def get_timestamp(self):
748 Return the timestamp of the event offsetted with the
749 system clock source or -1ULL on error.
751 return _bt_ctf_get_timestamp(self._e)
753 def get_field_with_scope(self, scope, field):
755 Return the definition of a specific field.
756 Return None on error.
758 evDef = ctf.Definition.__new__(ctf.Definition)
760 evDef._d = _bt_ctf_get_field(self._e, scope._d, field)
761 except AttributeError:
762 raise TypeError("in get_field, argument 2 must be a "
763 "Definition (scope) instance")
769 def get_field(self, field):
771 Return the definition of fields by a name
774 eventScope = self.get_top_level_scope(ctf.scope.EVENT_FIELDS)
775 streamScope = self.get_top_level_scope(ctf.scope.STREAM_EVENT_CONTEXT)
778 if eventScope is not None:
779 evDef = self.get_field_with_scope(eventScope, field)
780 if evDef is not None:
781 fields_by_name.append(evDef)
783 if streamScope is not None:
784 evDef = self.get_field_with_scope(streamScope, field)
785 if evDef is not None:
786 fields_by_name.append(evDef);
788 if not fields_by_name:
790 return fields_by_name
792 def get_field_list_with_scope(self, scope):
794 Return a list of Definitions associated with the scope
795 Return None on error.
798 field_lc = _bt_python_field_listcaller(self._e, scope._d)
799 except AttributeError:
800 raise TypeError("in get_field_list, argument 2 must be a "
801 "Definition (scope) instance")
809 tmp = ctf.Definition.__new__(ctf.Definition)
810 tmp._d = _bt_python_field_one_from_list(field_lc, i)
813 #Last item of list is None, assured in
814 #_bt_python_field_listcaller
822 def get_field_list(self):
823 """Return a list of Definitions or None on error."""
824 eventScope = self.get_top_level_scope(ctf.scope.EVENT_FIELDS)
825 streamScope = self.get_top_level_scope(ctf.scope.STREAM_EVENT_CONTEXT)
828 if eventScope is not None:
829 event_field_list = self.get_field_list_with_scope(eventScope)
830 if event_field_list is not None:
831 def_list = event_field_list
833 if streamScope is not None:
834 event_field_list = self.get_field_list_with_scope(streamScope)
835 if event_field_list is not None:
836 def_list.extend(event_field_list)
842 def get_index(self, field, index):
844 If the field is an array or a sequence, return the element
845 at position index, otherwise return None
847 evDef = ctf.Definition.__new__(ctf.Definition)
849 evDef._d = _bt_ctf_get_index(self._e, field._d, index)
850 except AttributeError:
851 raise TypeError("in get_index, argument 2 must be a "
852 "Definition (field) instance")
858 def get_handle(self):
860 Get the TraceHandle associated with an event
863 ret = _bt_ctf_event_get_handle_id(self._e)
867 th = TraceHandle.__new__(TraceHandle)
871 def get_context(self):
873 Get the context associated with an event.
874 Return None on error.
877 ctx._c = _bt_ctf_event_get_context(self._e);
884 class Definition(object):
885 """Definition class. Do not instantiate."""
888 raise NotImplementedError("ctf.Definition cannot be instantiated")
891 return "Babeltrace Definition: name('{0}'), type({1})".format(
892 self.field_name(), self.field_type())
894 def field_name(self):
895 """Return the name of a field or None on error."""
896 return _bt_ctf_field_name(self._d)
898 def field_type(self):
899 """Return the type of a field or -1 if unknown."""
900 return _bt_ctf_field_type(_bt_ctf_get_decl_from_def(self._d))
902 def get_int_signedness(self):
904 Return the signedness of an integer:
905 0 if unsigned; 1 if signed; -1 on error.
907 return _bt_ctf_get_int_signedness(_bt_ctf_get_decl_from_def(self._d))
909 def get_int_base(self):
910 """Return the base of an int or a negative value on error."""
911 return _bt_ctf_get_int_base(_bt_ctf_get_decl_from_def(self._d))
913 def get_int_byte_order(self):
915 Return the byte order of an int or a negative
918 return _bt_ctf_get_int_byte_order(_bt_ctf_get_decl_from_def(self._d))
920 def get_int_len(self):
922 Return the size, in bits, of an int or a negative
925 return _bt_ctf_get_int_len(_bt_ctf_get_decl_from_def(self._d))
927 def get_enum_str(self):
929 Return the string matching the current enumeration.
930 Return None on error.
932 return _bt_ctf_get_enum_str(self._d)
934 def get_encoding(self):
936 Return the encoding of an int or a string.
937 Return a negative value on error.
939 return _bt_ctf_get_encoding(_bt_ctf_get_decl_from_def(self._d))
941 def get_array_len(self):
943 Return the len of an array or a negative
946 return _bt_ctf_get_array_len(_bt_ctf_get_decl_from_def(self._d))
948 def get_array_element_at(self, index):
950 Return the array's element at position index.
953 array = _bt_python_get_array_from_def(self._d)
957 element = ctf.Definition.__new__(ctf.Definition)
958 element._d = _bt_array_index(array, index)
959 if element._d is None:
963 def get_uint64(self):
965 Return the value associated with the field.
966 If the field does not exist or is not of the type requested,
967 the value returned is undefined. To check if an error occured,
968 use the ctf.field_error() function after accessing a field.
970 return _bt_ctf_get_uint64(self._d)
974 Return the value associated with the field.
975 If the field does not exist or is not of the type requested,
976 the value returned is undefined. To check if an error occured,
977 use the ctf.field_error() function after accessing a field.
979 return _bt_ctf_get_int64(self._d)
981 def get_char_array(self):
983 Return the value associated with the field.
984 If the field does not exist or is not of the type requested,
985 the value returned is undefined. To check if an error occured,
986 use the ctf.field_error() function after accessing a field.
988 return _bt_ctf_get_char_array(self._d)
992 Return the value associated with the field.
993 If the field does not exist or is not of the type requested,
994 the value returned is undefined. To check if an error occured,
995 use the ctf.field_error() function after accessing a field.
997 return _bt_ctf_get_string(self._d)
1001 Return the value associated with the field according to its type.
1002 Return None on error.
1004 id = self.field_type()
1005 if id == ctf.type_id.STRING:
1006 return self.get_str()
1007 if id == ctf.type_id.ARRAY:
1009 for i in range(self.get_array_len()):
1010 element = self.get_array_element_at(i)
1011 array.append(element.get_value())
1013 if id == ctf.type_id.INTEGER:
1014 if self.get_int_signedness() == 0:
1015 return self.get_uint64()
1017 return self.get_int64()
1018 if id == ctf.type_id.ENUM:
1019 return self.get_enum_str()
1022 def get_scope(self):
1023 """Return the scope of a field or None on error."""
1026 class EventDecl(object):
1027 """Event declaration class. Do not instantiate."""
1030 raise NotImplementedError("ctf.EventDecl cannot be instantiated")
1033 return "Babeltrace EventDecl: name {0}".format(self.get_name())
1036 """Return the name of the event or None on error"""
1037 return _bt_ctf_get_decl_event_name(self._d)
1039 def get_decl_fields(self, scope):
1041 Return a list of ctf.FieldDecl
1042 Return None on error.
1044 ptr_list = _by_python_field_decl_listcaller(self._d, scope)
1046 if ptr_list is None:
1052 tmp = ctf.FieldDecl.__new__(ctf.FieldDecl)
1053 tmp._d = _bt_python_field_decl_one_from_list(
1057 #Last item of list is None
1060 decl_list.append(tmp)
1065 class FieldDecl(object):
1066 """Field declaration class. Do not instantiate."""
1069 raise NotImplementedError("ctf.FieldDecl cannot be instantiated")
1072 return "Babeltrace FieldDecl: name {0}".format(self.get_name())
1075 """Return the name of a FieldDecl or None on error"""
1076 return _bt_ctf_get_decl_field_name(self._d)
1082 Return the last error code encountered while
1083 accessing a field and reset the error flag.
1084 Return 0 if no error, a negative value otherwise.
1086 return _bt_ctf_field_get_error()
1089 def get_event_decl_list(trace_handle, context):
1091 Return a list of ctf.EventDecl
1092 Return None on error.
1095 handle_id = trace_handle._id
1096 except AttributeError:
1097 raise TypeError("in get_event_decl_list, "
1098 "argument 1 must be a TraceHandle instance")
1100 ptr_list = _bt_python_event_decl_listcaller(handle_id, context._c)
1101 except AttributeError:
1102 raise TypeError("in get_event_decl_list, "
1103 "argument 2 must be a Context instance")
1105 if ptr_list is None:
1111 tmp = ctf.EventDecl.__new__(ctf.EventDecl)
1112 tmp._d = _bt_python_decl_one_from_list(ptr_list, i)
1115 #Last item of list is None
1118 decl_list.append(tmp)
1126 // =================================================================
1128 // File and list-related
1129 // python-complements.h
1130 // =================================================================
1132 %include python-complements.c
1138 Open a file for babeltrace.
1140 file_path is a string containing the path or None to use the
1141 standard output in writing mode.
1143 The mode can be 'r', 'w' or 'a' for reading (default), writing or
1144 appending. The file will be created if it doesn't exist when
1145 opened for writing or appending; it will be truncated when opened
1146 for writing. Add a 'b' to the mode for binary files. Add a '+'
1147 to the mode to allow simultaneous reading and writing.
1150 def __new__(cls, file_path, mode='r'):
1151 # __new__ is used to control the return value
1152 # as the File class should return None
1153 # if _bt_file_open returns NULL
1156 if file_path is not None and type(file_path) is not str:
1157 raise TypeError("in method __init__, argument 2 of type 'str'")
1158 if type(mode) is not str:
1159 raise TypeError("in method __init__, argument 3 of type 'str'")
1162 file_ptr = _bt_file_open(file_path, mode)
1163 if file_ptr is None:
1166 # Class instantiation
1167 file_inst = super(File, cls).__new__(cls)
1168 file_inst._file = file_ptr
1171 def __init__(self, file_path, mode='r'):
1173 self._use_stdout = False
1175 if file_path is None:
1177 file_path = "stdout"
1179 self._use_stdout = True
1181 self._file_path = file_path
1192 return "{0} babeltrace File; file_path('{1}'), mode('{2}')".format(
1193 stat, self._file_path, self._mode)
1196 """Close the file. Is also called using del."""
1197 if self._opened and not self._use_stdout:
1198 _bt_file_close(self._file)
1199 self._opened = False