Re: dlloader documentation update

[Ralf Wildenhues]

Hi Peter,

* Peter Rosin wrote on Fri, Jan 22, 2010 at 09:53:40AM CET:
> Recently (when I wrote the testcase for error reporting
> in the loadlibrary loader) I found that the documentation
> for the dlloader section of the api was a wee bit lacking
> in accuracy...

Oh yes it is.  Oh brother.

> So, I set out to update it, see attached patch.
> 
> When going through this, I found it strange that
> lt_dlloader_add didn't call vtable->dlloader_init. Isn't
> that desirable? I'll send an additional patch to show what
> I mean...

That one's already been shot down.  ;->

The comment about us needing testsuite exposure for this kind of code is
still very much valid though.  We should try and see how far we can get
with the current documented sample code.

- the current code requires to pass in a structure allocated on the heap
  (i.e., we keep a pointer to it); I'm inclined to want to fix ltdl by
  copying the (documented part of the) input rather than change the
  documented API though.  Never mind the small memleak that ensues
  (this should still have a NEWS entry however).
- documenting the contents of a structure is bad bad bad.  Since we
  already do it, it is cast in stone and cannot be changed (neither
  amended, because even that will cause old compiled code to break),
- long deftype lines should be wrapped with @<newline>
- as argued in the other thread, lt_dlloader_init should not be
  documented nor used.
- typo: responible

> --- a/doc/libtool.texi
> +++ b/doc/libtool.texi
> @@ -4282,16 +4282,24 @@ can be recognised by @code{lt_dlloader_find} and 
> removed with
>  already in use by libltdl's builtin loaders:
>  
>  @table @asis
> address@hidden "dlopen"
> address@hidden "lt_dlopen"
>  The system dynamic library loader, if one exists.
> address@hidden "dld"
> address@hidden "lt_dld_link"
>  The @sc{gnu} dld loader, if @file{libdld} was installed when libltdl was
>  built.
> address@hidden "dlpreload"
> -The loader for @code{lt_dlopen}ing of preloaded static modules.
> address@hidden "lt_preopen"
> +The loader for @code{lt_dlopen}ing of preopened static modules.
> address@hidden "lt_dyld"
> +The Darwin / OS X dynamic library loader.
> address@hidden "lt_load_add_on"
> +The BeOS dynamic library loader.
> address@hidden "lt_loadlibrary"
> +The Win32 dynamic library loader.
> address@hidden "lt_shl_load"
> +The HP/UX dynamic library loader.
>  @end table
>  
> -The prefix "dl" is reserved for loaders supplied with future versions of
> +The prefix "lt_" is reserved for loaders supplied with future versions of
>  libltdl, so you should not use that for your own loader names.
>  
>  @noindent

That part and the perror removals look fairly ok to me, with
s/Win32/Windows/.

Cheers, and thanks,
Ralf