lt_dlopenadvise() inconsistencies in libtool-2.2.2

[Gary Kumfert]

Hi,

I am reporting either a documentation bug, an implementation bug,
or both in 2.2.2.  I'm not sure what the intent was, but it took
me (and my good friend, Tom) a bit of time to hunt
down why my libraries weren't being loaded globally like they
used to when I upgraded libtool.

The code says:
        lt_dlopenadvise() takes a lt_dladvise as its
        second argument (not a lt_dladvise* as with
        all the other lt_dladvise_* functions!)

   ltdl.h: lines 67 -- 82

        /* User module loading advisors.  */
        LT_SCOPE int        lt_dladvise_init     (lt_dladvise *advise);
        LT_SCOPE int        lt_dladvise_destroy  (lt_dladvise *advise);
        LT_SCOPE int        lt_dladvise_ext      (lt_dladvise *advise);
        LT_SCOPE int        lt_dladvise_resident (lt_dladvise *advise);
        LT_SCOPE int        lt_dladvise_local    (lt_dladvise *advise);
        LT_SCOPE int        lt_dladvise_global   (lt_dladvise *advise);

        /* Portable libltdl versions of the system dlopen() API. */
        LT_SCOPE lt_dlhandle lt_dlopen          (const char *filename);
        LT_SCOPE lt_dlhandle lt_dlopenext       (const char *filename);
        LT_SCOPE lt_dlhandle lt_dlopenadvise    (const char *filename,
                                                 lt_dladvise advise);
        LT_SCOPE void *     lt_dlsym            (lt_dlhandle handle, const char 
*name);
        LT_SCOPE const char *lt_dlerror         (void);
        LT_SCOPE int        lt_dlclose          (lt_dlhandle handle);

The documentation says:
 1.  Actually Section 11.1 doesn't have an entry for lt_dlopenadvise()
        which is a bug in itself.

 2. AND the code examples where lt_dlopenadvise() appears
        (e.g. lt_dladvise_ext() in Section 11.1) indicate a lt_dladvise*
        which doesn't gibe with the code.
          lt_dlhandle
          my_dlopenext (const char *filename)
          {
            lt_dlhandle handle = 0;
            lt_dladvise advise;

            if (!lt_dladvise_init (&advise) && !lt_dladvise_ext (&advise))
              handle = lt_dlopenadvise (filename, &advise); //<<<<---- wrong!!!

            lt_dladvise_destroy (&advise);

            return handle;
          }

So, when I inferred the API from the documentation, I ended up
having my ** casted to a * and lost the bit about global loading
that I had carefully set.

See the problem?

Questions:
1. What was the intended API?  lt_dladvise or lt_dladvise* ?
2. Why bother with all the casting in the implementation?
   The type is known statically and the compiler *could*
   have helped in finding this problem if we let it.
3. What is the resolution?  I'd like to know what to plan for.

Thanks,

Gary

------------------------------------------------------------------------
  Gary Kumfert, Ph.D.                               <address@hidden>
  Center for Applied Scientific Computing          phone: 925-424-2580
  Lawrence Livermore National Laboratory           fax:   925-424-2477
  P.O. Box 808,    L-550
  Livermore, CA 94551-0808