2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
5 * gst.c: Initialization and non-pipeline operations
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
25 * @short_description: Media library supporting arbitrary formats and filter
27 * @see_also: Check out both <ulink url="http://www.cse.ogi.edu/sysl/">OGI's
28 * pipeline</ulink> and Microsoft's DirectShow for some background.
30 * GStreamer is a framework for constructing graphs of various filters
31 * (termed elements here) that will handle streaming media. Any discreet
32 * (packetizable) media type is supported, with provisions for automatically
33 * determining source type. Formatting/framing information is provided with
34 * a powerful negotiation framework. Plugins are heavily used to provide for
35 * all elements, allowing one to construct plugins outside of the GST
36 * library, even released binary-only if license require (please don't).
38 * GStreamer borrows heavily from both the <ulink
39 * url="http://www.cse.ogi.edu/sysl/">OGI media pipeline</ulink> and
40 * Microsoft's DirectShow, hopefully taking the best of both and leaving the
41 * cruft behind. Its interface is slowly getting stable.
43 * The <application>GStreamer</application> library should be initialized with
44 * gst_init() before it can be used. You should pass pointers to the main argc
45 * and argv variables so that GStreamer can process its own command line
46 * options, as shown in the following example.
49 * <title>Initializing the gstreamer library</title>
50 * <programlisting language="c">
52 * main (int argc, char *argv[])
54 * // initialize the GStreamer library
55 * gst_init (&argc, &argv);
61 * It's allowed to pass two NULL pointers to gst_init() in case you don't want
62 * to pass the command line args to GStreamer.
64 * You can also use GOption to initialize your own parameters as shown in
65 * the next code fragment:
67 * <title>Initializing own parameters when initializing gstreamer</title>
69 * static gboolean stats = FALSE;
72 * main (int argc, char *argv[])
74 * GOptionEntry options[] = {
75 * {"tags", 't', 0, G_OPTION_ARG_NONE, &tags,
76 * N_("Output tags (also known as metadata)"), NULL},
79 * // must initialise the threading system before using any other GLib funtion
80 * if (!g_thread_supported ())
81 * g_thread_init (NULL);
82 * ctx = g_option_context_new ("[ADDITIONAL ARGUMENTS]");
83 * g_option_context_add_main_entries (ctx, options, GETTEXT_PACKAGE);
84 * g_option_context_add_group (ctx, gst_init_get_option_group ());
85 * if (!g_option_context_parse (ctx, &argc, &argv, &err)) {
86 * g_print ("Error initializing: %s\n", GST_STR_NULL (err->message));
89 * g_option_context_free (ctx);
95 * Use gst_version() to query the library version at runtime or use the
96 * GST_VERSION_* macros to find the version at compile time. Optionally
97 * gst_version_string() returns a printable string.
99 * The gst_deinit() call is used to clean up all internal resources used
100 * by <application>GStreamer</application>. It is mostly used in unit tests
101 * to check for leaks.
103 * Last reviewed on 2006-08-11 (0.10.10)
106 #include "gst_private.h"
109 #include <sys/types.h>
111 #include <sys/wait.h>
112 #endif /* HAVE_FORK */
113 #ifdef HAVE_SYS_UTSNAME_H
114 #include <sys/utsname.h>
120 #include "gst-i18n-lib.h"
121 #include <locale.h> /* for LC_ALL */
125 #define GST_CAT_DEFAULT GST_CAT_GST_INIT
127 #define MAX_PATH_SPLIT 16
128 #define GST_PLUGIN_SEPARATOR ","
130 static gboolean gst_initialized = FALSE;
131 static gboolean gst_deinitialized = FALSE;
133 #ifndef GST_DISABLE_REGISTRY
134 static GList *plugin_paths = NULL; /* for delayed processing in post_init */
137 #ifndef GST_DISABLE_GST_DEBUG
138 extern const gchar *priv_gst_dump_dot_dir;
142 #if defined(HAVE_FORK) && !defined(GST_HAVE_UNSAFE_FORK)
143 #define DEFAULT_FORK TRUE
145 #define DEFAULT_FORK FALSE
146 #endif /* HAVE_FORK */
148 /* set to TRUE when segfaults need to be left as is */
149 static gboolean _gst_disable_segtrap = FALSE;
151 /* control the behaviour of registry rebuild */
152 static gboolean _gst_enable_registry_fork = DEFAULT_FORK;
154 static void load_plugin_func (gpointer data, gpointer user_data);
155 static gboolean init_pre (GOptionContext * context, GOptionGroup * group,
156 gpointer data, GError ** error);
157 static gboolean init_post (GOptionContext * context, GOptionGroup * group,
158 gpointer data, GError ** error);
159 #ifndef GST_DISABLE_OPTION_PARSING
160 static gboolean parse_goption_arg (const gchar * s_opt,
161 const gchar * arg, gpointer data, GError ** err);
164 static GSList *preload_plugins = NULL;
166 const gchar g_log_domain_gstreamer[] = "GStreamer";
169 debug_log_handler (const gchar * log_domain,
170 GLogLevelFlags log_level, const gchar * message, gpointer user_data)
172 g_log_default_handler (log_domain, log_level, message, user_data);
173 /* FIXME: do we still need this ? fatal errors these days are all
174 * other than core errors */
175 /* g_on_error_query (NULL); */
182 #ifndef GST_DISABLE_GST_DEBUG
193 ARG_REGISTRY_FORK_DISABLE
196 /* debug-spec ::= category-spec [, category-spec]*
197 * category-spec ::= category:val | val
206 #ifndef GST_DISABLE_GST_DEBUG
208 parse_debug_category (gchar * str, const gchar ** category)
225 parse_debug_level (gchar * str, gint * level)
233 if (str[0] != NUL && str[1] == NUL
234 && str[0] >= '0' && str[0] < '0' + GST_LEVEL_COUNT) {
235 *level = str[0] - '0';
243 parse_debug_list (const gchar * list)
248 g_return_if_fail (list != NULL);
250 split = g_strsplit (list, ",", 0);
252 for (walk = split; *walk; walk++) {
253 if (strchr (*walk, ':')) {
254 gchar **values = g_strsplit (*walk, ":", 2);
256 if (values[0] && values[1]) {
258 const gchar *category;
260 if (parse_debug_category (values[0], &category)
261 && parse_debug_level (values[1], &level))
262 gst_debug_set_threshold_for_name (category, level);
269 if (parse_debug_level (*walk, &level))
270 gst_debug_set_default_threshold (level);
279 * gst_init_get_option_group:
281 * Returns a #GOptionGroup with GStreamer's argument specifications. The
282 * group is set up to use standard GOption callbacks, so when using this
283 * group in combination with GOption parsing methods, all argument parsing
284 * and initialization is automated.
286 * This function is useful if you want to integrate GStreamer with other
287 * libraries that use GOption (see g_option_context_add_group() ).
289 * If you use this function, you should make sure you initialise the GLib
290 * threading system as one of the very first things in your program
291 * (see the example at the beginning of this section).
293 * Returns: a pointer to GStreamer's option group.
297 gst_init_get_option_group (void)
299 #ifndef GST_DISABLE_OPTION_PARSING
301 static const GOptionEntry gst_args[] = {
302 {"gst-version", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
303 (gpointer) parse_goption_arg, N_("Print the GStreamer version"), NULL},
304 {"gst-fatal-warnings", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
305 (gpointer) parse_goption_arg, N_("Make all warnings fatal"), NULL},
306 #ifndef GST_DISABLE_GST_DEBUG
307 {"gst-debug-help", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
308 (gpointer) parse_goption_arg,
309 N_("Print available debug categories and exit"),
311 {"gst-debug-level", 0, 0, G_OPTION_ARG_CALLBACK,
312 (gpointer) parse_goption_arg,
313 N_("Default debug level from 1 (only error) to 5 (anything) or "
316 {"gst-debug", 0, 0, G_OPTION_ARG_CALLBACK, (gpointer) parse_goption_arg,
317 N_("Comma-separated list of category_name:level pairs to set "
318 "specific levels for the individual categories. Example: "
319 "GST_AUTOPLUG:5,GST_ELEMENT_*:3"),
321 {"gst-debug-no-color", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
322 (gpointer) parse_goption_arg, N_("Disable colored debugging output"),
324 {"gst-debug-disable", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
325 (gpointer) parse_goption_arg, N_("Disable debugging"), NULL},
327 {"gst-plugin-spew", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
328 (gpointer) parse_goption_arg,
329 N_("Enable verbose plugin loading diagnostics"),
331 {"gst-plugin-path", 0, 0, G_OPTION_ARG_CALLBACK,
332 (gpointer) parse_goption_arg,
333 N_("Colon-separated paths containing plugins"), N_("PATHS")},
334 {"gst-plugin-load", 0, 0, G_OPTION_ARG_CALLBACK,
335 (gpointer) parse_goption_arg,
336 N_("Comma-separated list of plugins to preload in addition to the "
337 "list stored in environment variable GST_PLUGIN_PATH"),
339 {"gst-disable-segtrap", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
340 (gpointer) parse_goption_arg,
341 N_("Disable trapping of segmentation faults during plugin loading"),
343 {"gst-disable-registry-fork", 0, G_OPTION_FLAG_NO_ARG,
344 G_OPTION_ARG_CALLBACK,
345 (gpointer) parse_goption_arg,
346 N_("Disable the use of fork() while scanning the registry"),
351 /* The GLib threading system must be initialised before calling any other
352 * GLib function according to the documentation; if the application hasn't
353 * called gst_init() yet or initialised the threading system otherwise, we
354 * better issue a warning here (since chances are high that the application
355 * has already called other GLib functions such as g_option_context_new() */
356 if (!g_thread_supported ()) {
357 g_warning ("The GStreamer function gst_init_get_option_group() was\n"
358 "\tcalled, but the GLib threading system has not been initialised\n"
359 "\tyet, something that must happen before any other GLib function\n"
360 "\tis called. The application needs to be fixed so that it calls\n"
361 "\t if (!g_thread_supported ()) g_thread_init(NULL);\n"
362 "\tas very first thing in its main() function. Please file a bug\n"
363 "\tagainst this application.");
364 g_thread_init (NULL);
367 group = g_option_group_new ("gst", _("GStreamer Options"),
368 _("Show GStreamer Options"), NULL, NULL);
369 g_option_group_set_parse_hooks (group, (GOptionParseFunc) init_pre,
370 (GOptionParseFunc) init_post);
372 g_option_group_add_entries (group, gst_args);
373 g_option_group_set_translation_domain (group, GETTEXT_PACKAGE);
383 * @argc: pointer to application's argc
384 * @argv: pointer to application's argv
385 * @err: pointer to a #GError to which a message will be posted on error
387 * Initializes the GStreamer library, setting up internal path lists,
388 * registering built-in elements, and loading standard plugins.
390 * This function will return %FALSE if GStreamer could not be initialized
391 * for some reason. If you want your program to fail fatally,
392 * use gst_init() instead.
394 * This function should be called before calling any other GLib functions. If
395 * this is not an option, your program must initialise the GLib thread system
396 * using g_thread_init() before any other GLib functions are called.
398 * Returns: %TRUE if GStreamer could be initialized.
401 gst_init_check (int *argc, char **argv[], GError ** err)
403 #ifndef GST_DISABLE_OPTION_PARSING
409 if (!g_thread_supported ())
410 g_thread_init (NULL);
412 if (gst_initialized) {
413 GST_DEBUG ("already initialized gst");
416 #ifndef GST_DISABLE_OPTION_PARSING
417 ctx = g_option_context_new ("- GStreamer initialization");
418 g_option_context_set_ignore_unknown_options (ctx, TRUE);
419 group = gst_init_get_option_group ();
420 g_option_context_add_group (ctx, group);
421 res = g_option_context_parse (ctx, argc, argv, err);
422 g_option_context_free (ctx);
424 init_pre (NULL, NULL, NULL, NULL);
425 init_post (NULL, NULL, NULL, NULL);
429 gst_initialized = res;
432 GST_INFO ("initialized GStreamer successfully");
434 GST_INFO ("failed to initialize GStreamer");
442 * @argc: pointer to application's argc
443 * @argv: pointer to application's argv
445 * Initializes the GStreamer library, setting up internal path lists,
446 * registering built-in elements, and loading standard plugins.
448 * This function should be called before calling any other GLib functions. If
449 * this is not an option, your program must initialise the GLib thread system
450 * using g_thread_init() before any other GLib functions are called.
453 * This function will terminate your program if it was unable to initialize
454 * GStreamer for some reason. If you want your program to fall back,
455 * use gst_init_check() instead.
458 * WARNING: This function does not work in the same way as corresponding
459 * functions in other glib-style libraries, such as gtk_init(). In
460 * particular, unknown command line options cause this function to
461 * abort program execution.
464 gst_init (int *argc, char **argv[])
468 if (!gst_init_check (argc, argv, &err)) {
469 g_print ("Could not initialize GStreamer: %s\n",
470 err ? err->message : "unknown error occurred");
478 #ifndef GST_DISABLE_REGISTRY
480 add_path_func (gpointer data, gpointer user_data)
482 GST_INFO ("Adding plugin path: \"%s\", will scan later", (gchar *) data);
483 plugin_paths = g_list_append (plugin_paths, g_strdup (data));
487 #ifndef GST_DISABLE_OPTION_PARSING
489 prepare_for_load_plugin_func (gpointer data, gpointer user_data)
491 preload_plugins = g_slist_prepend (preload_plugins, g_strdup (data));
496 load_plugin_func (gpointer data, gpointer user_data)
499 const gchar *filename;
502 filename = (const gchar *) data;
504 plugin = gst_plugin_load_file (filename, &err);
507 GST_INFO ("Loaded plugin: \"%s\"", filename);
509 gst_default_registry_add_plugin (plugin);
512 /* Report error to user, and free error */
513 GST_ERROR ("Failed to load plugin: %s", err->message);
516 GST_WARNING ("Failed to load plugin: \"%s\"", filename);
521 #ifndef GST_DISABLE_OPTION_PARSING
523 split_and_iterate (const gchar * stringlist, gchar * separator, GFunc iterator,
528 gchar *lastlist = g_strdup (stringlist);
531 strings = g_strsplit (lastlist, separator, MAX_PATH_SPLIT);
536 iterator (strings[j], user_data);
537 if (++j == MAX_PATH_SPLIT) {
538 lastlist = g_strdup (strings[j]);
543 g_strfreev (strings);
548 /* we have no fail cases yet, but maybe in the future */
550 init_pre (GOptionContext * context, GOptionGroup * group, gpointer data,
553 if (gst_initialized) {
554 GST_DEBUG ("already initialized");
558 /* GStreamer was built against a GLib >= 2.8 and is therefore not doing
559 * the refcount hack. Check that it isn't being run against an older GLib */
560 if (glib_major_version < 2 ||
561 (glib_major_version == 2 && glib_minor_version < 8)) {
562 g_warning ("GStreamer was compiled against GLib %d.%d.%d but is running"
563 " against %d.%d.%d. This will cause reference counting issues",
564 GLIB_MAJOR_VERSION, GLIB_MINOR_VERSION, GLIB_MICRO_VERSION,
565 glib_major_version, glib_minor_version, glib_micro_version);
570 /* we need threading to be enabled right here */
571 g_assert (g_thread_supported ());
575 setlocale (LC_ALL, "");
576 bindtextdomain (GETTEXT_PACKAGE, LOCALEDIR);
577 #endif /* ENABLE_NLS */
579 #ifndef GST_DISABLE_GST_DEBUG
581 const gchar *debug_list;
583 if (g_getenv ("GST_DEBUG_NO_COLOR") != NULL)
584 gst_debug_set_colored (FALSE);
586 debug_list = g_getenv ("GST_DEBUG");
588 parse_debug_list (debug_list);
592 priv_gst_dump_dot_dir = g_getenv ("GST_DEBUG_DUMP_DOT_DIR");
594 /* This is the earliest we can make stuff show up in the logs.
595 * So give some useful info about GStreamer here */
596 GST_INFO ("Initializing GStreamer Core Library version %s", VERSION);
597 GST_INFO ("Using library installed in %s", LIBDIR);
599 /* Print some basic system details if possible (OS/architecture) */
600 #ifdef HAVE_SYS_UTSNAME_H
602 struct utsname sys_details;
604 if (uname (&sys_details) == 0) {
605 GST_INFO ("%s %s %s %s %s", sys_details.sysname,
606 sys_details.nodename, sys_details.release, sys_details.version,
607 sys_details.machine);
616 gst_register_core_elements (GstPlugin * plugin)
618 /* register some standard builtin types */
619 if (!gst_element_register (plugin, "bin", GST_RANK_PRIMARY,
621 !gst_element_register (plugin, "pipeline", GST_RANK_PRIMARY,
624 g_assert_not_reached ();
629 #ifndef GST_DISABLE_REGISTRY
633 REGISTRY_SCAN_AND_UPDATE_FAILURE = 0,
634 REGISTRY_SCAN_AND_UPDATE_SUCCESS_NOT_CHANGED,
635 REGISTRY_SCAN_AND_UPDATE_SUCCESS_UPDATED
636 } GstRegistryScanAndUpdateResult;
639 * scan_and_update_registry:
640 * @default_registry: the #GstRegistry
641 * @registry_file: registry filename
642 * @write_changes: write registry if it has changed?
644 * Scans for registry changes and eventually updates the registry cache.
646 * Return: %REGISTRY_SCAN_AND_UPDATE_FAILURE if the registry could not scanned
647 * or updated, %REGISTRY_SCAN_AND_UPDATE_SUCCESS_NOT_CHANGED if the
648 * registry is clean and %REGISTRY_SCAN_AND_UPDATE_SUCCESS_UPDATED if
649 * it has been updated and the cache needs to be re-read.
651 static GstRegistryScanAndUpdateResult
652 scan_and_update_registry (GstRegistry * default_registry,
653 const gchar * registry_file, gboolean write_changes, GError ** error)
655 const gchar *plugin_path;
656 gboolean changed = FALSE;
659 GST_INFO ("Validating registry cache: %s", registry_file);
660 /* It sounds tempting to just compare the mtime of directories with the mtime
661 * of the registry cache, but it does not work. It would not catch updated
662 * plugins, which might bring more or less features.
665 /* scan paths specified via --gst-plugin-path */
666 GST_DEBUG ("scanning paths added via --gst-plugin-path");
667 for (l = plugin_paths; l != NULL; l = l->next) {
668 GST_INFO ("Scanning plugin path: \"%s\"", (gchar *) l->data);
669 /* FIXME: add changed |= here as well? */
670 gst_registry_scan_path (default_registry, (gchar *) l->data);
672 /* keep plugin_paths around in case a re-scan is forced later on */
674 /* GST_PLUGIN_PATH specifies a list of directories to scan for
675 * additional plugins. These take precedence over the system plugins */
676 plugin_path = g_getenv ("GST_PLUGIN_PATH");
681 GST_DEBUG ("GST_PLUGIN_PATH set to %s", plugin_path);
682 list = g_strsplit (plugin_path, G_SEARCHPATH_SEPARATOR_S, 0);
683 for (i = 0; list[i]; i++) {
684 changed |= gst_registry_scan_path (default_registry, list[i]);
688 GST_DEBUG ("GST_PLUGIN_PATH not set");
691 /* GST_PLUGIN_SYSTEM_PATH specifies a list of plugins that are always
692 * loaded by default. If not set, this defaults to the system-installed
693 * path, and the plugins installed in the user's home directory */
694 plugin_path = g_getenv ("GST_PLUGIN_SYSTEM_PATH");
695 if (plugin_path == NULL) {
698 GST_DEBUG ("GST_PLUGIN_SYSTEM_PATH not set");
700 /* plugins in the user's home directory take precedence over
701 * system-installed ones */
702 home_plugins = g_build_filename (g_get_home_dir (),
703 ".gstreamer-" GST_MAJORMINOR, "plugins", NULL);
704 GST_DEBUG ("scanning home plugins %s", home_plugins);
705 changed |= gst_registry_scan_path (default_registry, home_plugins);
706 g_free (home_plugins);
708 /* add the main (installed) library path */
709 GST_DEBUG ("scanning main plugins %s", PLUGINDIR);
710 changed |= gst_registry_scan_path (default_registry, PLUGINDIR);
715 GST_DEBUG ("GST_PLUGIN_SYSTEM_PATH set to %s", plugin_path);
716 list = g_strsplit (plugin_path, G_SEARCHPATH_SEPARATOR_S, 0);
717 for (i = 0; list[i]; i++) {
718 changed |= gst_registry_scan_path (default_registry, list[i]);
723 /* Remove cached plugins so stale info is cleared. */
724 changed |= _priv_gst_registry_remove_cache_plugins (default_registry);
727 GST_INFO ("Registry cache has not changed");
728 return REGISTRY_SCAN_AND_UPDATE_SUCCESS_NOT_CHANGED;
731 if (!write_changes) {
732 GST_INFO ("Registry cache changed, but writing is disabled. Not writing.");
733 return REGISTRY_SCAN_AND_UPDATE_FAILURE;
736 GST_INFO ("Registry cache changed. Writing new registry cache");
737 #ifdef USE_BINARY_REGISTRY
738 if (!gst_registry_binary_write_cache (default_registry, registry_file)) {
740 if (!gst_registry_xml_write_cache (default_registry, registry_file)) {
742 g_set_error (error, GST_CORE_ERROR, GST_CORE_ERROR_FAILED,
743 _("Error writing registry cache to %s: %s"),
744 registry_file, g_strerror (errno));
745 return REGISTRY_SCAN_AND_UPDATE_FAILURE;
748 GST_INFO ("Registry cache written successfully");
749 return REGISTRY_SCAN_AND_UPDATE_SUCCESS_UPDATED;
753 ensure_current_registry_nonforking (GstRegistry * default_registry,
754 const gchar * registry_file, GError ** error)
756 /* fork() not available */
757 GST_INFO ("reading registry cache: %s", registry_file);
758 #ifdef USE_BINARY_REGISTRY
759 gst_registry_binary_read_cache (default_registry, registry_file);
761 gst_registry_xml_read_cache (default_registry, registry_file);
763 GST_DEBUG ("Updating registry cache in-process");
764 scan_and_update_registry (default_registry, registry_file, TRUE, error);
768 /* when forking is not available this function always does nothing but return
771 ensure_current_registry_forking (GstRegistry * default_registry,
772 const gchar * registry_file, GError ** error)
779 /* We fork here, and let the child read and possibly rebuild the registry.
780 * After that, the parent will re-read the freshly generated registry. */
781 GST_DEBUG ("forking to update registry");
783 if (pipe (pfd) == -1) {
784 g_set_error (error, GST_CORE_ERROR, GST_CORE_ERROR_FAILED,
785 _("Error re-scanning registry %s: %s"),
786 ", could not create pipes. Error", g_strerror (errno));
790 GST_INFO ("reading registry cache: %s", registry_file);
791 #ifdef USE_BINARY_REGISTRY
792 gst_registry_binary_read_cache (default_registry, registry_file);
794 gst_registry_xml_read_cache (default_registry, registry_file);
799 GST_ERROR ("Failed to fork()");
800 g_set_error (error, GST_CORE_ERROR, GST_CORE_ERROR_FAILED,
801 _("Error re-scanning registry %s: %s"),
802 ", failed to fork. Error", g_strerror (errno));
809 /* this is the child. Close the read pipe */
810 (void) close (pfd[0]);
812 GST_DEBUG ("child reading registry cache");
814 scan_and_update_registry (default_registry, registry_file, TRUE, NULL);
816 /* need to use _exit, so that any exit handlers registered don't
817 * bring down the main program */
818 GST_DEBUG ("child exiting: %d", result_code);
820 /* make valgrind happy (yes, you can call it insane) */
821 g_free ((char *) registry_file);
823 /* write a result byte to the pipe */
825 ret = write (pfd[1], &result_code, sizeof (result_code));
826 } while (ret == -1 && errno == EINTR);
827 /* if ret == -1 now, we could not write to pipe, probably
828 * means parent has exited before us */
829 (void) close (pfd[1]);
835 /* parent. Close write pipe */
836 (void) close (pfd[1]);
838 /* Wait for result from the pipe */
839 GST_DEBUG ("Waiting for data from child");
841 ret = read (pfd[0], &result_code, sizeof (result_code));
842 } while (ret == -1 && errno == EINTR);
845 g_set_error (error, GST_CORE_ERROR, GST_CORE_ERROR_FAILED,
846 _("Error re-scanning registry %s: %s"),
847 ", read returned error", g_strerror (errno));
851 (void) close (pfd[0]);
853 /* Wait to ensure the child is reaped, but ignore the result */
854 GST_DEBUG ("parent waiting on child");
855 waitpid (pid, NULL, 0);
856 GST_DEBUG ("parent done waiting on child");
859 GST_ERROR ("child did not exit normally, terminated by signal");
860 g_set_error (error, GST_CORE_ERROR, GST_CORE_ERROR_FAILED,
861 _("Error re-scanning registry %s"), ", child terminated by signal");
865 if (result_code == REGISTRY_SCAN_AND_UPDATE_SUCCESS_UPDATED) {
866 GST_DEBUG ("Child succeeded. Parent reading registry cache");
867 _priv_gst_registry_remove_cache_plugins (default_registry);
868 #ifdef USE_BINARY_REGISTRY
869 gst_registry_binary_read_cache (default_registry, registry_file);
871 gst_registry_xml_read_cache (default_registry, registry_file);
873 } else if (result_code == REGISTRY_SCAN_AND_UPDATE_FAILURE) {
874 GST_DEBUG ("Child failed. Parent re-scanning registry, ignoring errors.");
875 scan_and_update_registry (default_registry, registry_file, FALSE, NULL);
878 #endif /* HAVE_FORK */
883 ensure_current_registry (GError ** error)
886 GstRegistry *default_registry;
890 default_registry = gst_registry_get_default ();
891 registry_file = g_strdup (g_getenv ("GST_REGISTRY"));
892 if (registry_file == NULL) {
893 #ifdef USE_BINARY_REGISTRY
894 registry_file = g_build_filename (g_get_home_dir (),
895 ".gstreamer-" GST_MAJORMINOR, "registry." HOST_CPU ".bin", NULL);
897 registry_file = g_build_filename (g_get_home_dir (),
898 ".gstreamer-" GST_MAJORMINOR, "registry." HOST_CPU ".xml", NULL);
902 /* first see if forking is enabled */
903 do_fork = _gst_enable_registry_fork;
905 const gchar *fork_env;
907 /* forking enabled, see if it is disabled with an env var */
908 if ((fork_env = g_getenv ("GST_REGISTRY_FORK"))) {
909 /* fork enabled for any value different from "no" */
910 do_fork = strcmp (fork_env, "no") != 0;
914 /* now check registry with or without forking */
916 GST_DEBUG ("forking for registry rebuild");
917 ret = ensure_current_registry_forking (default_registry, registry_file,
920 GST_DEBUG ("requested not to fork for registry rebuild");
921 ret = ensure_current_registry_nonforking (default_registry, registry_file,
925 g_free (registry_file);
929 #endif /* GST_DISABLE_REGISTRY */
933 * - initalization of threads if we use them
936 * - initializes gst_format
937 * - registers a bunch of types for gst_objects
939 * - we don't have cases yet where this fails, but in the future
940 * we might and then it's nice to be able to return that
943 init_post (GOptionContext * context, GOptionGroup * group, gpointer data,
948 #ifndef GST_DISABLE_TRACE
950 #endif /* GST_DISABLE_TRACE */
952 if (gst_initialized) {
953 GST_DEBUG ("already initialized");
957 llf = G_LOG_LEVEL_CRITICAL | G_LOG_LEVEL_ERROR | G_LOG_FLAG_FATAL;
958 g_log_set_handler (g_log_domain_gstreamer, llf, debug_log_handler, NULL);
960 _priv_gst_quarks_initialize ();
961 _gst_format_initialize ();
962 _gst_query_initialize ();
963 g_type_class_ref (gst_object_get_type ());
964 g_type_class_ref (gst_pad_get_type ());
965 g_type_class_ref (gst_element_factory_get_type ());
966 g_type_class_ref (gst_element_get_type ());
967 g_type_class_ref (gst_type_find_factory_get_type ());
968 g_type_class_ref (gst_bin_get_type ());
970 #ifndef GST_DISABLE_INDEX
971 g_type_class_ref (gst_index_factory_get_type ());
972 #endif /* GST_DISABLE_INDEX */
973 #ifndef GST_DISABLE_URI
974 gst_uri_handler_get_type ();
975 #endif /* GST_DISABLE_URI */
977 #ifndef GST_DISABLE_ENUMTYPES
978 g_type_class_ref (gst_object_flags_get_type ());
979 g_type_class_ref (gst_bin_flags_get_type ());
980 g_type_class_ref (gst_buffer_flag_get_type ());
981 g_type_class_ref (gst_buffer_copy_flags_get_type ());
982 g_type_class_ref (gst_bus_flags_get_type ());
983 g_type_class_ref (gst_bus_sync_reply_get_type ());
984 g_type_class_ref (gst_caps_flags_get_type ());
985 g_type_class_ref (gst_clock_return_get_type ());
986 g_type_class_ref (gst_clock_entry_type_get_type ());
987 g_type_class_ref (gst_clock_flags_get_type ());
988 g_type_class_ref (gst_debug_graph_details_get_type ());
989 g_type_class_ref (gst_state_get_type ());
990 g_type_class_ref (gst_state_change_return_get_type ());
991 g_type_class_ref (gst_state_change_get_type ());
992 g_type_class_ref (gst_element_flags_get_type ());
993 g_type_class_ref (gst_core_error_get_type ());
994 g_type_class_ref (gst_library_error_get_type ());
995 g_type_class_ref (gst_resource_error_get_type ());
996 g_type_class_ref (gst_stream_error_get_type ());
997 g_type_class_ref (gst_event_type_flags_get_type ());
998 g_type_class_ref (gst_event_type_get_type ());
999 g_type_class_ref (gst_seek_type_get_type ());
1000 g_type_class_ref (gst_seek_flags_get_type ());
1001 g_type_class_ref (gst_format_get_type ());
1002 g_type_class_ref (gst_index_certainty_get_type ());
1003 g_type_class_ref (gst_index_entry_type_get_type ());
1004 g_type_class_ref (gst_index_lookup_method_get_type ());
1005 g_type_class_ref (gst_assoc_flags_get_type ());
1006 g_type_class_ref (gst_index_resolver_method_get_type ());
1007 g_type_class_ref (gst_index_flags_get_type ());
1008 g_type_class_ref (gst_debug_level_get_type ());
1009 g_type_class_ref (gst_debug_color_flags_get_type ());
1010 g_type_class_ref (gst_iterator_result_get_type ());
1011 g_type_class_ref (gst_iterator_item_get_type ());
1012 g_type_class_ref (gst_message_type_get_type ());
1013 g_type_class_ref (gst_mini_object_flags_get_type ());
1014 g_type_class_ref (gst_pad_link_return_get_type ());
1015 g_type_class_ref (gst_flow_return_get_type ());
1016 g_type_class_ref (gst_activate_mode_get_type ());
1017 g_type_class_ref (gst_pad_direction_get_type ());
1018 g_type_class_ref (gst_pad_flags_get_type ());
1019 g_type_class_ref (gst_pad_presence_get_type ());
1020 g_type_class_ref (gst_pad_template_flags_get_type ());
1021 g_type_class_ref (gst_pipeline_flags_get_type ());
1022 g_type_class_ref (gst_plugin_error_get_type ());
1023 g_type_class_ref (gst_plugin_flags_get_type ());
1024 g_type_class_ref (gst_rank_get_type ());
1025 g_type_class_ref (gst_query_type_get_type ());
1026 g_type_class_ref (gst_buffering_mode_get_type ());
1027 g_type_class_ref (gst_tag_merge_mode_get_type ());
1028 g_type_class_ref (gst_tag_flag_get_type ());
1029 g_type_class_ref (gst_task_state_get_type ());
1030 g_type_class_ref (gst_alloc_trace_flags_get_type ());
1031 g_type_class_ref (gst_type_find_probability_get_type ());
1032 g_type_class_ref (gst_uri_type_get_type ());
1033 g_type_class_ref (gst_parse_error_get_type ());
1036 gst_structure_get_type ();
1037 _gst_value_initialize ();
1038 g_type_class_ref (gst_param_spec_fraction_get_type ());
1039 gst_caps_get_type ();
1040 _gst_event_initialize ();
1041 _gst_buffer_initialize ();
1042 _gst_message_initialize ();
1043 _gst_tag_initialize ();
1045 _gst_plugin_initialize ();
1047 /* register core plugins */
1048 gst_plugin_register_static (GST_VERSION_MAJOR, GST_VERSION_MINOR,
1049 "staticelements", "core elements linked into the GStreamer library",
1050 gst_register_core_elements, VERSION, GST_LICENSE, PACKAGE,
1051 GST_PACKAGE_NAME, GST_PACKAGE_ORIGIN);
1054 * Any errors happening below this point are non-fatal, we therefore mark
1055 * gstreamer as being initialized, since it is the case from a plugin point of
1058 * If anything fails, it will be put back to FALSE in gst_init_check().
1059 * This allows some special plugins that would call gst_init() to not cause a
1060 * looping effect (i.e. initializing GStreamer twice).
1062 gst_initialized = TRUE;
1064 #ifndef GST_DISABLE_REGISTRY
1065 if (!ensure_current_registry (error))
1067 #endif /* GST_DISABLE_REGISTRY */
1069 /* if we need to preload plugins, do so now */
1070 g_slist_foreach (preload_plugins, load_plugin_func, NULL);
1071 /* keep preload_plugins around in case a re-scan is forced later on */
1073 #ifndef GST_DISABLE_TRACE
1075 if (_gst_trace_on) {
1076 gst_trace = gst_trace_new ("gst.trace", 1024);
1077 gst_trace_set_default (gst_trace);
1079 #endif /* GST_DISABLE_TRACE */
1084 #ifndef GST_DISABLE_GST_DEBUG
1086 select_all (GstPlugin * plugin, gpointer user_data)
1092 sort_by_category_name (gconstpointer a, gconstpointer b)
1094 return strcmp (gst_debug_category_get_name ((GstDebugCategory *) a),
1095 gst_debug_category_get_name ((GstDebugCategory *) b));
1099 gst_debug_help (void)
1101 GSList *list, *walk;
1104 /* Need to ensure the registry is loaded to get debug categories */
1105 if (!init_post (NULL, NULL, NULL, NULL))
1108 list2 = gst_registry_plugin_filter (gst_registry_get_default (),
1109 select_all, FALSE, NULL);
1111 /* FIXME this is gross. why don't debug have categories PluginFeatures? */
1112 for (g = list2; g; g = g_list_next (g)) {
1113 GstPlugin *plugin = GST_PLUGIN_CAST (g->data);
1115 gst_plugin_load (plugin);
1117 g_list_free (list2);
1119 list = gst_debug_get_all_categories ();
1120 walk = list = g_slist_sort (list, sort_by_category_name);
1123 g_print ("name level description\n");
1124 g_print ("---------------------+--------+--------------------------------\n");
1127 GstDebugCategory *cat = (GstDebugCategory *) walk->data;
1129 if (gst_debug_is_colored ()) {
1130 gchar *color = gst_debug_construct_term_color (cat->color);
1132 g_print ("%s%-20s\033[00m %1d %s %s%s\033[00m\n",
1134 gst_debug_category_get_name (cat),
1135 gst_debug_category_get_threshold (cat),
1136 gst_debug_level_get_name (gst_debug_category_get_threshold (cat)),
1137 color, gst_debug_category_get_description (cat));
1140 g_print ("%-20s %1d %s %s\n", gst_debug_category_get_name (cat),
1141 gst_debug_category_get_threshold (cat),
1142 gst_debug_level_get_name (gst_debug_category_get_threshold (cat)),
1143 gst_debug_category_get_description (cat));
1145 walk = g_slist_next (walk);
1147 g_slist_free (list);
1152 #ifndef GST_DISABLE_OPTION_PARSING
1154 parse_one_option (gint opt, const gchar * arg, GError ** err)
1158 g_print ("GStreamer Core Library version %s\n", PACKAGE_VERSION);
1160 case ARG_FATAL_WARNINGS:{
1161 GLogLevelFlags fatal_mask;
1163 fatal_mask = g_log_set_always_fatal (G_LOG_FATAL_MASK);
1164 fatal_mask |= G_LOG_LEVEL_WARNING | G_LOG_LEVEL_CRITICAL;
1165 g_log_set_always_fatal (fatal_mask);
1168 #ifndef GST_DISABLE_GST_DEBUG
1169 case ARG_DEBUG_LEVEL:{
1172 tmp = strtol (arg, NULL, 0);
1173 if (tmp >= 0 && tmp < GST_LEVEL_COUNT) {
1174 gst_debug_set_default_threshold (tmp);
1179 parse_debug_list (arg);
1181 case ARG_DEBUG_NO_COLOR:
1182 gst_debug_set_colored (FALSE);
1184 case ARG_DEBUG_DISABLE:
1185 gst_debug_set_active (FALSE);
1187 case ARG_DEBUG_HELP:
1191 case ARG_PLUGIN_SPEW:
1193 case ARG_PLUGIN_PATH:
1194 #ifndef GST_DISABLE_REGISTRY
1195 split_and_iterate (arg, G_SEARCHPATH_SEPARATOR_S, add_path_func, NULL);
1196 #endif /* GST_DISABLE_REGISTRY */
1198 case ARG_PLUGIN_LOAD:
1199 split_and_iterate (arg, ",", prepare_for_load_plugin_func, NULL);
1201 case ARG_SEGTRAP_DISABLE:
1202 _gst_disable_segtrap = TRUE;
1204 case ARG_REGISTRY_FORK_DISABLE:
1205 _gst_enable_registry_fork = FALSE;
1208 g_set_error (err, G_OPTION_ERROR, G_OPTION_ERROR_UNKNOWN_OPTION,
1209 _("Unknown option"));
1217 parse_goption_arg (const gchar * opt,
1218 const gchar * arg, gpointer data, GError ** err)
1226 "--gst-version", ARG_VERSION}, {
1227 "--gst-fatal-warnings", ARG_FATAL_WARNINGS},
1228 #ifndef GST_DISABLE_GST_DEBUG
1230 "--gst-debug-level", ARG_DEBUG_LEVEL}, {
1231 "--gst-debug", ARG_DEBUG}, {
1232 "--gst-debug-disable", ARG_DEBUG_DISABLE}, {
1233 "--gst-debug-no-color", ARG_DEBUG_NO_COLOR}, {
1234 "--gst-debug-help", ARG_DEBUG_HELP},
1237 "--gst-plugin-spew", ARG_PLUGIN_SPEW}, {
1238 "--gst-plugin-path", ARG_PLUGIN_PATH}, {
1239 "--gst-plugin-load", ARG_PLUGIN_LOAD}, {
1240 "--gst-disable-segtrap", ARG_SEGTRAP_DISABLE}, {
1241 "--gst-disable-registry-fork", ARG_REGISTRY_FORK_DISABLE}, {
1246 for (n = 0; options[n].opt; n++) {
1247 if (!strcmp (opt, options[n].opt)) {
1248 val = options[n].val;
1253 return parse_one_option (val, arg, err);
1257 extern GstRegistry *_gst_registry_default;
1262 * Clean up any resources created by GStreamer in gst_init().
1264 * It is normally not needed to call this function in a normal application
1265 * as the resources will automatically be freed when the program terminates.
1266 * This function is therefore mostly used by testsuites and other memory
1269 * After this call GStreamer (including this method) should not be used anymore.
1276 GST_INFO ("deinitializing GStreamer");
1278 if (gst_deinitialized) {
1279 GST_DEBUG ("already deinitialized");
1283 g_slist_foreach (preload_plugins, (GFunc) g_free, NULL);
1284 g_slist_free (preload_plugins);
1285 preload_plugins = NULL;
1287 #ifndef GST_DISABLE_REGISTRY
1288 g_list_foreach (plugin_paths, (GFunc) g_free, NULL);
1289 g_list_free (plugin_paths);
1290 plugin_paths = NULL;
1293 clock = gst_system_clock_obtain ();
1294 gst_object_unref (clock);
1295 gst_object_unref (clock);
1297 _priv_gst_registry_cleanup ();
1299 g_type_class_unref (g_type_class_peek (gst_object_get_type ()));
1300 g_type_class_unref (g_type_class_peek (gst_pad_get_type ()));
1301 g_type_class_unref (g_type_class_peek (gst_element_factory_get_type ()));
1302 g_type_class_unref (g_type_class_peek (gst_element_get_type ()));
1303 g_type_class_unref (g_type_class_peek (gst_type_find_factory_get_type ()));
1304 g_type_class_unref (g_type_class_peek (gst_bin_get_type ()));
1305 #ifndef GST_DISABLE_INDEX
1306 g_type_class_unref (g_type_class_peek (gst_index_factory_get_type ()));
1307 #endif /* GST_DISABLE_INDEX */
1308 g_type_class_unref (g_type_class_peek (gst_param_spec_fraction_get_type ()));
1310 gst_deinitialized = TRUE;
1311 GST_INFO ("deinitialized GStreamer");
1316 * @major: pointer to a guint to store the major version number
1317 * @minor: pointer to a guint to store the minor version number
1318 * @micro: pointer to a guint to store the micro version number
1319 * @nano: pointer to a guint to store the nano version number
1321 * Gets the version number of the GStreamer library.
1324 gst_version (guint * major, guint * minor, guint * micro, guint * nano)
1326 g_return_if_fail (major);
1327 g_return_if_fail (minor);
1328 g_return_if_fail (micro);
1329 g_return_if_fail (nano);
1331 *major = GST_VERSION_MAJOR;
1332 *minor = GST_VERSION_MINOR;
1333 *micro = GST_VERSION_MICRO;
1334 *nano = GST_VERSION_NANO;
1338 * gst_version_string:
1340 * This function returns a string that is useful for describing this version
1341 * of GStreamer to the outside world: user agent strings, logging, ...
1343 * Returns: a newly allocated string describing this version of GStreamer.
1347 gst_version_string ()
1349 guint major, minor, micro, nano;
1351 gst_version (&major, &minor, µ, &nano);
1353 return g_strdup_printf ("GStreamer %d.%d.%d", major, minor, micro);
1355 return g_strdup_printf ("GStreamer %d.%d.%d (CVS)", major, minor, micro);
1357 return g_strdup_printf ("GStreamer %d.%d.%d (prerelease)", major, minor,
1362 * gst_segtrap_is_enabled:
1364 * Some functions in the GStreamer core might install a custom SIGSEGV handler
1365 * to better catch and report errors to the application. Currently this feature
1366 * is enabled by default when loading plugins.
1368 * Applications might want to disable this behaviour with the
1369 * gst_segtrap_set_enabled() function. This is typically done if the application
1370 * wants to install its own handler without GStreamer interfering.
1372 * Returns: %TRUE if GStreamer is allowed to install a custom SIGSEGV handler.
1377 gst_segtrap_is_enabled (void)
1379 /* yeps, it's enabled when it's not disabled */
1380 return !_gst_disable_segtrap;
1384 * gst_segtrap_set_enabled:
1385 * @enabled: whether a custom SIGSEGV handler should be installed.
1387 * Applications might want to disable/enable the SIGSEGV handling of
1388 * the GStreamer core. See gst_segtrap_is_enabled() for more information.
1393 gst_segtrap_set_enabled (gboolean enabled)
1395 _gst_disable_segtrap = !enabled;
1399 * gst_registry_fork_is_enabled:
1401 * By default GStreamer will perform a fork() when scanning and rebuilding the
1404 * Applications might want to disable this behaviour with the
1405 * gst_registry_fork_set_enabled() function.
1407 * Returns: %TRUE if GStreamer will use fork() when rebuilding the registry. On
1408 * platforms without fork(), this function will always return %FALSE.
1413 gst_registry_fork_is_enabled (void)
1415 return _gst_enable_registry_fork;
1419 * gst_registry_fork_set_enabled:
1420 * @enabled: whether rebuilding the registry may fork
1422 * Applications might want to disable/enable the usage of fork() when rebuilding
1423 * the registry. See gst_registry_fork_is_enabled() for more information.
1425 * On platforms without fork(), this function will have no effect on the return
1426 * value of gst_registry_fork_is_enabled().
1431 gst_registry_fork_set_enabled (gboolean enabled)
1434 _gst_enable_registry_fork = enabled;
1435 #endif /* HAVE_FORK */
1440 * gst_update_registry:
1442 * Forces GStreamer to re-scan its plugin paths and update the default
1445 * Applications will almost never need to call this function, it is only
1446 * useful if the application knows new plugins have been installed (or old
1447 * ones removed) since the start of the application (or, to be precise, the
1448 * first call to gst_init()) and the application wants to make use of any
1449 * newly-installed plugins without restarting the application.
1451 * Applications should assume that the registry update is neither atomic nor
1452 * thread-safe and should therefore not have any dynamic pipelines running
1453 * (including the playbin and decodebin elements) and should also not create
1454 * any elements or access the GStreamer registry while the update is in
1457 * Note that this function may block for a significant amount of time.
1459 * Returns: %TRUE if the registry has been updated successfully (does not
1460 * imply that there were changes), otherwise %FALSE.
1465 gst_update_registry (void)
1467 gboolean res = FALSE;
1469 #ifndef GST_DISABLE_REGISTRY
1472 res = ensure_current_registry (&err);
1474 GST_WARNING ("registry update failed: %s", err->message);
1477 GST_LOG ("registry update succeeded");
1480 if (preload_plugins) {
1481 g_slist_foreach (preload_plugins, load_plugin_func, NULL);
1484 GST_WARNING ("registry update failed: %s", "registry disabled");
1485 #endif /* GST_DISABLE_REGISTRY */