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