gst/gst.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gst.c: Initialization and non-pipeline operations
   6  *
   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.
  11  *
  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.
  16  *
  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.
  21  */
  22
  23 /**
  24  * SECTION:gst
  25  * @short_description: Media library supporting arbitrary formats and filter
  26  *                     graphs.
  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.
  29  *
  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).
  37  *
  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.
  42  *
  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.
  47  *
  48  * <example>
  49  * <title>Initializing the gstreamer library</title>
  50  * <programlisting language="c">
  51  * int
  52  * main (int argc, char *argv[])
  53  * {
  54  *   // initialize the GStreamer library
  55  *   gst_init (&amp;argc, &amp;argv);
  56  *   ...
  57  * }
  58  * </programlisting>
  59  * </example>
  60  *
  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.
  63  *
  64  * You can also use GOption to initialize your own parameters as shown in
  65  * the next code fragment:
  66  * <example>
  67  * <title>Initializing own parameters when initializing gstreamer</title>
  68  * <programlisting>
  69  * static gboolean stats = FALSE;
  70  * ...
  71  * int
  72  * main (int argc, char *argv[])
  73  * {
  74  *  GOptionEntry options[] = {
  75  *   {"tags", 't', 0, G_OPTION_ARG_NONE, &amp;tags,
  76  *       N_("Output tags (also known as metadata)"), NULL},
  77  *   {NULL}
  78  *  };
  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, &amp;argc, &amp;argv, &amp;err)) {
  86  *    g_print ("Error initializing: &percnt;s\n", GST_STR_NULL (err->message));
  87  *    exit (1);
  88  *  }
  89  *  g_option_context_free (ctx);
  90  * ...
  91  * }
  92  * </programlisting>
  93  * </example>
  94  *
  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.
  98  *
  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.
 102  *
 103  * Last reviewed on 2006-08-11 (0.10.10)
 104  */
 105
 106 #include "gst_private.h"
 107 #include <stdlib.h>
 108 #include <stdio.h>
 109 #include <sys/types.h>
 110 #ifdef HAVE_FORK
 111 #include <sys/wait.h>
 112 #endif /* HAVE_FORK */
 113 #ifdef HAVE_SYS_UTSNAME_H
 114 #include <sys/utsname.h>
 115 #endif
 116 #ifdef HAVE_UNISTD_H
 117 #include <unistd.h>
 118 #endif
 119
 120 #include "gst-i18n-lib.h"
 121 #include <locale.h>             /* for LC_ALL */
 122
 123 #include "gst.h"
 124
 125 #define GST_CAT_DEFAULT GST_CAT_GST_INIT
 126
 127 #define MAX_PATH_SPLIT  16
 128 #define GST_PLUGIN_SEPARATOR ","
 129
 130 static gboolean gst_initialized = FALSE;
 131
 132 #ifndef GST_DISABLE_REGISTRY
 133 static GList *plugin_paths = NULL;      /* for delayed processing in post_init */
 134 #endif
 135
 136 extern gint _gst_trace_on;
 137
 138 /* defaults */
 139 #ifdef HAVE_FORK
 140 #define DEFAULT_FORK TRUE
 141 #else
 142 #define DEFAULT_FORK FALSE
 143 #endif /* HAVE_FORK */
 144
 145 /* set to TRUE when segfaults need to be left as is, FIXME, this variable is
 146  * global. */
 147 gboolean _gst_disable_segtrap = FALSE;
 148
 149 /* control the behaviour of registry rebuild */
 150 static gboolean _gst_enable_registry_fork = DEFAULT_FORK;
 151
 152 static void load_plugin_func (gpointer data, gpointer user_data);
 153 static gboolean init_pre (GOptionContext * context, GOptionGroup * group,
 154     gpointer data, GError ** error);
 155 static gboolean init_post (GOptionContext * context, GOptionGroup * group,
 156     gpointer data, GError ** error);
 157 #ifndef GST_DISABLE_OPTION_PARSING
 158 static gboolean parse_goption_arg (const gchar * s_opt,
 159     const gchar * arg, gpointer data, GError ** err);
 160 #endif
 161
 162 static GSList *preload_plugins = NULL;
 163
 164 const gchar g_log_domain_gstreamer[] = "GStreamer";
 165
 166 static void
 167 debug_log_handler (const gchar * log_domain,
 168     GLogLevelFlags log_level, const gchar * message, gpointer user_data)
 169 {
 170   g_log_default_handler (log_domain, log_level, message, user_data);
 171   /* FIXME: do we still need this ? fatal errors these days are all
 172    * other than core errors */
 173   /* g_on_error_query (NULL); */
 174 }
 175
 176 enum
 177 {
 178   ARG_VERSION = 1,
 179   ARG_FATAL_WARNINGS,
 180 #ifndef GST_DISABLE_GST_DEBUG
 181   ARG_DEBUG_LEVEL,
 182   ARG_DEBUG,
 183   ARG_DEBUG_DISABLE,
 184   ARG_DEBUG_NO_COLOR,
 185   ARG_DEBUG_HELP,
 186 #endif
 187   ARG_PLUGIN_SPEW,
 188   ARG_PLUGIN_PATH,
 189   ARG_PLUGIN_LOAD,
 190   ARG_SEGTRAP_DISABLE,
 191   ARG_REGISTRY_FORK_DISABLE
 192 };
 193
 194 /* debug-spec ::= category-spec [, category-spec]*
 195  * category-spec ::= category:val | val
 196  * category ::= [^:]+
 197  * val ::= [0-5]
 198  */
 199
 200 #ifndef NUL
 201 #define NUL '\0'
 202 #endif
 203
 204 #ifndef GST_DISABLE_GST_DEBUG
 205 static gboolean
 206 parse_debug_category (gchar * str, const gchar ** category)
 207 {
 208   if (!str)
 209     return FALSE;
 210
 211   /* works in place */
 212   g_strstrip (str);
 213
 214   if (str[0] != NUL) {
 215     *category = str;
 216     return TRUE;
 217   }
 218
 219   return FALSE;
 220 }
 221
 222 static gboolean
 223 parse_debug_level (gchar * str, gint * level)
 224 {
 225   if (!str)
 226     return FALSE;
 227
 228   /* works in place */
 229   g_strstrip (str);
 230
 231   if (str[0] != NUL && str[1] == NUL
 232       && str[0] >= '0' && str[0] < '0' + GST_LEVEL_COUNT) {
 233     *level = str[0] - '0';
 234     return TRUE;
 235   }
 236
 237   return FALSE;
 238 }
 239
 240 static void
 241 parse_debug_list (const gchar * list)
 242 {
 243   gchar **split;
 244   gchar **walk;
 245
 246   g_return_if_fail (list != NULL);
 247
 248   split = g_strsplit (list, ",", 0);
 249
 250   for (walk = split; *walk; walk++) {
 251     if (strchr (*walk, ':')) {
 252       gchar **values = g_strsplit (*walk, ":", 2);
 253
 254       if (values[0] && values[1]) {
 255         gint level;
 256         const gchar *category;
 257
 258         if (parse_debug_category (values[0], &category)
 259             && parse_debug_level (values[1], &level))
 260           gst_debug_set_threshold_for_name (category, level);
 261       }
 262
 263       g_strfreev (values);
 264     } else {
 265       gint level;
 266
 267       if (parse_debug_level (*walk, &level))
 268         gst_debug_set_default_threshold (level);
 269     }
 270   }
 271
 272   g_strfreev (split);
 273 }
 274 #endif
 275
 276 /**
 277  * gst_init_get_option_group:
 278  *
 279  * Returns a #GOptionGroup with GStreamer's argument specifications. The
 280  * group is set up to use standard GOption callbacks, so when using this
 281  * group in combination with GOption parsing methods, all argument parsing
 282  * and initialization is automated.
 283  *
 284  * This function is useful if you want to integrate GStreamer with other
 285  * libraries that use GOption (see g_option_context_add_group() ).
 286  *
 287  * If you use this function, you should make sure you initialise the GLib
 288  * threading system as one of the very first things in your program
 289  * (see the example at the beginning of this section).
 290  *
 291  * Returns: a pointer to GStreamer's option group.
 292  */
 293
 294 GOptionGroup *
 295 gst_init_get_option_group (void)
 296 {
 297 #ifndef GST_DISABLE_OPTION_PARSING
 298   GOptionGroup *group;
 299   const static GOptionEntry gst_args[] = {
 300     {"gst-version", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
 301         (gpointer) parse_goption_arg, N_("Print the GStreamer version"), NULL},
 302     {"gst-fatal-warnings", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
 303         (gpointer) parse_goption_arg, N_("Make all warnings fatal"), NULL},
 304 #ifndef GST_DISABLE_GST_DEBUG
 305     {"gst-debug-help", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
 306           (gpointer) parse_goption_arg,
 307           N_("Print available debug categories and exit"),
 308         NULL},
 309     {"gst-debug-level", 0, 0, G_OPTION_ARG_CALLBACK,
 310           (gpointer) parse_goption_arg,
 311           N_("Default debug level from 1 (only error) to 5 (anything) or "
 312               "0 for no output"),
 313         N_("LEVEL")},
 314     {"gst-debug", 0, 0, G_OPTION_ARG_CALLBACK, (gpointer) parse_goption_arg,
 315           N_("Comma-separated list of category_name:level pairs to set "
 316               "specific levels for the individual categories. Example: "
 317               "GST_AUTOPLUG:5,GST_ELEMENT_*:3"),
 318         N_("LIST")},
 319     {"gst-debug-no-color", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
 320           (gpointer) parse_goption_arg, N_("Disable colored debugging output"),
 321         NULL},
 322     {"gst-debug-disable", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
 323         (gpointer) parse_goption_arg, N_("Disable debugging"), NULL},
 324 #endif
 325     {"gst-plugin-spew", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
 326           (gpointer) parse_goption_arg,
 327           N_("Enable verbose plugin loading diagnostics"),
 328         NULL},
 329     {"gst-plugin-path", 0, 0, G_OPTION_ARG_CALLBACK,
 330           (gpointer) parse_goption_arg,
 331         N_("Colon-separated paths containing plugins"), N_("PATHS")},
 332     {"gst-plugin-load", 0, 0, G_OPTION_ARG_CALLBACK,
 333           (gpointer) parse_goption_arg,
 334           N_("Comma-separated list of plugins to preload in addition to the "
 335               "list stored in environment variable GST_PLUGIN_PATH"),
 336         N_("PLUGINS")},
 337     {"gst-disable-segtrap", 0, G_OPTION_FLAG_NO_ARG, G_OPTION_ARG_CALLBACK,
 338           (gpointer) parse_goption_arg,
 339           N_("Disable trapping of segmentation faults during plugin loading"),
 340         NULL},
 341     {"gst-disable-registry-fork", 0, G_OPTION_FLAG_NO_ARG,
 342           G_OPTION_ARG_CALLBACK,
 343           (gpointer) parse_goption_arg,
 344           N_("Disable the use of fork() while scanning the registry"),
 345         NULL},
 346     {NULL}
 347   };
 348
 349   /* The GLib threading system must be initialised before calling any other
 350    * GLib function according to the documentation; if the application hasn't
 351    * called gst_init() yet or initialised the threading system otherwise, we
 352    * better issue a warning here (since chances are high that the application
 353    * has already called other GLib functions such as g_option_context_new() */
 354   if (!g_thread_supported ()) {
 355     g_warning ("The GStreamer function gst_init_get_option_group() was\n"
 356         "\tcalled, but the GLib threading system has not been initialised\n"
 357         "\tyet, something that must happen before any other GLib function\n"
 358         "\tis called. The application needs to be fixed so that it calls\n"
 359         "\t   if (!g_thread_supported ()) g_thread_init(NULL);\n"
 360         "\tas very first thing in its main() function. Please file a bug\n"
 361         "\tagainst this application.");
 362     g_thread_init (NULL);
 363   }
 364
 365   group = g_option_group_new ("gst", _("GStreamer Options"),
 366       _("Show GStreamer Options"), NULL, NULL);
 367   g_option_group_set_parse_hooks (group, (GOptionParseFunc) init_pre,
 368       (GOptionParseFunc) init_post);
 369
 370   g_option_group_add_entries (group, gst_args);
 371   g_option_group_set_translation_domain (group, GETTEXT_PACKAGE);
 372
 373   return group;
 374 #else
 375   return NULL;
 376 #endif
 377 }
 378
 379 /**
 380  * gst_init_check:
 381  * @argc: pointer to application's argc
 382  * @argv: pointer to application's argv
 383  * @err: pointer to a #GError to which a message will be posted on error
 384  *
 385  * Initializes the GStreamer library, setting up internal path lists,
 386  * registering built-in elements, and loading standard plugins.
 387  *
 388  * This function will return %FALSE if GStreamer could not be initialized
 389  * for some reason.  If you want your program to fail fatally,
 390  * use gst_init() instead.
 391  *
 392  * This function should be called before calling any other GLib functions. If
 393  * this is not an option, your program must initialise the GLib thread system
 394  * using g_thread_init() before any other GLib functions are called.
 395  *
 396  * Returns: %TRUE if GStreamer could be initialized.
 397  */
 398 gboolean
 399 gst_init_check (int *argc, char **argv[], GError ** err)
 400 {
 401 #ifndef GST_DISABLE_OPTION_PARSING
 402   GOptionGroup *group;
 403   GOptionContext *ctx;
 404 #endif
 405   gboolean res;
 406
 407   if (!g_thread_supported ())
 408     g_thread_init (NULL);
 409
 410   GST_INFO ("initializing GStreamer");
 411
 412   if (gst_initialized) {
 413     GST_DEBUG ("already initialized gst");
 414     return TRUE;
 415   }
 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);
 423 #else
 424   init_pre (NULL, NULL, NULL, NULL);
 425   init_post (NULL, NULL, NULL, NULL);
 426   res = TRUE;
 427 #endif
 428
 429   gst_initialized = res;
 430
 431   if (res) {
 432     GST_INFO ("initialized GStreamer successfully");
 433   } else {
 434     GST_INFO ("failed to initialize GStreamer");
 435   }
 436
 437   return res;
 438 }
 439
 440 /**
 441  * gst_init:
 442  * @argc: pointer to application's argc
 443  * @argv: pointer to application's argv
 444  *
 445  * Initializes the GStreamer library, setting up internal path lists,
 446  * registering built-in elements, and loading standard plugins.
 447  *
 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.
 451  *
 452  * <note><para>
 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.
 456  * </para></note>
 457  *
 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.
 462  */
 463 void
 464 gst_init (int *argc, char **argv[])
 465 {
 466   GError *err = NULL;
 467
 468   if (!gst_init_check (argc, argv, &err)) {
 469     g_print ("Could not initialize GStreamer: %s\n",
 470         err ? err->message : "unknown error occurred");
 471     if (err) {
 472       g_error_free (err);
 473     }
 474     exit (1);
 475   }
 476 }
 477
 478 #ifndef GST_DISABLE_REGISTRY
 479 static void
 480 add_path_func (gpointer data, gpointer user_data)
 481 {
 482   GST_INFO ("Adding plugin path: \"%s\", will scan later", (gchar *) data);
 483   plugin_paths = g_list_append (plugin_paths, g_strdup (data));
 484 }
 485 #endif
 486
 487 #ifndef GST_DISABLE_OPTION_PARSING
 488 static void
 489 prepare_for_load_plugin_func (gpointer data, gpointer user_data)
 490 {
 491   preload_plugins = g_slist_prepend (preload_plugins, g_strdup (data));
 492 }
 493 #endif
 494
 495 static void
 496 load_plugin_func (gpointer data, gpointer user_data)
 497 {
 498   GstPlugin *plugin;
 499   const gchar *filename;
 500   GError *err = NULL;
 501
 502   filename = (const gchar *) data;
 503
 504   plugin = gst_plugin_load_file (filename, &err);
 505
 506   if (plugin) {
 507     GST_INFO ("Loaded plugin: \"%s\"", filename);
 508
 509     gst_default_registry_add_plugin (plugin);
 510   } else {
 511     if (err) {
 512       /* Report error to user, and free error */
 513       GST_ERROR ("Failed to load plugin: %s", err->message);
 514       g_error_free (err);
 515     } else {
 516       GST_WARNING ("Failed to load plugin: \"%s\"", filename);
 517     }
 518   }
 519 }
 520
 521 #ifndef GST_DISABLE_OPTION_PARSING
 522 static void
 523 split_and_iterate (const gchar * stringlist, gchar * separator, GFunc iterator,
 524     gpointer user_data)
 525 {
 526   gchar **strings;
 527   gint j = 0;
 528   gchar *lastlist = g_strdup (stringlist);
 529
 530   while (lastlist) {
 531     strings = g_strsplit (lastlist, separator, MAX_PATH_SPLIT);
 532     g_free (lastlist);
 533     lastlist = NULL;
 534
 535     while (strings[j]) {
 536       iterator (strings[j], user_data);
 537       if (++j == MAX_PATH_SPLIT) {
 538         lastlist = g_strdup (strings[j]);
 539         j = 0;
 540         break;
 541       }
 542     }
 543     g_strfreev (strings);
 544   }
 545 }
 546 #endif
 547
 548 /* we have no fail cases yet, but maybe in the future */
 549 static gboolean
 550 init_pre (GOptionContext * context, GOptionGroup * group, gpointer data,
 551     GError ** error)
 552 {
 553   if (gst_initialized) {
 554     GST_DEBUG ("already initialized");
 555     return TRUE;
 556   }
 557
 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);
 566   }
 567
 568   g_type_init ();
 569
 570   /* we need threading to be enabled right here */
 571   g_assert (g_thread_supported ());
 572   _gst_debug_init ();
 573
 574 #ifdef ENABLE_NLS
 575   setlocale (LC_ALL, "");
 576   bindtextdomain (GETTEXT_PACKAGE, LOCALEDIR);
 577 #endif /* ENABLE_NLS */
 578
 579 #ifndef GST_DISABLE_GST_DEBUG
 580   {
 581     const gchar *debug_list;
 582
 583     if (g_getenv ("GST_DEBUG_NO_COLOR") != NULL)
 584       gst_debug_set_colored (FALSE);
 585
 586     debug_list = g_getenv ("GST_DEBUG");
 587     if (debug_list) {
 588       parse_debug_list (debug_list);
 589     }
 590   }
 591 #endif
 592   /* This is the earliest we can make stuff show up in the logs.
 593    * So give some useful info about GStreamer here */
 594   GST_INFO ("Initializing GStreamer Core Library version %s", VERSION);
 595   GST_INFO ("Using library installed in %s", LIBDIR);
 596
 597   /* Print some basic system details if possible (OS/architecture) */
 598 #ifdef HAVE_SYS_UTSNAME_H
 599   {
 600     struct utsname sys_details;
 601
 602     if (uname (&sys_details) == 0) {
 603       GST_INFO ("%s %s %s %s %s", sys_details.sysname,
 604           sys_details.nodename, sys_details.release, sys_details.version,
 605           sys_details.machine);
 606     }
 607   }
 608 #endif
 609
 610   return TRUE;
 611 }
 612
 613 static gboolean
 614 gst_register_core_elements (GstPlugin * plugin)
 615 {
 616   /* register some standard builtin types */
 617   if (!gst_element_register (plugin, "bin", GST_RANK_PRIMARY,
 618           GST_TYPE_BIN) ||
 619       !gst_element_register (plugin, "pipeline", GST_RANK_PRIMARY,
 620           GST_TYPE_PIPELINE)
 621       )
 622     g_assert_not_reached ();
 623
 624   return TRUE;
 625 }
 626
 627 static GstPluginDesc plugin_desc = {
 628   GST_VERSION_MAJOR,
 629   GST_VERSION_MINOR,
 630   "staticelements",
 631   "core elements linked into the GStreamer library",
 632   gst_register_core_elements,
 633   VERSION,
 634   GST_LICENSE,
 635   PACKAGE,
 636   GST_PACKAGE_NAME,
 637   GST_PACKAGE_ORIGIN,
 638
 639   GST_PADDING_INIT
 640 };
 641
 642 #ifndef GST_DISABLE_REGISTRY
 643
 644 typedef enum
 645 {
 646   REGISTRY_SCAN_AND_UPDATE_FAILURE = 0,
 647   REGISTRY_SCAN_AND_UPDATE_SUCCESS_NOT_CHANGED,
 648   REGISTRY_SCAN_AND_UPDATE_SUCCESS_UPDATED
 649 } GstRegistryScanAndUpdateResult;
 650
 651 /*
 652  * scan_and_update_registry:
 653  * @default_registry: the #GstRegistry
 654  * @registry_file: registry filename
 655  * @write_changes: write registry if it has changed?
 656  *
 657  * Scans for registry changes and eventually updates the registry cache.
 658  *
 659  * Return: %REGISTRY_SCAN_AND_UPDATE_FAILURE if the registry could not scanned
 660  *         or updated, %REGISTRY_SCAN_AND_UPDATE_SUCCESS_NOT_CHANGED if the
 661  *         registry is clean and %REGISTRY_SCAN_AND_UPDATE_SUCCESS_UPDATED if
 662  *         it has been updated and the cache needs to be re-read.
 663  */
 664 static GstRegistryScanAndUpdateResult
 665 scan_and_update_registry (GstRegistry * default_registry,
 666     const gchar * registry_file, gboolean write_changes, GError ** error)
 667 {
 668   const gchar *plugin_path;
 669   gboolean changed = FALSE;
 670   GList *l;
 671
 672   /* scan paths specified via --gst-plugin-path */
 673   GST_DEBUG ("scanning paths added via --gst-plugin-path");
 674   for (l = plugin_paths; l != NULL; l = l->next) {
 675     GST_INFO ("Scanning plugin path: \"%s\"", (gchar *) l->data);
 676     /* CHECKME: add changed |= here as well? */
 677     gst_registry_scan_path (default_registry, (gchar *) l->data);
 678   }
 679   /* keep plugin_paths around in case a re-scan is forced later on */
 680
 681   /* GST_PLUGIN_PATH specifies a list of directories to scan for
 682    * additional plugins.  These take precedence over the system plugins */
 683   plugin_path = g_getenv ("GST_PLUGIN_PATH");
 684   if (plugin_path) {
 685     char **list;
 686     int i;
 687
 688     GST_DEBUG ("GST_PLUGIN_PATH set to %s", plugin_path);
 689     list = g_strsplit (plugin_path, G_SEARCHPATH_SEPARATOR_S, 0);
 690     for (i = 0; list[i]; i++) {
 691       changed |= gst_registry_scan_path (default_registry, list[i]);
 692     }
 693     g_strfreev (list);
 694   } else {
 695     GST_DEBUG ("GST_PLUGIN_PATH not set");
 696   }
 697
 698   /* GST_PLUGIN_SYSTEM_PATH specifies a list of plugins that are always
 699    * loaded by default.  If not set, this defaults to the system-installed
 700    * path, and the plugins installed in the user's home directory */
 701   plugin_path = g_getenv ("GST_PLUGIN_SYSTEM_PATH");
 702   if (plugin_path == NULL) {
 703     char *home_plugins;
 704
 705     GST_DEBUG ("GST_PLUGIN_SYSTEM_PATH not set");
 706
 707     /* plugins in the user's home directory take precedence over
 708      * system-installed ones */
 709     home_plugins = g_build_filename (g_get_home_dir (),
 710         ".gstreamer-" GST_MAJORMINOR, "plugins", NULL);
 711     GST_DEBUG ("scanning home plugins %s", home_plugins);
 712     changed |= gst_registry_scan_path (default_registry, home_plugins);
 713     g_free (home_plugins);
 714
 715     /* add the main (installed) library path */
 716     GST_DEBUG ("scanning main plugins %s", PLUGINDIR);
 717     changed |= gst_registry_scan_path (default_registry, PLUGINDIR);
 718   } else {
 719     gchar **list;
 720     gint i;
 721
 722     GST_DEBUG ("GST_PLUGIN_SYSTEM_PATH set to %s", plugin_path);
 723     list = g_strsplit (plugin_path, G_SEARCHPATH_SEPARATOR_S, 0);
 724     for (i = 0; list[i]; i++) {
 725       changed |= gst_registry_scan_path (default_registry, list[i]);
 726     }
 727     g_strfreev (list);
 728   }
 729
 730   /* Remove cached plugins so stale info is cleared. */
 731   changed |= _priv_gst_registry_remove_cache_plugins (default_registry);
 732
 733   if (!changed) {
 734     GST_INFO ("Registry cache has not changed");
 735     return REGISTRY_SCAN_AND_UPDATE_SUCCESS_NOT_CHANGED;
 736   }
 737
 738   if (!write_changes) {
 739     GST_INFO ("Registry cached changed, but writing is disabled. Not writing.");
 740     return REGISTRY_SCAN_AND_UPDATE_FAILURE;
 741   }
 742
 743   GST_INFO ("Registry cache changed. Writing new registry cache");
 744 #ifdef USE_BINARY_REGISTRY
 745   if (!gst_registry_binary_write_cache (default_registry, registry_file)) {
 746 #else
 747   if (!gst_registry_xml_write_cache (default_registry, registry_file)) {
 748 #endif
 749     g_set_error (error, GST_CORE_ERROR, GST_CORE_ERROR_FAILED,
 750         _("Error writing registry cache to %s: %s"),
 751         registry_file, g_strerror (errno));
 752     return REGISTRY_SCAN_AND_UPDATE_FAILURE;
 753   }
 754
 755   GST_INFO ("Registry cache written successfully");
 756   return REGISTRY_SCAN_AND_UPDATE_SUCCESS_UPDATED;
 757 }
 758
 759 static gboolean
 760 ensure_current_registry_nonforking (GstRegistry * default_registry,
 761     const gchar * registry_file, GError ** error)
 762 {
 763   /* fork() not available */
 764   GST_INFO ("reading registry cache: %s", registry_file);
 765 #ifdef USE_BINARY_REGISTRY
 766   gst_registry_binary_read_cache (default_registry, registry_file);
 767 #else
 768   gst_registry_xml_read_cache (default_registry, registry_file);
 769 #endif
 770   GST_DEBUG ("Updating registry cache in-process");
 771   scan_and_update_registry (default_registry, registry_file, TRUE, error);
 772   return TRUE;
 773 }
 774
 775 /* when forking is not available this function always does nothing but return
 776  * TRUE immediatly */
 777 static gboolean
 778 ensure_current_registry_forking (GstRegistry * default_registry,
 779     const gchar * registry_file, GError ** error)
 780 {
 781 #ifdef HAVE_FORK
 782   pid_t pid;
 783   int pfd[2];
 784   int ret;
 785
 786   /* We fork here, and let the child read and possibly rebuild the registry.
 787    * After that, the parent will re-read the freshly generated registry. */
 788   GST_DEBUG ("forking to update registry");
 789
 790   if (pipe (pfd) == -1) {
 791     g_set_error (error, GST_CORE_ERROR, GST_CORE_ERROR_FAILED,
 792         _("Error re-scanning registry %s: %s"),
 793         ", could not create pipes. Error", g_strerror (errno));
 794     return FALSE;
 795   }
 796
 797   GST_INFO ("reading registry cache: %s", registry_file);
 798 #ifdef USE_BINARY_REGISTRY
 799   gst_registry_binary_read_cache (default_registry, registry_file);
 800 #else
 801   gst_registry_xml_read_cache (default_registry, registry_file);
 802 #endif
 803
 804   pid = fork ();
 805   if (pid == -1) {
 806     GST_ERROR ("Failed to fork()");
 807     g_set_error (error, GST_CORE_ERROR, GST_CORE_ERROR_FAILED,
 808         _("Error re-scanning registry %s: %s"),
 809         ", failed to fork. Error", g_strerror (errno));
 810     return FALSE;
 811   }
 812
 813   if (pid == 0) {
 814     gint result_code;
 815
 816     /* this is the child. Close the read pipe */
 817     (void) close (pfd[0]);
 818
 819     GST_DEBUG ("child reading registry cache");
 820     result_code =
 821         scan_and_update_registry (default_registry, registry_file, TRUE, NULL);
 822
 823     /* need to use _exit, so that any exit handlers registered don't
 824      * bring down the main program */
 825     GST_DEBUG ("child exiting: %d", result_code);
 826
 827     /* make valgrind happy (yes, you can call it insane) */
 828     g_free ((char *) registry_file);
 829
 830     /* write a result byte to the pipe */
 831     do {
 832       ret = write (pfd[1], &result_code, sizeof (result_code));
 833     } while (ret == -1 && errno == EINTR);
 834     /* if ret == -1 now, we could not write to pipe, probably
 835      * means parent has exited before us */
 836     (void) close (pfd[1]);
 837
 838     _exit (0);
 839   } else {
 840     gint result_code;
 841
 842     /* parent. Close write pipe */
 843     (void) close (pfd[1]);
 844
 845     /* Wait for result from the pipe */
 846     GST_DEBUG ("Waiting for data from child");
 847     do {
 848       ret = read (pfd[0], &result_code, sizeof (result_code));
 849     } while (ret == -1 && errno == EINTR);
 850
 851     if (ret == -1) {
 852       g_set_error (error, GST_CORE_ERROR, GST_CORE_ERROR_FAILED,
 853           _("Error re-scanning registry %s: %s"),
 854           ", read returned error", g_strerror (errno));
 855       close (pfd[0]);
 856       return FALSE;
 857     }
 858     (void) close (pfd[0]);
 859
 860     /* Wait to ensure the child is reaped, but ignore the result */
 861     GST_DEBUG ("parent waiting on child");
 862     waitpid (pid, NULL, 0);
 863     GST_DEBUG ("parent done waiting on child");
 864
 865     if (ret == 0) {
 866       GST_ERROR ("child did not exit normally, terminated by signal");
 867       g_set_error (error, GST_CORE_ERROR, GST_CORE_ERROR_FAILED,
 868           _("Error re-scanning registry %s"), ", child terminated by signal");
 869       return FALSE;
 870     }
 871
 872     if (result_code == REGISTRY_SCAN_AND_UPDATE_SUCCESS_UPDATED) {
 873       GST_DEBUG ("Child succeeded. Parent reading registry cache");
 874       _priv_gst_registry_remove_cache_plugins (default_registry);
 875 #ifdef USE_BINARY_REGISTRY
 876       gst_registry_binary_read_cache (default_registry, registry_file);
 877 #else
 878       gst_registry_xml_read_cache (default_registry, registry_file);
 879 #endif
 880     } else if (result_code == REGISTRY_SCAN_AND_UPDATE_FAILURE) {
 881       GST_DEBUG ("Child failed. Parent re-scanning registry, ignoring errors.");
 882       scan_and_update_registry (default_registry, registry_file, FALSE, NULL);
 883     }
 884   }
 885 #endif /* HAVE_FORK */
 886   return TRUE;
 887 }
 888
 889 static gboolean
 890 ensure_current_registry (GError ** error)
 891 {
 892   char *registry_file;
 893   GstRegistry *default_registry;
 894   gboolean ret;
 895   gboolean do_fork;
 896
 897   default_registry = gst_registry_get_default ();
 898   registry_file = g_strdup (g_getenv ("GST_REGISTRY"));
 899   if (registry_file == NULL) {
 900 #ifdef USE_BINARY_REGISTRY
 901     registry_file = g_build_filename (g_get_home_dir (),
 902         ".gstreamer-" GST_MAJORMINOR, "registry." HOST_CPU ".bin", NULL);
 903 #else
 904     registry_file = g_build_filename (g_get_home_dir (),
 905         ".gstreamer-" GST_MAJORMINOR, "registry." HOST_CPU ".xml", NULL);
 906 #endif
 907   }
 908
 909   /* first see if forking is enabled */
 910   do_fork = _gst_enable_registry_fork;
 911   if (do_fork) {
 912     const gchar *fork_env;
 913
 914     /* forking enabled, see if it is disabled with an env var */
 915     if ((fork_env = g_getenv ("GST_REGISTRY_FORK"))) {
 916       /* fork enabled for any value different from "no" */
 917       do_fork = strcmp (fork_env, "no") != 0;
 918     }
 919   }
 920
 921   /* now check registry with or without forking */
 922   if (do_fork) {
 923     GST_DEBUG ("forking for registry rebuild");
 924     ret = ensure_current_registry_forking (default_registry, registry_file,
 925         error);
 926   } else {
 927     GST_DEBUG ("requested not to fork for registry rebuild");
 928     ret = ensure_current_registry_nonforking (default_registry, registry_file,
 929         error);
 930   }
 931
 932   g_free (registry_file);
 933
 934   return ret;
 935 }
 936 #endif /* GST_DISABLE_REGISTRY */
 937
 938 /*
 939  * this bit handles:
 940  * - initalization of threads if we use them
 941  * - log handler
 942  * - initial output
 943  * - initializes gst_format
 944  * - registers a bunch of types for gst_objects
 945  *
 946  * - we don't have cases yet where this fails, but in the future
 947  *   we might and then it's nice to be able to return that
 948  */
 949 static gboolean
 950 init_post (GOptionContext * context, GOptionGroup * group, gpointer data,
 951     GError ** error)
 952 {
 953   GLogLevelFlags llf;
 954
 955 #ifndef GST_DISABLE_TRACE
 956   GstTrace *gst_trace;
 957 #endif /* GST_DISABLE_TRACE */
 958
 959   if (gst_initialized) {
 960     GST_DEBUG ("already initialized");
 961     return TRUE;
 962   }
 963
 964   llf = G_LOG_LEVEL_CRITICAL | G_LOG_LEVEL_ERROR | G_LOG_FLAG_FATAL;
 965   g_log_set_handler (g_log_domain_gstreamer, llf, debug_log_handler, NULL);
 966
 967   _priv_gst_quarks_initialize ();
 968   _gst_format_initialize ();
 969   _gst_query_initialize ();
 970   gst_object_get_type ();
 971   gst_pad_get_type ();
 972   gst_element_factory_get_type ();
 973   gst_element_get_type ();
 974   gst_type_find_factory_get_type ();
 975   gst_bin_get_type ();
 976
 977 #ifndef GST_DISABLE_INDEX
 978   gst_index_factory_get_type ();
 979 #endif /* GST_DISABLE_INDEX */
 980 #ifndef GST_DISABLE_URI
 981   gst_uri_handler_get_type ();
 982 #endif /* GST_DISABLE_URI */
 983
 984   gst_structure_get_type ();
 985   _gst_value_initialize ();
 986   gst_param_spec_fraction_get_type ();
 987   gst_caps_get_type ();
 988   _gst_event_initialize ();
 989   _gst_buffer_initialize ();
 990   _gst_message_initialize ();
 991   _gst_tag_initialize ();
 992
 993   /* register core plugins */
 994   _gst_plugin_register_static (&plugin_desc);
 995
 996   _gst_plugin_initialize ();
 997
 998   /*
 999    * Any errors happening below this point are non-fatal, we therefore mark
1000    * gstreamer as being initialized, since it is the case from a plugin point of
1001    * view.
1002    *
1003    * If anything fails, it will be put back to FALSE in gst_init_check().
1004    * This allows some special plugins that would call gst_init() to not cause a
1005    * looping effect (i.e. initializing GStreamer twice).
1006    */
1007   gst_initialized = TRUE;
1008
1009 #ifndef GST_DISABLE_REGISTRY
1010   if (!ensure_current_registry (error))
1011     return FALSE;
1012 #endif /* GST_DISABLE_REGISTRY */
1013
1014   /* if we need to preload plugins, do so now */
1015   g_slist_foreach (preload_plugins, load_plugin_func, NULL);
1016   /* keep preload_plugins around in case a re-scan is forced later on */
1017
1018 #ifndef GST_DISABLE_TRACE
1019   _gst_trace_on = 0;
1020   if (_gst_trace_on) {
1021     gst_trace = gst_trace_new ("gst.trace", 1024);
1022     gst_trace_set_default (gst_trace);
1023   }
1024 #endif /* GST_DISABLE_TRACE */
1025
1026   return TRUE;
1027 }
1028
1029 #ifndef GST_DISABLE_GST_DEBUG
1030 static gboolean
1031 select_all (GstPlugin * plugin, gpointer user_data)
1032 {
1033   return TRUE;
1034 }
1035
1036 static gint
1037 sort_by_category_name (gconstpointer a, gconstpointer b)
1038 {
1039   return strcmp (gst_debug_category_get_name ((GstDebugCategory *) a),
1040       gst_debug_category_get_name ((GstDebugCategory *) b));
1041 }
1042
1043 static void
1044 gst_debug_help (void)
1045 {
1046   GSList *list, *walk;
1047   GList *list2, *g;
1048
1049   /* Need to ensure the registry is loaded to get debug categories */
1050   if (!init_post (NULL, NULL, NULL, NULL))
1051     exit (1);
1052
1053   list2 = gst_registry_plugin_filter (gst_registry_get_default (),
1054       select_all, FALSE, NULL);
1055
1056   /* FIXME this is gross.  why don't debug have categories PluginFeatures? */
1057   for (g = list2; g; g = g_list_next (g)) {
1058     GstPlugin *plugin = GST_PLUGIN_CAST (g->data);
1059
1060     gst_plugin_load (plugin);
1061   }
1062   g_list_free (list2);
1063
1064   list = gst_debug_get_all_categories ();
1065   walk = list = g_slist_sort (list, sort_by_category_name);
1066
1067   g_print ("\n");
1068   g_print ("name                  level    description\n");
1069   g_print ("---------------------+--------+--------------------------------\n");
1070
1071   while (walk) {
1072     GstDebugCategory *cat = (GstDebugCategory *) walk->data;
1073
1074     if (gst_debug_is_colored ()) {
1075       gchar *color = gst_debug_construct_term_color (cat->color);
1076
1077       g_print ("%s%-20s\033[00m  %1d %s  %s%s\033[00m\n",
1078           color,
1079           gst_debug_category_get_name (cat),
1080           gst_debug_category_get_threshold (cat),
1081           gst_debug_level_get_name (gst_debug_category_get_threshold (cat)),
1082           color, gst_debug_category_get_description (cat));
1083       g_free (color);
1084     } else {
1085       g_print ("%-20s  %1d %s  %s\n", gst_debug_category_get_name (cat),
1086           gst_debug_category_get_threshold (cat),
1087           gst_debug_level_get_name (gst_debug_category_get_threshold (cat)),
1088           gst_debug_category_get_description (cat));
1089     }
1090     walk = g_slist_next (walk);
1091   }
1092   g_slist_free (list);
1093   g_print ("\n");
1094 }
1095 #endif
1096
1097 #ifndef GST_DISABLE_OPTION_PARSING
1098 static gboolean
1099 parse_one_option (gint opt, const gchar * arg, GError ** err)
1100 {
1101   switch (opt) {
1102     case ARG_VERSION:
1103       g_print ("GStreamer Core Library version %s\n", PACKAGE_VERSION);
1104       exit (0);
1105     case ARG_FATAL_WARNINGS:{
1106       GLogLevelFlags fatal_mask;
1107
1108       fatal_mask = g_log_set_always_fatal (G_LOG_FATAL_MASK);
1109       fatal_mask |= G_LOG_LEVEL_WARNING | G_LOG_LEVEL_CRITICAL;
1110       g_log_set_always_fatal (fatal_mask);
1111       break;
1112     }
1113 #ifndef GST_DISABLE_GST_DEBUG
1114     case ARG_DEBUG_LEVEL:{
1115       gint tmp = 0;
1116
1117       tmp = strtol (arg, NULL, 0);
1118       if (tmp >= 0 && tmp < GST_LEVEL_COUNT) {
1119         gst_debug_set_default_threshold (tmp);
1120       }
1121       break;
1122     }
1123     case ARG_DEBUG:
1124       parse_debug_list (arg);
1125       break;
1126     case ARG_DEBUG_NO_COLOR:
1127       gst_debug_set_colored (FALSE);
1128       break;
1129     case ARG_DEBUG_DISABLE:
1130       gst_debug_set_active (FALSE);
1131       break;
1132     case ARG_DEBUG_HELP:
1133       gst_debug_help ();
1134       exit (0);
1135 #endif
1136     case ARG_PLUGIN_SPEW:
1137       break;
1138     case ARG_PLUGIN_PATH:
1139 #ifndef GST_DISABLE_REGISTRY
1140       split_and_iterate (arg, G_SEARCHPATH_SEPARATOR_S, add_path_func, NULL);
1141 #endif /* GST_DISABLE_REGISTRY */
1142       break;
1143     case ARG_PLUGIN_LOAD:
1144       split_and_iterate (arg, ",", prepare_for_load_plugin_func, NULL);
1145       break;
1146     case ARG_SEGTRAP_DISABLE:
1147       _gst_disable_segtrap = TRUE;
1148       break;
1149     case ARG_REGISTRY_FORK_DISABLE:
1150       _gst_enable_registry_fork = FALSE;
1151       break;
1152     default:
1153       g_set_error (err, G_OPTION_ERROR, G_OPTION_ERROR_UNKNOWN_OPTION,
1154           _("Unknown option"));
1155       return FALSE;
1156   }
1157
1158   return TRUE;
1159 }
1160
1161 static gboolean
1162 parse_goption_arg (const gchar * opt,
1163     const gchar * arg, gpointer data, GError ** err)
1164 {
1165   static const struct
1166   {
1167     gchar *opt;
1168     int val;
1169   } options[] = {
1170     {
1171     "--gst-version", ARG_VERSION}, {
1172     "--gst-fatal-warnings", ARG_FATAL_WARNINGS},
1173 #ifndef GST_DISABLE_GST_DEBUG
1174     {
1175     "--gst-debug-level", ARG_DEBUG_LEVEL}, {
1176     "--gst-debug", ARG_DEBUG}, {
1177     "--gst-debug-disable", ARG_DEBUG_DISABLE}, {
1178     "--gst-debug-no-color", ARG_DEBUG_NO_COLOR}, {
1179     "--gst-debug-help", ARG_DEBUG_HELP},
1180 #endif
1181     {
1182     "--gst-plugin-spew", ARG_PLUGIN_SPEW}, {
1183     "--gst-plugin-path", ARG_PLUGIN_PATH}, {
1184     "--gst-plugin-load", ARG_PLUGIN_LOAD}, {
1185     "--gst-disable-segtrap", ARG_SEGTRAP_DISABLE}, {
1186     "--gst-disable-registry-fork", ARG_REGISTRY_FORK_DISABLE}, {
1187     NULL}
1188   };
1189   gint val = 0, n;
1190
1191   for (n = 0; options[n].opt; n++) {
1192     if (!strcmp (opt, options[n].opt)) {
1193       val = options[n].val;
1194       break;
1195     }
1196   }
1197
1198   return parse_one_option (val, arg, err);
1199 }
1200 #endif
1201
1202 extern GstRegistry *_gst_registry_default;
1203
1204 /**
1205  * gst_deinit:
1206  *
1207  * Clean up any resources created by GStreamer in gst_init().
1208  *
1209  * It is normally not needed to call this function in a normal application
1210  * as the resources will automatically be freed when the program terminates.
1211  * This function is therefore mostly used by testsuites and other memory
1212  * profiling tools.
1213  *
1214  * After this call GStreamer (including this method) should not be used anymore.
1215  */
1216 void
1217 gst_deinit (void)
1218 {
1219   GstClock *clock;
1220
1221   GST_INFO ("deinitializing GStreamer");
1222
1223   if (!gst_initialized) {
1224     GST_DEBUG ("already deinitialized");
1225     return;
1226   }
1227
1228   g_slist_foreach (preload_plugins, (GFunc) g_free, NULL);
1229   g_slist_free (preload_plugins);
1230   preload_plugins = NULL;
1231
1232 #ifndef GST_DISABLE_REGISTRY
1233   g_list_foreach (plugin_paths, (GFunc) g_free, NULL);
1234   g_list_free (plugin_paths);
1235   plugin_paths = NULL;
1236 #endif
1237
1238   clock = gst_system_clock_obtain ();
1239   gst_object_unref (clock);
1240   gst_object_unref (clock);
1241
1242   _priv_gst_registry_cleanup ();
1243
1244   gst_initialized = FALSE;
1245   GST_INFO ("deinitialized GStreamer");
1246 }
1247
1248 /**
1249  * gst_version:
1250  * @major: pointer to a guint to store the major version number
1251  * @minor: pointer to a guint to store the minor version number
1252  * @micro: pointer to a guint to store the micro version number
1253  * @nano:  pointer to a guint to store the nano version number
1254  *
1255  * Gets the version number of the GStreamer library.
1256  */
1257 void
1258 gst_version (guint * major, guint * minor, guint * micro, guint * nano)
1259 {
1260   g_return_if_fail (major);
1261   g_return_if_fail (minor);
1262   g_return_if_fail (micro);
1263   g_return_if_fail (nano);
1264
1265   *major = GST_VERSION_MAJOR;
1266   *minor = GST_VERSION_MINOR;
1267   *micro = GST_VERSION_MICRO;
1268   *nano = GST_VERSION_NANO;
1269 }
1270
1271 /**
1272  * gst_version_string:
1273  *
1274  * This function returns a string that is useful for describing this version
1275  * of GStreamer to the outside world: user agent strings, logging, ...
1276  *
1277  * Returns: a newly allocated string describing this version of GStreamer.
1278  */
1279
1280 gchar *
1281 gst_version_string ()
1282 {
1283   guint major, minor, micro, nano;
1284
1285   gst_version (&major, &minor, &micro, &nano);
1286   if (nano == 0)
1287     return g_strdup_printf ("GStreamer %d.%d.%d", major, minor, micro);
1288   else if (nano == 1)
1289     return g_strdup_printf ("GStreamer %d.%d.%d (CVS)", major, minor, micro);
1290   else
1291     return g_strdup_printf ("GStreamer %d.%d.%d (prerelease)", major, minor,
1292         micro);
1293 }
1294
1295 /**
1296  * gst_segtrap_is_enabled:
1297  *
1298  * Some functions in the GStreamer core might install a custom SIGSEGV handler
1299  * to better catch and report errors to the application. Currently this feature
1300  * is enabled by default when loading plugins.
1301  *
1302  * Applications might want to disable this behaviour with the
1303  * gst_segtrap_set_enabled() function. This is typically done if the application
1304  * wants to install its own handler without GStreamer interfering.
1305  *
1306  * Returns: %TRUE if GStreamer is allowed to install a custom SIGSEGV handler.
1307  *
1308  * Since: 0.10.10
1309  */
1310 gboolean
1311 gst_segtrap_is_enabled (void)
1312 {
1313   /* yeps, it's enabled when it's not disabled */
1314   return !_gst_disable_segtrap;
1315 }
1316
1317 /**
1318  * gst_segtrap_set_enabled:
1319  * @enabled: whether a custom SIGSEGV handler should be installed.
1320  *
1321  * Applications might want to disable/enable the SIGSEGV handling of
1322  * the GStreamer core. See gst_segtrap_is_enabled() for more information.
1323  *
1324  * Since: 0.10.10
1325  */
1326 void
1327 gst_segtrap_set_enabled (gboolean enabled)
1328 {
1329   _gst_disable_segtrap = !enabled;
1330 }
1331
1332 /**
1333  * gst_registry_fork_is_enabled:
1334  *
1335  * By default GStreamer will perform a fork() when scanning and rebuilding the
1336  * registry file.
1337  *
1338  * Applications might want to disable this behaviour with the
1339  * gst_registry_fork_set_enabled() function.
1340  *
1341  * Returns: %TRUE if GStreamer will use fork() when rebuilding the registry. On
1342  * platforms without fork(), this function will always return %FALSE.
1343  *
1344  * Since: 0.10.10
1345  */
1346 gboolean
1347 gst_registry_fork_is_enabled (void)
1348 {
1349   return _gst_enable_registry_fork;
1350 }
1351
1352 /**
1353  * gst_registry_fork_set_enabled:
1354  * @enabled: whether rebuilding the registry may fork
1355  *
1356  * Applications might want to disable/enable the usage of fork() when rebuilding
1357  * the registry. See gst_registry_fork_is_enabled() for more information.
1358  *
1359  * On platforms without fork(), this function will have no effect on the return
1360  * value of gst_registry_fork_is_enabled().
1361  *
1362  * Since: 0.10.10
1363  */
1364 void
1365 gst_registry_fork_set_enabled (gboolean enabled)
1366 {
1367 #ifdef HAVE_FORK
1368   _gst_enable_registry_fork = enabled;
1369 #endif /* HAVE_FORK */
1370 }
1371
1372
1373 /**
1374  * gst_update_registry:
1375  *
1376  * Forces GStreamer to re-scan its plugin paths and update the default
1377  * plugin registry.
1378  *
1379  * Applications will almost never need to call this function, it is only
1380  * useful if the application knows new plugins have been installed (or old
1381  * ones removed) since the start of the application (or, to be precise, the
1382  * first call to gst_init()) and the application wants to make use of any
1383  * newly-installed plugins without restarting the application.
1384  *
1385  * Applications should assume that the registry update is neither atomic nor
1386  * thread-safe and should therefore not have any dynamic pipelines running
1387  * (including the playbin and decodebin elements) and should also not create
1388  * any elements or access the GStreamer registry while the update is in
1389  * progress.
1390  *
1391  * Note that this function may block for a significant amount of time.
1392  *
1393  * Returns: %TRUE if the registry has been updated successfully (does not
1394  *          imply that there were changes), otherwise %FALSE.
1395  *
1396  * Since: 0.10.12
1397  */
1398 gboolean
1399 gst_update_registry (void)
1400 {
1401   gboolean res = FALSE;
1402
1403 #ifndef GST_DISABLE_REGISTRY
1404   GError *err = NULL;
1405
1406   res = ensure_current_registry (&err);
1407   if (err) {
1408     GST_WARNING ("registry update failed: %s", err->message);
1409     g_error_free (err);
1410   } else {
1411     GST_LOG ("registry update succeeded");
1412   }
1413
1414   if (preload_plugins) {
1415     g_slist_foreach (preload_plugins, load_plugin_func, NULL);
1416   }
1417 #else
1418   GST_WARNING ("registry update failed: %s", "registry disabled");
1419 #endif /* GST_DISABLE_REGISTRY */
1420
1421   return res;
1422 }