/**
* SECTION:gstinfo
+ * @title: GstInfo
* @short_description: Debugging and logging facilities
* @see_also: #gst-running for command line parameters
* and environment variables that affect the debugging output.
* categories. This is easily done with 3 lines. At the top of your code,
* declare
* the variables and set the default category.
- * |[
+ * |[<!-- language="C" -->
* GST_DEBUG_CATEGORY_STATIC (my_category); // define category (statically)
* #define GST_CAT_DEFAULT my_category // set as default
* ]|
* After that you only need to initialize the category.
- * |[
+ * |[<!-- language="C" -->
* GST_DEBUG_CATEGORY_INIT (my_category, "my category",
* 0, "This is my very own");
* ]|
#undef gst_debug_add_log_function
#ifndef GST_DISABLE_GST_DEBUG
-
#ifdef HAVE_DLFCN_H
# include <dlfcn.h>
#endif
static char *gst_info_printf_pointer_extension_func (const char *format,
void *ptr);
+#else /* GST_DISABLE_GST_DEBUG */
+#include <glib/gprintf.h>
#endif /* !GST_DISABLE_GST_DEBUG */
+#ifdef HAVE_UNWIND
+/* No need for remote debugging so turn on the 'local only' optimizations in
+ * libunwind */
+#define UNW_LOCAL_ONLY
+
+#include <libunwind.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <stdarg.h>
+#include <unistd.h>
+#include <errno.h>
+
+#ifdef HAVE_DW
+#include <elfutils/libdwfl.h>
+#endif /* HAVE_DW */
+#endif /* HAVE_UNWIND */
+
+#ifdef HAVE_BACKTRACE
+#include <execinfo.h>
+#define BT_BUF_SIZE 100
+#endif /* HAVE_BACKTRACE */
+
extern gboolean gst_is_initialized (void);
/* we want these symbols exported even if debug is disabled, to maintain
#endif /* __sgi__ */
#endif
+static const gchar *_gst_debug_filter = NULL;
+
static void gst_debug_reset_threshold (gpointer category, gpointer unused);
static void gst_debug_reset_all_thresholds (void);
static GMutex __log_func_mutex;
static GSList *__log_functions = NULL;
+/* whether to add the default log function in gst_init() */
+static gboolean add_default_log_func = TRUE;
+
#define PRETTY_TAGS_DEFAULT TRUE
static gboolean pretty_tags = PRETTY_TAGS_DEFAULT;
return (in_valgrind == GST_VG_INSIDE);
}
+static gchar *
+_replace_pattern_in_gst_debug_file_name (gchar * name, const char *token,
+ guint val)
+{
+ gchar *token_start;
+ if ((token_start = strstr (name, token))) {
+ gsize token_len = strlen (token);
+ gchar *name_prefix = name;
+ gchar *name_suffix = token_start + token_len;
+ token_start[0] = '\0';
+ name = g_strdup_printf ("%s%u%s", name_prefix, val, name_suffix);
+ g_free (name_prefix);
+ }
+ return name;
+}
+
+static gchar *
+_priv_gst_debug_file_name (const gchar * env)
+{
+ gchar *name;
+
+ name = g_strdup (env);
+ name = _replace_pattern_in_gst_debug_file_name (name, "%p", getpid ());
+ name = _replace_pattern_in_gst_debug_file_name (name, "%r", g_random_int ());
+
+ return name;
+}
+
/* Initialize the debugging system */
void
_priv_gst_debug_init (void)
const gchar *env;
FILE *log_file;
- env = g_getenv ("GST_DEBUG_FILE");
- if (env != NULL && *env != '\0') {
- if (strcmp (env, "-") == 0) {
- log_file = stdout;
- } else {
- log_file = g_fopen (env, "w");
- if (log_file == NULL) {
- g_printerr ("Could not open log file '%s' for writing: %s\n", env,
- g_strerror (errno));
- log_file = stderr;
+ if (add_default_log_func) {
+ env = g_getenv ("GST_DEBUG_FILE");
+ if (env != NULL && *env != '\0') {
+ if (strcmp (env, "-") == 0) {
+ log_file = stdout;
+ } else {
+ gchar *name = _priv_gst_debug_file_name (env);
+ log_file = g_fopen (name, "w");
+ g_free (name);
+ if (log_file == NULL) {
+ g_printerr ("Could not open log file '%s' for writing: %s\n", env,
+ g_strerror (errno));
+ log_file = stderr;
+ }
}
+ } else {
+ log_file = stderr;
}
- } else {
- log_file = stderr;
+
+ gst_debug_add_log_function (gst_debug_log_default, log_file, NULL);
}
__gst_printf_pointer_extension_set_func
_GST_CAT_DEBUG = _gst_debug_category_new ("GST_DEBUG",
GST_DEBUG_BOLD | GST_DEBUG_FG_YELLOW, "debugging subsystem");
- gst_debug_add_log_function (gst_debug_log_default, log_file, NULL);
-
/* FIXME: add descriptions here */
GST_CAT_GST_INIT = _gst_debug_category_new ("GST_INIT",
GST_DEBUG_BOLD | GST_DEBUG_FG_RED, NULL);
if (env)
gst_debug_set_color_mode_from_string (env);
- env = g_getenv ("GST_DEBUG");
- if (env) {
- gst_debug_set_threshold_from_string (env, FALSE);
+ _gst_debug_filter = g_getenv ("GST_DEBUG");
+ if (_gst_debug_filter) {
+ gst_debug_set_threshold_from_string (_gst_debug_filter, FALSE);
}
}
return ret;
}
+static inline gchar *
+gst_info_describe_stream (GstStream * stream)
+{
+ gchar *ret, *caps_str = NULL, *tags_str = NULL;
+ GstCaps *caps;
+ GstTagList *tags;
+
+ caps = gst_stream_get_caps (stream);
+ if (caps) {
+ caps_str = gst_caps_to_string (caps);
+ gst_caps_unref (caps);
+ }
+
+ tags = gst_stream_get_tags (stream);
+ if (tags) {
+ tags_str = gst_tag_list_to_string (tags);
+ gst_tag_list_unref (tags);
+ }
+
+ ret =
+ g_strdup_printf ("stream %s %p, ID %s, flags 0x%x, caps [%s], tags [%s]",
+ gst_stream_type_get_name (gst_stream_get_stream_type (stream)), stream,
+ gst_stream_get_stream_id (stream), gst_stream_get_stream_flags (stream),
+ caps_str ? caps_str : "", tags_str ? tags_str : "");
+
+ g_free (caps_str);
+ g_free (tags_str);
+
+ return ret;
+}
+
+static inline gchar *
+gst_info_describe_stream_collection (GstStreamCollection * collection)
+{
+ gchar *ret;
+ GString *streams_str;
+ guint i;
+
+ streams_str = g_string_new ("<");
+ for (i = 0; i < gst_stream_collection_get_size (collection); i++) {
+ GstStream *stream = gst_stream_collection_get_stream (collection, i);
+ gchar *s;
+
+ s = gst_info_describe_stream (stream);
+ g_string_append_printf (streams_str, " %s,", s);
+ g_free (s);
+ }
+ g_string_append (streams_str, " >");
+
+ ret = g_strdup_printf ("collection %p (%d streams) %s", collection,
+ gst_stream_collection_get_size (collection), streams_str->str);
+
+ g_string_free (streams_str, TRUE);
+ return ret;
+}
+
static gchar *
gst_debug_print_object (gpointer ptr)
{
g_free (s);
return ret;
}
+ if (GST_IS_STREAM (object)) {
+ return gst_info_describe_stream (GST_STREAM_CAST (object));
+ }
+ if (GST_IS_STREAM_COLLECTION (object)) {
+ return
+ gst_info_describe_stream_collection (GST_STREAM_COLLECTION_CAST
+ (object));
+ }
if (GST_IS_PAD (object) && GST_OBJECT_NAME (object)) {
return g_strdup_printf ("<%s:%s>", GST_DEBUG_PAD_NAME (object));
}
case 'B': /* GST_SEGMENT_FORMAT */
s = gst_debug_print_segment (ptr);
break;
+ case 'a': /* GST_WRAPPED_PTR_FORMAT */
+ s = priv_gst_string_take_and_wrap (gst_debug_print_object (ptr));
+ break;
default:
/* must have been compiled against a newer version with an extension
* we don't known about yet - just ignore and fallback to %p below */
/**
* gst_debug_remove_log_function:
- * @func: (scope call): the log function to remove
+ * @func: (scope call) (allow-none): the log function to remove, or %NULL to
+ * remove the default log function
*
* Removes all registered instances of the given logging functions.
*
removals =
gst_debug_remove_with_compare_func
(gst_debug_compare_log_function_by_func, (gpointer) func);
- if (gst_is_initialized ())
+
+ if (gst_is_initialized ()) {
GST_DEBUG ("removed log function %p %d times from log function list", func,
removals);
+ } else {
+ /* If the default log function is removed before gst_init() was called,
+ * set a flag so we don't add it in gst_init() later */
+ if (func == gst_debug_log_default) {
+ add_default_log_func = FALSE;
+ ++removals;
+ }
+ }
return removals;
}
* If activated, debugging messages are sent to the debugging
* handlers.
* It makes sense to deactivate it for speed issues.
- * <note><para>This function is not threadsafe. It makes sense to only call it
- * during initialization.</para></note>
+ * > This function is not threadsafe. It makes sense to only call it
+ * during initialization.
*/
void
gst_debug_set_active (gboolean active)
}
g_mutex_unlock (&__cat_mutex);
+ /* ensure the filter is applied to categories registered after _debug_init */
+ if (_gst_debug_filter) {
+ gst_debug_set_threshold_from_string (_gst_debug_filter, FALSE);
+ }
+
return cat;
}
* Sets the threshold of the category to the given level. Debug information will
* only be output if the threshold is lower or equal to the level of the
* debugging message.
- * <note><para>
- * Do not use this function in production code, because other functions may
- * change the threshold of categories as side effect. It is however a nice
- * function to use when debugging (even from gdb).
- * </para></note>
+ * > Do not use this function in production code, because other functions may
+ * > change the threshold of categories as side effect. It is however a nice
+ * > function to use when debugging (even from gdb).
*/
void
gst_debug_category_set_threshold (GstDebugCategory * category,
const gchar *category;
if (parse_debug_category (values[0], &category)
- && parse_debug_level (values[1], &level))
+ && parse_debug_level (values[1], &level)) {
gst_debug_set_threshold_for_name (category, level);
+
+ /* bump min-level anyway to allow the category to be registered in the
+ * future still */
+ if (level > _gst_debug_min) {
+ _gst_debug_min = level;
+ }
+ }
}
g_strfreev (values);
* fallback function that cleans up the format string and replaces all pointer
* extension formats with plain %p. */
#ifdef GST_DISABLE_GST_DEBUG
-#include <glib/gprintf.h>
int
__gst_info_fallback_vasprintf (char **result, char const *format, va_list args)
{
}
#endif
-#ifdef GST_ENABLE_FUNC_INSTRUMENTATION
-/* FIXME make this thread specific */
-static GSList *stack_trace = NULL;
+/**
+ * gst_info_vasprintf:
+ * @result: (out): the resulting string
+ * @format: a printf style format string
+ * @args: the va_list of printf arguments for @format
+ *
+ * Allocates and fills a string large enough (including the terminating null
+ * byte) to hold the specified printf style @format and @args.
+ *
+ * This function deals with the GStreamer specific printf specifiers
+ * #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. If you do not have these specifiers
+ * in your @format string, you do not need to use this function and can use
+ * alternatives such as g_vasprintf().
+ *
+ * Free @result with g_free().
+ *
+ * Returns: the length of the string allocated into @result or -1 on any error
+ *
+ * Since: 1.8
+ */
+gint
+gst_info_vasprintf (gchar ** result, const gchar * format, va_list args)
+{
+ /* This will fallback to __gst_info_fallback_vasprintf() via a #define in
+ * gst_private.h if the debug system is disabled which will remove the gst
+ * specific printf format specifiers */
+ return __gst_vasprintf (result, format, args);
+}
+
+/**
+ * gst_info_strdup_vprintf:
+ * @format: a printf style format string
+ * @args: the va_list of printf arguments for @format
+ *
+ * Allocates, fills and returns a null terminated string from the printf style
+ * @format string and @args.
+ *
+ * See gst_info_vasprintf() for when this function is required.
+ *
+ * Free with g_free().
+ *
+ * Returns: a newly allocated null terminated string or %NULL on any error
+ *
+ * Since: 1.8
+ */
+gchar *
+gst_info_strdup_vprintf (const gchar * format, va_list args)
+{
+ gchar *ret;
+
+ if (gst_info_vasprintf (&ret, format, args) < 0)
+ ret = NULL;
+
+ return ret;
+}
+
+/**
+ * gst_info_strdup_printf:
+ * @format: a printf style format string
+ * @...: the printf arguments for @format
+ *
+ * Allocates, fills and returns a 0-terminated string from the printf style
+ * @format string and corresponding arguments.
+ *
+ * See gst_info_vasprintf() for when this function is required.
+ *
+ * Free with g_free().
+ *
+ * Returns: a newly allocated null terminated string or %NULL on any error
+ *
+ * Since: 1.8
+ */
+gchar *
+gst_info_strdup_printf (const gchar * format, ...)
+{
+ gchar *ret;
+ va_list args;
+
+ va_start (args, format);
+ ret = gst_info_strdup_vprintf (format, args);
+ va_end (args);
+ return ret;
+}
+
+/**
+ * gst_print:
+ * @format: a printf style format string
+ * @...: the printf arguments for @format
+ *
+ * Outputs a formatted message via the GLib print handler. The default print
+ * handler simply outputs the message to stdout.
+ *
+ * This function will not append a new-line character at the end, unlike
+ * gst_println() which will.
+ *
+ * All strings must be in ASCII or UTF-8 encoding.
+ *
+ * This function differs from g_print() in that it supports all the additional
+ * printf specifiers that are supported by GStreamer's debug logging system,
+ * such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT.
+ *
+ * This function is primarily for printing debug output.
+ *
+ * Since: 1.12
+ */
void
-__cyg_profile_func_enter (void *this_fn, void *call_site)
- G_GNUC_NO_INSTRUMENT;
- void __cyg_profile_func_enter (void *this_fn, void *call_site)
+gst_print (const gchar * format, ...)
{
- gchar *name = _gst_debug_nameof_funcptr (this_fn);
- gchar *site = _gst_debug_nameof_funcptr (call_site);
+ va_list args;
+ gchar *str;
- GST_CAT_DEBUG (GST_CAT_CALL_TRACE, "entering function %s from %s", name,
- site);
- stack_trace =
- g_slist_prepend (stack_trace, g_strdup_printf ("%8p in %s from %p (%s)",
- this_fn, name, call_site, site));
+ va_start (args, format);
+ str = gst_info_strdup_vprintf (format, args);
+ va_end (args);
- g_free (name);
- g_free (site);
+ g_print ("%s", str);
+ g_free (str);
}
+/**
+ * gst_println:
+ * @format: a printf style format string
+ * @...: the printf arguments for @format
+ *
+ * Outputs a formatted message via the GLib print handler. The default print
+ * handler simply outputs the message to stdout.
+ *
+ * This function will append a new-line character at the end, unlike
+ * gst_print() which will not.
+ *
+ * All strings must be in ASCII or UTF-8 encoding.
+ *
+ * This function differs from g_print() in that it supports all the additional
+ * printf specifiers that are supported by GStreamer's debug logging system,
+ * such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT.
+ *
+ * This function is primarily for printing debug output.
+ *
+ * Since: 1.12
+ */
void
-__cyg_profile_func_exit (void *this_fn, void *call_site)
- G_GNUC_NO_INSTRUMENT;
- void __cyg_profile_func_exit (void *this_fn, void *call_site)
+gst_println (const gchar * format, ...)
{
- gchar *name = _gst_debug_nameof_funcptr (this_fn);
+ va_list args;
+ gchar *str;
- GST_CAT_DEBUG (GST_CAT_CALL_TRACE, "leaving function %s", name);
- g_free (stack_trace->data);
- stack_trace = g_slist_delete_link (stack_trace, stack_trace);
+ va_start (args, format);
+ str = gst_info_strdup_vprintf (format, args);
+ va_end (args);
- g_free (name);
+ g_print ("%s\n", str);
+ g_free (str);
}
/**
- * gst_debug_print_stack_trace:
+ * gst_printerr:
+ * @format: a printf style format string
+ * @...: the printf arguments for @format
+ *
+ * Outputs a formatted message via the GLib error message handler. The default
+ * handler simply outputs the message to stderr.
+ *
+ * This function will not append a new-line character at the end, unlike
+ * gst_printerrln() which will.
+ *
+ * All strings must be in ASCII or UTF-8 encoding.
+ *
+ * This function differs from g_printerr() in that it supports the additional
+ * printf specifiers that are supported by GStreamer's debug logging system,
+ * such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT.
*
- * If GST_ENABLE_FUNC_INSTRUMENTATION is defined a stacktrace is available for
- * gstreamer code, which can be printed with this function.
+ * This function is primarily for printing debug output.
+ *
+ * Since: 1.12
*/
void
-gst_debug_print_stack_trace (void)
+gst_printerr (const gchar * format, ...)
{
- GSList *walk = stack_trace;
- gint count = 0;
+ va_list args;
+ gchar *str;
- if (walk)
- walk = g_slist_next (walk);
+ va_start (args, format);
+ str = gst_info_strdup_vprintf (format, args);
+ va_end (args);
- while (walk) {
- gchar *name = (gchar *) walk->data;
+ g_printerr ("%s", str);
+ g_free (str);
+}
+
+/**
+ * gst_printerrln:
+ * @format: a printf style format string
+ * @...: the printf arguments for @format
+ *
+ * Outputs a formatted message via the GLib error message handler. The default
+ * handler simply outputs the message to stderr.
+ *
+ * This function will append a new-line character at the end, unlike
+ * gst_printerr() which will not.
+ *
+ * All strings must be in ASCII or UTF-8 encoding.
+ *
+ * This function differs from g_printerr() in that it supports the additional
+ * printf specifiers that are supported by GStreamer's debug logging system,
+ * such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT.
+ *
+ * This function is primarily for printing debug output.
+ *
+ * Since: 1.12
+ */
+void
+gst_printerrln (const gchar * format, ...)
+{
+ va_list args;
+ gchar *str;
- g_print ("#%-2d %s\n", count++, name);
+ va_start (args, format);
+ str = gst_info_strdup_vprintf (format, args);
+ va_end (args);
- walk = g_slist_next (walk);
+ g_printerr ("%s\n", str);
+ g_free (str);
+}
+
+#ifdef HAVE_UNWIND
+#ifdef HAVE_DW
+static gboolean
+append_debug_info (GString * trace, Dwfl * dwfl, const void *ip)
+{
+ Dwfl_Line *line;
+ Dwarf_Addr addr;
+ Dwfl_Module *module;
+ const gchar *function_name;
+
+ if (dwfl_linux_proc_report (dwfl, getpid ()) != 0)
+ return FALSE;
+
+ if (dwfl_report_end (dwfl, NULL, NULL))
+ return FALSE;
+
+ addr = (uintptr_t) ip;
+ module = dwfl_addrmodule (dwfl, addr);
+ function_name = dwfl_module_addrname (module, addr);
+
+ g_string_append_printf (trace, "%s (", function_name ? function_name : "??");
+
+ line = dwfl_getsrc (dwfl, addr);
+ if (line != NULL) {
+ gint nline;
+ Dwarf_Addr addr;
+ const gchar *filename = dwfl_lineinfo (line, &addr,
+ &nline, NULL, NULL, NULL);
+
+ g_string_append_printf (trace, "%s:%d", strrchr (filename,
+ G_DIR_SEPARATOR) + 1, nline);
+ } else {
+ const gchar *eflfile = NULL;
+
+ dwfl_module_info (module, NULL, NULL, NULL, NULL, NULL, &eflfile, NULL);
+ g_string_append_printf (trace, "%s:%p", eflfile ? eflfile : "??", ip);
}
+
+ return TRUE;
+}
+#endif /* HAVE_DW */
+
+static gchar *
+generate_unwind_trace (GstStackTraceFlags flags)
+{
+ unw_context_t uc;
+ unw_cursor_t cursor;
+ gboolean use_libunwind = TRUE;
+ GString *trace = g_string_new (NULL);
+
+#ifdef HAVE_DW
+ Dwfl *dwfl = NULL;
+ Dwfl_Callbacks callbacks = {
+ .find_elf = dwfl_linux_proc_find_elf,
+ .find_debuginfo = dwfl_standard_find_debuginfo,
+ };
+
+ if ((flags & GST_STACK_TRACE_SHOW_FULL))
+ dwfl = dwfl_begin (&callbacks);
+#endif /* HAVE_DW */
+
+ unw_getcontext (&uc);
+ unw_init_local (&cursor, &uc);
+
+ while (unw_step (&cursor) > 0) {
+#ifdef HAVE_DW
+ if (dwfl) {
+ unw_word_t ip;
+
+ unw_get_reg (&cursor, UNW_REG_IP, &ip);
+ if (append_debug_info (trace, dwfl, (void *) (ip - 4))) {
+ use_libunwind = FALSE;
+ g_string_append (trace, ")\n");
+ }
+ }
+#endif /* HAVE_DW */
+
+ if (use_libunwind) {
+ char name[32];
+
+ unw_word_t offset = 0;
+ unw_get_proc_name (&cursor, name, sizeof (name), &offset);
+ g_string_append_printf (trace, "%s (0x%" G_GSIZE_FORMAT ")\n", name,
+ (gsize) offset);
+ }
+ }
+
+#ifdef HAVE_DW
+ if (dwfl)
+ dwfl_end (dwfl);
+#endif
+
+ return g_string_free (trace, FALSE);
+}
+
+#endif /* HAVE_UNWIND */
+
+#ifdef HAVE_BACKTRACE
+static gchar *
+generate_backtrace_trace (void)
+{
+ int j, nptrs;
+ void *buffer[BT_BUF_SIZE];
+ char **strings;
+ GString *trace;
+
+ trace = g_string_new (NULL);
+ nptrs = backtrace (buffer, BT_BUF_SIZE);
+
+ strings = backtrace_symbols (buffer, nptrs);
+
+ if (!strings)
+ return NULL;
+
+ for (j = 0; j < nptrs; j++)
+ g_string_append_printf (trace, "%s\n", strings[j]);
+
+ return g_string_free (trace, FALSE);
}
#else
+#define generate_backtrace_trace() NULL
+#endif /* HAVE_BACKTRACE */
+
+/**
+ * gst_debug_get_stack_trace:
+ * @flags: A set of #GstStackTraceFlags to determine how the stack
+ * trace should look like. Pass 0 to retrieve a minimal backtrace.
+ *
+ * If libunwind or glibc backtrace are present, a stack trace
+ * is returned.
+ *
+ * Since: 1.12
+ */
+gchar *
+gst_debug_get_stack_trace (GstStackTraceFlags flags)
+{
+ gchar *trace = NULL;
+#ifdef HAVE_BACKTRACE
+ gboolean have_backtrace = TRUE;
+#else
+ gboolean have_backtrace = FALSE;
+#endif
+
+#ifdef HAVE_UNWIND
+ if ((flags & GST_STACK_TRACE_SHOW_FULL) || !have_backtrace)
+ trace = generate_unwind_trace (flags);
+#endif /* HAVE_UNWIND */
+
+ if (trace)
+ return trace;
+ else if (have_backtrace)
+ return generate_backtrace_trace ();
+
+ return NULL;
+}
+
+/**
+ * gst_debug_print_stack_trace:
+ *
+ * If libunwind or glibc backtrace are present
+ * a stack trace is printed.
+ */
void
gst_debug_print_stack_trace (void)
{
- /* nothing because it's compiled out */
-}
+ gchar *trace = gst_debug_get_stack_trace (GST_STACK_TRACE_SHOW_FULL);
+
+ if (trace)
+ g_print ("%s\n", trace);
-#endif /* GST_ENABLE_FUNC_INSTRUMENTATION */
+ g_free (trace);
+}