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_GetLibDir ();
 466     if (likely(vlcpath != NULL)
 467      && likely(asprintf (&paths, "%s" DIR_SEP "plugins", vlcpath) != -1))
 468     {
 469         AllocatePluginPath (p_this, paths, mode);
 470         free( paths );
 471     }
 472     free (vlcpath);
 473 #endif /* VLC_WINSTORE_APP */
 474
 475     /* If the user provided a plugin path, we add it to the list */
 476     paths = getenv( "VLC_PLUGIN_PATH" );
 477     if( paths == NULL )
 478         return;
 479
 480     paths = strdup( paths ); /* don't harm the environment ! :) */
 481     if( unlikely(paths == NULL) )
 482         return;
 483
 484     for( char *buf, *path = strtok_r( paths, PATH_SEP, &buf );
 485          path != NULL;
 486          path = strtok_r( NULL, PATH_SEP, &buf ) )
 487         AllocatePluginPath (p_this, path, mode);
 488
 489     free( paths );
 490 }
 491
 492 /**
 493  * Ensures that a plug-in is loaded.
 494  *
 495  * \note This function is thread-safe but not re-entrant.
 496  *
 497  * \return 0 on success, -1 on failure
 498  */
 499 int module_Map(vlc_object_t *obj, vlc_plugin_t *plugin)
 500 {
 501     static vlc_mutex_t lock = VLC_STATIC_MUTEX;
 502
 503     if (atomic_load_explicit(&plugin->loaded, memory_order_acquire))
 504         return 0; /* fast path: already loaded */
 505
 506     /* Try to load the plug-in (without locks, so read-only) */
 507     assert(plugin->abspath != NULL);
 508
 509     void *handle = vlc_dlopen(plugin->abspath, false);
 510     if (handle == NULL)
 511     {
 512         char *errmsg = vlc_dlerror();
 513         msg_Err(obj, "cannot load plug-in %s: %s", plugin->abspath,
 514                 errmsg ? errmsg : "unknown error");
 515         free(errmsg);
 516         return -1;
 517     }
 518
 519     vlc_plugin_cb entry = vlc_dlsym(handle, vlc_entry_name);
 520     if (entry == NULL)
 521     {
 522         msg_Err(obj, "cannot find plug-in entry point in %s", plugin->abspath);
 523         vlc_dlclose(handle);
 524         return -1;
 525     }
 526
 527     vlc_mutex_lock(&lock);
 528     if (!atomic_load_explicit(&plugin->loaded, memory_order_relaxed))
 529     {   /* Lock is held, update the plug-in structure */
 530         if (vlc_plugin_resolve(plugin, entry))
 531         {
 532             vlc_mutex_unlock(&lock);
 533             return -1;
 534         }
 535
 536         plugin->handle = handle;
 537         atomic_store_explicit(&plugin->loaded, true, memory_order_release);
 538     }
 539     else /* Another thread won the race to load the plugin */
 540         vlc_dlclose(handle);
 541     vlc_mutex_unlock(&lock);
 542
 543     return 0;
 544 }
 545
 546 /**
 547  * Ensures that a module is not loaded.
 548  *
 549  * \note This function is not thread-safe. The caller must ensure that the
 550  * plug-in is no longer used before calling this function.
 551  */
 552 static void module_Unmap(vlc_plugin_t *plugin)
 553 {
 554     if (!plugin->unloadable)
 555         return;
 556     if (!atomic_exchange_explicit(&plugin->loaded, false,
 557                                   memory_order_acquire))
 558         return;
 559
 560     assert(plugin->handle != NULL);
 561     vlc_dlclose(plugin->handle);
 562 }
 563 #else
 564 int module_Map(vlc_object_t *obj, vlc_plugin_t *plugin)
 565 {
 566     (void) obj; (void) plugin;
 567     return 0;
 568 }
 569
 570 static void module_Unmap(vlc_plugin_t *plugin)
 571 {
 572     (void) plugin;
 573 }
 574 #endif /* HAVE_DYNAMIC_PLUGINS */
 575
 576 /**
 577  * Init bank
 578  *
 579  * Creates a module bank structure which will be filled later
 580  * on with all the modules found.
 581  */
 582 void module_InitBank (void)
 583 {
 584     vlc_mutex_lock (&modules.lock);
 585
 586     if (modules.usage == 0)
 587     {
 588         /* Fills the module bank structure with the core module infos.
 589          * This is very useful as it will allow us to consider the core
 590          * library just as another module, and for instance the configuration
 591          * options of core will be available in the module bank structure just
 592          * as for every other module. */
 593         vlc_plugin_t *plugin = module_InitStatic(vlc_entry__core);
 594         if (likely(plugin != NULL))
 595             vlc_plugin_store(plugin);
 596         config_SortConfig ();
 597     }
 598     modules.usage++;
 599
 600     /* We do retain the module bank lock until the plugins are loaded as well.
 601      * This is ugly, this staged loading approach is needed: LibVLC gets
 602      * some configuration parameters relevant to loading the plugins from
 603      * the core (builtin) module. The module bank becomes shared read-only data
 604      * once it is ready, so we need to fully serialize initialization.
 605      * DO NOT UNCOMMENT the following line unless you managed to squeeze
 606      * module_LoadPlugins() before you unlock the mutex. */
 607     /*vlc_mutex_unlock (&modules.lock);*/
 608 }
 609
 610 /**
 611  * Unloads all unused plugin modules and empties the module
 612  * bank in case of success.
 613  */
 614 void module_EndBank (bool b_plugins)
 615 {
 616     vlc_plugin_t *libs = NULL;
 617     block_t *caches = NULL;
 618     void *caps_tree = NULL;
 619
 620     /* If plugins were _not_ loaded, then the caller still has the bank lock
 621      * from module_InitBank(). */
 622     if( b_plugins )
 623         vlc_mutex_lock (&modules.lock);
 624     /*else
 625         vlc_assert_locked (&modules.lock); not for static mutexes :( */
 626
 627     assert (modules.usage > 0);
 628     if (--modules.usage == 0)
 629     {
 630         config_UnsortConfig ();
 631         libs = vlc_plugins;
 632         caches = modules.caches;
 633         caps_tree = modules.caps_tree;
 634         vlc_plugins = NULL;
 635         modules.caches = NULL;
 636         modules.caps_tree = NULL;
 637     }
 638     vlc_mutex_unlock (&modules.lock);
 639
 640     tdestroy(caps_tree, vlc_modcap_free);
 641
 642     while (libs != NULL)
 643     {
 644         vlc_plugin_t *lib = libs;
 645
 646         libs = lib->next;
 647         module_Unmap(lib);
 648         vlc_plugin_destroy(lib);
 649     }
 650
 651     block_ChainRelease(caches);
 652 }
 653
 654 #undef module_LoadPlugins
 655 /**
 656  * Loads module descriptions for all available plugins.
 657  * Fills the module bank structure with the plugin modules.
 658  *
 659  * \param p_this vlc object structure
 660  * \return total number of modules in bank after loading all plug-ins
 661  */
 662 size_t module_LoadPlugins (vlc_object_t *obj)
 663 {
 664     /*vlc_assert_locked (&modules.lock); not for static mutexes :( */
 665
 666     if (modules.usage == 1)
 667     {
 668         module_InitStaticModules ();
 669 #ifdef HAVE_DYNAMIC_PLUGINS
 670         msg_Dbg (obj, "searching plug-in modules");
 671         AllocateAllPlugins (obj);
 672 #endif
 673         config_UnsortConfig ();
 674         config_SortConfig ();
 675
 676         twalk(modules.caps_tree, vlc_modcap_sort);
 677     }
 678     vlc_mutex_unlock (&modules.lock);
 679
 680     size_t count;
 681     module_t **list = module_list_get (&count);
 682     module_list_free (list);
 683     msg_Dbg (obj, "plug-ins loaded: %zu modules", count);
 684     return count;
 685 }
 686
 687 /**
 688  * Frees the flat list of VLC modules.
 689  * @param list list obtained by module_list_get()
 690  * @param length number of items on the list
 691  * @return nothing.
 692  */
 693 void module_list_free (module_t **list)
 694 {
 695     free (list);
 696 }
 697
 698 /**
 699  * Gets the flat list of VLC modules.
 700  * @param n [OUT] pointer to the number of modules
 701  * @return table of module pointers (release with module_list_free()),
 702  *         or NULL in case of error (in that case, *n is zeroed).
 703  */
 704 module_t **module_list_get (size_t *n)
 705 {
 706     module_t **tab = NULL;
 707     size_t i = 0;
 708
 709     assert (n != NULL);
 710
 711     for (vlc_plugin_t *lib = vlc_plugins; lib != NULL; lib = lib->next)
 712     {
 713         module_t **nt = realloc(tab, (i + lib->modules_count) * sizeof (*tab));
 714         if (unlikely(nt == NULL))
 715         {
 716             free (tab);
 717             *n = 0;
 718             return NULL;
 719         }
 720
 721         tab = nt;
 722         for (module_t *m = lib->module; m != NULL; m = m->next)
 723             tab[i++] = m;
 724     }
 725     *n = i;
 726     return tab;
 727 }
 728
 729 /**
 730  * Builds a sorted list of all VLC modules with a given capability.
 731  * The list is sorted from the highest module score to the lowest.
 732  * @param list pointer to the table of modules [OUT]
 733  * @param name name of capability of modules to look for
 734  * @return the number of matching found, or -1 on error (*list is then NULL).
 735  * @note *list must be freed with module_list_free().
 736  */
 737 ssize_t module_list_cap (module_t ***restrict list, const char *name)
 738 {
 739     const vlc_modcap_t **cp = tfind(&name, &modules.caps_tree, vlc_modcap_cmp);
 740     if (cp == NULL)
 741     {
 742         *list = NULL;
 743         return 0;
 744     }
 745
 746     const vlc_modcap_t *cap = *cp;
 747     size_t n = cap->modc;
 748     module_t **tab = vlc_alloc (n, sizeof (*tab));
 749     *list = tab;
 750     if (unlikely(tab == NULL))
 751         return -1;
 752
 753     memcpy(tab, cap->modv, sizeof (*tab) * n);
 754     return n;
 755 }