src/modules/bank.c

   1 /*****************************************************************************
   2  * bank.c : Modules list
   3  *****************************************************************************
   4  * Copyright (C) 2001-2011 VLC authors and VideoLAN
   5  *
   6  * Authors: Sam Hocevar <sam@zoy.org>
   7  *          Ethan C. Baldridge <BaldridgeE@cadmus.com>
   8  *          Hans-Peter Jansen <hpj@urpla.net>
   9  *          Gildas Bazin <gbazin@videolan.org>
  10  *          Rémi Denis-Courmont
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU Lesser General Public License as published by
  14  * the Free Software Foundation; either version 2.1 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  20  * GNU Lesser General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Lesser General Public License
  23  * along with this program; if not, write to the Free Software Foundation,
  24  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  25  *****************************************************************************/
  26
  27 #ifdef HAVE_CONFIG_H
  28 # include "config.h"
  29 #endif
  30
  31 #include <stdlib.h>
  32 #include <stdio.h>
  33 #include <string.h>
  34 #include <assert.h>
  35
  36 #include <sys/types.h>
  37 #include <sys/stat.h>
  38 #include <unistd.h>
  39 #ifdef HAVE_SEARCH_H
  40 # include <search.h>
  41 #endif
  42
  43 #include <vlc_common.h>
  44 #include <vlc_plugin.h>
  45 #include <vlc_modules.h>
  46 #include <vlc_fs.h>
  47 #include <vlc_block.h>
  48 #include "libvlc.h"
  49 #include "config/configuration.h"
  50 #include "modules/modules.h"
  51
  52 typedef struct vlc_modcap
  53 {
  54     char *name;
  55     module_t **modv;
  56     size_t modc;
  57 } vlc_modcap_t;
  58
  59 static int vlc_modcap_cmp(const void *a, const void *b)
  60 {
  61     const vlc_modcap_t *capa = a, *capb = b;
  62     return strcmp(capa->name, capb->name);
  63 }
  64
  65 static void vlc_modcap_free(void *data)
  66 {
  67     vlc_modcap_t *cap = data;
  68
  69     free(cap->modv);
  70     free(cap->name);
  71     free(cap);
  72 }
  73
  74 static int vlc_module_cmp (const void *a, const void *b)
  75 {
  76     const module_t *const *ma = a, *const *mb = b;
  77     /* Note that qsort() uses _ascending_ order,
  78      * so the smallest module is the one with the biggest score. */
  79     return (*mb)->i_score - (*ma)->i_score;
  80 }
  81
  82 static void vlc_modcap_sort(const void *node, const VISIT which,
  83                             const int depth)
  84 {
  85     vlc_modcap_t *const *cp = node, *cap = *cp;
  86
  87     if (which != postorder && which != leaf)
  88         return;
  89
  90     qsort(cap->modv, cap->modc, sizeof (*cap->modv), vlc_module_cmp);
  91     (void) depth;
  92 }
  93
  94 static struct
  95 {
  96     vlc_mutex_t lock;
  97     block_t *caches;
  98     void *caps_tree;
  99     unsigned usage;
 100 } modules = { VLC_STATIC_MUTEX, NULL, NULL, 0 };
 101
 102 vlc_plugin_t *vlc_plugins = NULL;
 103
 104 /**
 105  * Adds a module to the bank
 106  */
 107 static int vlc_module_store(module_t *mod)
 108 {
 109     const char *name = module_get_capability(mod);
 110     vlc_modcap_t *cap = malloc(sizeof (*cap));
 111     if (unlikely(cap == NULL))
 112         return -1;
 113
 114     cap->name = strdup(name);
 115     cap->modv = NULL;
 116     cap->modc = 0;
 117
 118     if (unlikely(cap->name == NULL))
 119         goto error;
 120
 121     vlc_modcap_t **cp = tsearch(cap, &modules.caps_tree, vlc_modcap_cmp);
 122     if (unlikely(cp == NULL))
 123         goto error;
 124
 125     if (*cp != cap)
 126     {
 127         vlc_modcap_free(cap);
 128         cap = *cp;
 129     }
 130
 131     module_t **modv = realloc(cap->modv, sizeof (*modv) * (cap->modc + 1));
 132     if (unlikely(modv == NULL))
 133         return -1;
 134
 135     cap->modv = modv;
 136     cap->modv[cap->modc] = mod;
 137     cap->modc++;
 138     return 0;
 139 error:
 140     vlc_modcap_free(cap);
 141     return -1;
 142 }
 143
 144 /**
 145  * Adds a plugin (and all its modules) to the bank
 146  */
 147 static void vlc_plugin_store(vlc_plugin_t *lib)
 148 {
 149     /*vlc_assert_locked (&modules.lock);*/
 150
 151     lib->next = vlc_plugins;
 152     vlc_plugins = lib;
 153
 154     for (module_t *m = lib->module; m != NULL; m = m->next)
 155         vlc_module_store(m);
 156 }
 157
 158 /**
 159  * Registers a statically-linked plug-in.
 160  */
 161 static vlc_plugin_t *module_InitStatic(vlc_plugin_cb entry)
 162 {
 163     /* Initializes the statically-linked library */
 164     vlc_plugin_t *lib = vlc_plugin_describe (entry);
 165     if (unlikely(lib == NULL))
 166         return NULL;
 167
 168 #ifdef HAVE_DYNAMIC_PLUGINS
 169     atomic_init(&lib->loaded, true);
 170     lib->unloadable = false;
 171 #endif
 172     return lib;
 173 }
 174
 175 #if defined(__ELF__) || !HAVE_DYNAMIC_PLUGINS
 176 VLC_WEAK
 177 extern vlc_plugin_cb vlc_static_modules[];
 178
 179 static void module_InitStaticModules(void)
 180 {
 181     if (!vlc_static_modules)
 182         return;
 183
 184     for (unsigned i = 0; vlc_static_modules[i]; i++)
 185     {
 186         vlc_plugin_t *lib = module_InitStatic(vlc_static_modules[i]);
 187         if (likely(lib != NULL))
 188             vlc_plugin_store(lib);
 189     }
 190 }
 191 #else
 192 static void module_InitStaticModules(void) { }
 193 #endif
 194
 195 #ifdef HAVE_DYNAMIC_PLUGINS
 196 static const char vlc_entry_name[] = "vlc_entry" MODULE_SUFFIX;
 197
 198 /**
 199  * Loads a dynamically-linked plug-in into memory and initialize it.
 200  *
 201  * The module can then be handled by module_need() and module_unneed().
 202  *
 203  * \param path file path of the shared object
 204  * \param fast whether to optimize loading for speed or safety
 205  *             (fast is used when the plug-in is registered but not used)
 206  */
 207 static vlc_plugin_t *module_InitDynamic(vlc_object_t *obj, const char *path,
 208                                         bool fast)
 209 {
 210     void *handle = vlc_dlopen(path, fast);
 211     if (handle == NULL)
 212     {
 213         char *errmsg = vlc_dlerror();
 214         msg_Err(obj, "cannot load plug-in %s: %s", path,
 215                 errmsg ? errmsg : "unknown error");
 216         free(errmsg);
 217         return NULL;
 218     }
 219
 220     /* Try to resolve the symbol */
 221     vlc_plugin_cb entry = vlc_dlsym(handle, vlc_entry_name);
 222     if (entry == NULL)
 223     {
 224         msg_Warn (obj, "cannot find plug-in entry point in %s", path);
 225         goto error;
 226     }
 227
 228     /* We can now try to call the symbol */
 229     vlc_plugin_t *plugin = vlc_plugin_describe(entry);
 230     if (unlikely(plugin == NULL))
 231     {
 232         /* With a well-written module we shouldn't have to print an
 233          * additional error message here, but just make sure. */
 234         msg_Err (obj, "cannot initialize plug-in %s", path);
 235         goto error;
 236     }
 237
 238     plugin->handle = handle;
 239     atomic_init(&plugin->loaded, true);
 240     return plugin;
 241 error:
 242     vlc_dlclose(handle);
 243     return NULL;
 244 }
 245
 246 typedef enum
 247 {
 248     CACHE_READ_FILE  = 0x1,
 249     CACHE_SCAN_DIR   = 0x2,
 250     CACHE_WRITE_FILE = 0x4,
 251 } cache_mode_t;
 252
 253 typedef struct module_bank
 254 {
 255     vlc_object_t *obj;
 256     const char   *base;
 257     cache_mode_t  mode;
 258
 259     size_t        size;
 260     vlc_plugin_t **plugins;
 261     vlc_plugin_t *cache;
 262 } module_bank_t;
 263
 264 /**
 265  * Scans a plug-in from a file.
 266  */
 267 static int AllocatePluginFile (module_bank_t *bank, const char *abspath,
 268                                const char *relpath, const struct stat *st)
 269 {
 270     vlc_plugin_t *plugin = NULL;
 271
 272     /* Check our plugins cache first then load plugin if needed */
 273     if (bank->mode & CACHE_READ_FILE)
 274     {
 275         plugin = vlc_cache_lookup(&bank->cache, relpath);
 276
 277         if (plugin != NULL
 278          && (plugin->mtime != (int64_t)st->st_mtime
 279           || plugin->size != (uint64_t)st->st_size))
 280         {
 281             msg_Err(bank->obj, "stale plugins cache: modified %s",
 282                     plugin->abspath);
 283             vlc_plugin_destroy(plugin);
 284             plugin = NULL;
 285         }
 286     }
 287
 288     if (plugin == NULL)
 289     {
 290         plugin = module_InitDynamic(bank->obj, abspath, true);
 291
 292         if (plugin != NULL)
 293         {
 294             plugin->path = xstrdup(relpath);
 295             plugin->mtime = st->st_mtime;
 296             plugin->size = st->st_size;
 297         }
 298     }
 299
 300     if (plugin == NULL)
 301         return -1;
 302
 303     vlc_plugin_store(plugin);
 304
 305     if (bank->mode & CACHE_WRITE_FILE) /* Add entry to to-be-saved cache */
 306     {
 307         bank->plugins = xrealloc(bank->plugins,
 308                                  (bank->size + 1) * sizeof (vlc_plugin_t *));
 309         bank->plugins[bank->size] = plugin;
 310         bank->size++;
 311     }
 312
 313     /* TODO: deal with errors */
 314     return  0;
 315 }
 316
 317 /**
 318  * Recursively browses a directory to look for plug-ins.
 319  */
 320 static void AllocatePluginDir (module_bank_t *bank, unsigned maxdepth,
 321                                const char *absdir, const char *reldir)
 322 {
 323     if (maxdepth == 0)
 324         return;
 325     maxdepth--;
 326
 327     DIR *dh = vlc_opendir (absdir);
 328     if (dh == NULL)
 329         return;
 330
 331     /* Parse the directory and try to load all files it contains. */
 332     for (;;)
 333     {
 334         char *relpath = NULL, *abspath = NULL;
 335         const char *file = vlc_readdir (dh);
 336         if (file == NULL)
 337             break;
 338
 339         /* Skip ".", ".." */
 340         if (!strcmp (file, ".") || !strcmp (file, ".."))
 341             continue;
 342
 343         /* Compute path relative to plug-in base directory */
 344         if (reldir != NULL)
 345         {
 346             if (asprintf (&relpath, "%s"DIR_SEP"%s", reldir, file) == -1)
 347                 relpath = NULL;
 348         }
 349         else
 350             relpath = strdup (file);
 351         if (unlikely(relpath == NULL))
 352             continue;
 353
 354         /* Compute absolute path */
 355         if (asprintf (&abspath, "%s"DIR_SEP"%s", bank->base, relpath) == -1)
 356         {
 357             abspath = NULL;
 358             goto skip;
 359         }
 360
 361         struct stat st;
 362         if (vlc_stat (abspath, &st) == -1)
 363             goto skip;
 364
 365         if (S_ISREG (st.st_mode))
 366         {
 367             static const char prefix[] = "lib";
 368             static const char suffix[] = "_plugin"LIBEXT;
 369             size_t len = strlen (file);
 370
 371 #ifndef __OS2__
 372             /* Check that file matches the "lib*_plugin"LIBEXT pattern */
 373             if (len > strlen (suffix)
 374              && !strncmp (file, prefix, strlen (prefix))
 375              && !strcmp (file + len - strlen (suffix), suffix))
 376 #else
 377             /* We load all the files ending with LIBEXT on OS/2,
 378              * because OS/2 has a 8.3 length limitation for DLL name */
 379             if (len > strlen (LIBEXT)
 380              && !strcasecmp (file + len - strlen (LIBEXT), LIBEXT))
 381 #endif
 382                 AllocatePluginFile (bank, abspath, relpath, &st);
 383         }
 384         else if (S_ISDIR (st.st_mode))
 385             /* Recurse into another directory */
 386             AllocatePluginDir (bank, maxdepth, abspath, relpath);
 387     skip:
 388         free (relpath);
 389         free (abspath);
 390     }
 391     closedir (dh);
 392 }
 393
 394 /**
 395  * Scans for plug-ins within a file system hierarchy.
 396  * \param path base directory to browse
 397  */
 398 static void AllocatePluginPath(vlc_object_t *obj, const char *path,
 399                                cache_mode_t mode)
 400 {
 401     module_bank_t bank =
 402     {
 403         .obj = obj,
 404         .base = path,
 405         .mode = mode,
 406     };
 407
 408     if (mode & CACHE_READ_FILE)
 409         bank.cache = vlc_cache_load(obj, path, &modules.caches);
 410     else
 411         msg_Dbg(bank.obj, "ignoring plugins cache file");
 412
 413     if (mode & CACHE_SCAN_DIR)
 414     {
 415         msg_Dbg(obj, "recursively browsing `%s'", bank.base);
 416
 417         /* Don't go deeper than 5 subdirectories */
 418         AllocatePluginDir(&bank, 5, path, NULL);
 419     }
 420
 421     /* Deal with unmatched cache entries from cache file */
 422     while (bank.cache != NULL)
 423     {
 424         vlc_plugin_t *plugin = bank.cache;
 425
 426         bank.cache = plugin->next;
 427         if (mode & CACHE_SCAN_DIR)
 428             vlc_plugin_destroy(plugin);
 429         else
 430             vlc_plugin_store(plugin);
 431     }
 432
 433     if (mode & CACHE_WRITE_FILE)
 434         CacheSave(obj, path, bank.plugins, bank.size);
 435
 436     free(bank.plugins);
 437 }
 438
 439 /**
 440  * Enumerates all dynamic plug-ins that can be found.
 441  *
 442  * This function will recursively browse the default plug-ins directory and any
 443  * directory listed in the VLC_PLUGIN_PATH environment variable.
 444  * For performance reasons, a cache is normally used so that plug-in shared
 445  * objects do not need to loaded and linked into the process.
 446  */
 447 static void AllocateAllPlugins (vlc_object_t *p_this)
 448 {
 449     char *paths;
 450     cache_mode_t mode = 0;
 451
 452     if (var_InheritBool(p_this, "plugins-cache"))
 453         mode |= CACHE_READ_FILE;
 454     if (var_InheritBool(p_this, "plugins-scan"))
 455         mode |= CACHE_SCAN_DIR;
 456     if (var_InheritBool(p_this, "reset-plugins-cache"))
 457         mode = (mode | CACHE_WRITE_FILE) & ~CACHE_READ_FILE;
 458
 459 #if VLC_WINSTORE_APP
 460     /* Windows Store Apps can not load external plugins with absolute paths. */
 461     AllocatePluginPath (p_this, "plugins", mode);
 462 #else
 463     /* Contruct the special search path for system that have a relocatable
 464      * executable. Set it to <vlc path>/plugins. */
 465     char *vlcpath = config_GetSysPath(VLC_PKG_LIB_DIR, "plugins");
 466     if (likely(vlcpath != NULL))
 467     {
 468         AllocatePluginPath(p_this, vlcpath, mode);
 469         free(vlcpath);
 470     }
 471 #endif /* VLC_WINSTORE_APP */
 472
 473     /* If the user provided a plugin path, we add it to the list */
 474     paths = getenv( "VLC_PLUGIN_PATH" );
 475     if( paths == NULL )
 476         return;
 477
 478     paths = strdup( paths ); /* don't harm the environment ! :) */
 479     if( unlikely(paths == NULL) )
 480         return;
 481
 482     for( char *buf, *path = strtok_r( paths, PATH_SEP, &buf );
 483          path != NULL;
 484          path = strtok_r( NULL, PATH_SEP, &buf ) )
 485         AllocatePluginPath (p_this, path, mode);
 486
 487     free( paths );
 488 }
 489
 490 /**
 491  * Ensures that a plug-in is loaded.
 492  *
 493  * \note This function is thread-safe but not re-entrant.
 494  *
 495  * \return 0 on success, -1 on failure
 496  */
 497 int module_Map(vlc_object_t *obj, vlc_plugin_t *plugin)
 498 {
 499     static vlc_mutex_t lock = VLC_STATIC_MUTEX;
 500
 501     if (atomic_load_explicit(&plugin->loaded, memory_order_acquire))
 502         return 0; /* fast path: already loaded */
 503
 504     /* Try to load the plug-in (without locks, so read-only) */
 505     assert(plugin->abspath != NULL);
 506
 507     void *handle = vlc_dlopen(plugin->abspath, false);
 508     if (handle == NULL)
 509     {
 510         char *errmsg = vlc_dlerror();
 511         msg_Err(obj, "cannot load plug-in %s: %s", plugin->abspath,
 512                 errmsg ? errmsg : "unknown error");
 513         free(errmsg);
 514         return -1;
 515     }
 516
 517     vlc_plugin_cb entry = vlc_dlsym(handle, vlc_entry_name);
 518     if (entry == NULL)
 519     {
 520         msg_Err(obj, "cannot find plug-in entry point in %s", plugin->abspath);
 521         vlc_dlclose(handle);
 522         return -1;
 523     }
 524
 525     vlc_mutex_lock(&lock);
 526     if (!atomic_load_explicit(&plugin->loaded, memory_order_relaxed))
 527     {   /* Lock is held, update the plug-in structure */
 528         if (vlc_plugin_resolve(plugin, entry))
 529         {
 530             vlc_mutex_unlock(&lock);
 531             return -1;
 532         }
 533
 534         plugin->handle = handle;
 535         atomic_store_explicit(&plugin->loaded, true, memory_order_release);
 536     }
 537     else /* Another thread won the race to load the plugin */
 538         vlc_dlclose(handle);
 539     vlc_mutex_unlock(&lock);
 540
 541     return 0;
 542 }
 543
 544 /**
 545  * Ensures that a module is not loaded.
 546  *
 547  * \note This function is not thread-safe. The caller must ensure that the
 548  * plug-in is no longer used before calling this function.
 549  */
 550 static void module_Unmap(vlc_plugin_t *plugin)
 551 {
 552     if (!plugin->unloadable)
 553         return;
 554     if (!atomic_exchange_explicit(&plugin->loaded, false,
 555                                   memory_order_acquire))
 556         return;
 557
 558     assert(plugin->handle != NULL);
 559     vlc_dlclose(plugin->handle);
 560 }
 561 #else
 562 int module_Map(vlc_object_t *obj, vlc_plugin_t *plugin)
 563 {
 564     (void) obj; (void) plugin;
 565     return 0;
 566 }
 567
 568 static void module_Unmap(vlc_plugin_t *plugin)
 569 {
 570     (void) plugin;
 571 }
 572 #endif /* HAVE_DYNAMIC_PLUGINS */
 573
 574 /**
 575  * Init bank
 576  *
 577  * Creates a module bank structure which will be filled later
 578  * on with all the modules found.
 579  */
 580 void module_InitBank (void)
 581 {
 582     vlc_mutex_lock (&modules.lock);
 583
 584     if (modules.usage == 0)
 585     {
 586         /* Fills the module bank structure with the core module infos.
 587          * This is very useful as it will allow us to consider the core
 588          * library just as another module, and for instance the configuration
 589          * options of core will be available in the module bank structure just
 590          * as for every other module. */
 591         vlc_plugin_t *plugin = module_InitStatic(vlc_entry__core);
 592         if (likely(plugin != NULL))
 593             vlc_plugin_store(plugin);
 594         config_SortConfig ();
 595     }
 596     modules.usage++;
 597
 598     /* We do retain the module bank lock until the plugins are loaded as well.
 599      * This is ugly, this staged loading approach is needed: LibVLC gets
 600      * some configuration parameters relevant to loading the plugins from
 601      * the core (builtin) module. The module bank becomes shared read-only data
 602      * once it is ready, so we need to fully serialize initialization.
 603      * DO NOT UNCOMMENT the following line unless you managed to squeeze
 604      * module_LoadPlugins() before you unlock the mutex. */
 605     /*vlc_mutex_unlock (&modules.lock);*/
 606 }
 607
 608 /**
 609  * Unloads all unused plugin modules and empties the module
 610  * bank in case of success.
 611  */
 612 void module_EndBank (bool b_plugins)
 613 {
 614     vlc_plugin_t *libs = NULL;
 615     block_t *caches = NULL;
 616     void *caps_tree = NULL;
 617
 618     /* If plugins were _not_ loaded, then the caller still has the bank lock
 619      * from module_InitBank(). */
 620     if( b_plugins )
 621         vlc_mutex_lock (&modules.lock);
 622     /*else
 623         vlc_assert_locked (&modules.lock); not for static mutexes :( */
 624
 625     assert (modules.usage > 0);
 626     if (--modules.usage == 0)
 627     {
 628         config_UnsortConfig ();
 629         libs = vlc_plugins;
 630         caches = modules.caches;
 631         caps_tree = modules.caps_tree;
 632         vlc_plugins = NULL;
 633         modules.caches = NULL;
 634         modules.caps_tree = NULL;
 635     }
 636     vlc_mutex_unlock (&modules.lock);
 637
 638     tdestroy(caps_tree, vlc_modcap_free);
 639
 640     while (libs != NULL)
 641     {
 642         vlc_plugin_t *lib = libs;
 643
 644         libs = lib->next;
 645         module_Unmap(lib);
 646         vlc_plugin_destroy(lib);
 647     }
 648
 649     block_ChainRelease(caches);
 650 }
 651
 652 #undef module_LoadPlugins
 653 /**
 654  * Loads module descriptions for all available plugins.
 655  * Fills the module bank structure with the plugin modules.
 656  *
 657  * \param p_this vlc object structure
 658  */
 659 void module_LoadPlugins(vlc_object_t *obj)
 660 {
 661     /*vlc_assert_locked (&modules.lock); not for static mutexes :( */
 662
 663     if (modules.usage == 1)
 664     {
 665         module_InitStaticModules ();
 666 #ifdef HAVE_DYNAMIC_PLUGINS
 667         msg_Dbg (obj, "searching plug-in modules");
 668         AllocateAllPlugins (obj);
 669 #endif
 670         config_UnsortConfig ();
 671         config_SortConfig ();
 672
 673         twalk(modules.caps_tree, vlc_modcap_sort);
 674     }
 675     vlc_mutex_unlock (&modules.lock);
 676
 677     size_t count;
 678     module_t **list = module_list_get (&count);
 679     module_list_free (list);
 680     msg_Dbg (obj, "plug-ins loaded: %zu modules", count);
 681 }
 682
 683 /**
 684  * Frees the flat list of VLC modules.
 685  * @param list list obtained by module_list_get()
 686  * @param length number of items on the list
 687  * @return nothing.
 688  */
 689 void module_list_free (module_t **list)
 690 {
 691     free (list);
 692 }
 693
 694 /**
 695  * Gets the flat list of VLC modules.
 696  * @param n [OUT] pointer to the number of modules
 697  * @return table of module pointers (release with module_list_free()),
 698  *         or NULL in case of error (in that case, *n is zeroed).
 699  */
 700 module_t **module_list_get (size_t *n)
 701 {
 702     module_t **tab = NULL;
 703     size_t i = 0;
 704
 705     assert (n != NULL);
 706
 707     for (vlc_plugin_t *lib = vlc_plugins; lib != NULL; lib = lib->next)
 708     {
 709         module_t **nt = realloc(tab, (i + lib->modules_count) * sizeof (*tab));
 710         if (unlikely(nt == NULL))
 711         {
 712             free (tab);
 713             *n = 0;
 714             return NULL;
 715         }
 716
 717         tab = nt;
 718         for (module_t *m = lib->module; m != NULL; m = m->next)
 719             tab[i++] = m;
 720     }
 721     *n = i;
 722     return tab;
 723 }
 724
 725 /**
 726  * Builds a sorted list of all VLC modules with a given capability.
 727  * The list is sorted from the highest module score to the lowest.
 728  * @param list pointer to the table of modules [OUT]
 729  * @param name name of capability of modules to look for
 730  * @return the number of matching found, or -1 on error (*list is then NULL).
 731  * @note *list must be freed with module_list_free().
 732  */
 733 ssize_t module_list_cap (module_t ***restrict list, const char *name)
 734 {
 735     const vlc_modcap_t **cp = tfind(&name, &modules.caps_tree, vlc_modcap_cmp);
 736     if (cp == NULL)
 737     {
 738         *list = NULL;
 739         return 0;
 740     }
 741
 742     const vlc_modcap_t *cap = *cp;
 743     size_t n = cap->modc;
 744     module_t **tab = vlc_alloc (n, sizeof (*tab));
 745     *list = tab;
 746     if (unlikely(tab == NULL))
 747         return -1;
 748
 749     memcpy(tab, cap->modv, sizeof (*tab) * n);
 750     return n;
 751 }