ChangeLogTag:Mon Dec 5 22:23:25 UTC 2011 Steve Huston <shuston@riverace.com>

3 files changed, 69 insertions, 20 deletions

diff --git a/ChangeLog b/ChangeLog
index 97c50d2b775..f5eecad7069 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+Mon Dec  5 22:23:25 UTC 2011  Steve Huston  <shuston@riverace.com>
+
+        * ace/DLL.h:
+        * ace/DLL_Manager.h: Corrected and expanded the descriptions of how
+          DLL/library names are handled, decorated, and located.
+
 Wed Jun 29 20:47:33 UTC 2011  Steve Huston  <shuston@riverace.com>
 
         * ace/Select_Reactor_T.cpp:
diff --git a/ace/DLL.h b/ace/DLL.h
index 64cb646576a..9182d9df731 100644
--- a/ace/DLL.h
+++ b/ace/DLL.h
@@ -88,24 +88,37 @@ public:
 
   /**
    * This method opens and dynamically links a specified DLL.
-   * @param dll_name  The filename or path of the DLL to load.
-   *        If a filename is given to @c open(), the @c ACE::ldfind() is used
-   *        to locate DLLs via the following algorithms: (1) DLL filename
-   *        expansion: @c ACE::ldfind() determines the name of the DLL by
-   *        adding the appropriate prefix and suffix, e.g., it adds the @c lib
-   *        prefix and @c .so suffix for Solaris and the @c .dll suffix for
-   *        Windows and (2) DLL search path: @c ACE::ldfind() will also search
-   *        for the designated DLL using the platform's DLL search path
-   *        environment variable, e.g., it searches for DLLs using @c
-   *        LD_LIBRARY_PATH on many UNIX systems and @c PATH on Windows.
+   * @param dll_name  The filename or path of the DLL to load. ACE will
+   *        attempt to apply the platform's standard library/DLL prefixes
+   *        and suffixes, allowing a simple, unadorned name to be passed
+   *        regardless of platform. The set of name transforms is listed
+   *        below. A @i decorator is a platform's name designator for a debug
+   *        vs release build. For example, on Windows it is usually "d".
+   *        @li Name + decorator + suffix
+   *        @li Name + suffix
+   *        @li Prefix + name + decorator + suffix
+   *        @li Prefix + name + suffix
+   *        @li Name
+   *        Note that the transforms with @i decorator will be avoided if
+   *        ACE is built with the @c ACE_DISABLE_DEBUG_DLL_CHECK config macro.
+   *
+   *        @Note There is another mode for locating library/DLL files that
+   *        was used in old versions of ACE. The alternate method builds
+   *        more combinations of pathname by combining the names transforms
+   *        above with locations listed in the platform's standard "path"
+   *        locations (e.g., @c LD_LIBRARY_PATH). It can be enabled by building
+   *        ACE with the @c ACE_MUST_HELP_DLOPEN_SEARCH_PATH config macro.
+   *        Use of this option is discouraged since it avoids the standard
+   *        platform search options and security mechanisms.
+   *
    * @param open_mode  Flags to alter the actions taken when loading the DLL.
    *        The possible values are:
    *        @li @c RTLD_LAZY (this the default): loads identifier symbols but
    *            not the symbols for functions, which are loaded dynamically
-   *            on-demand.
+   *            on demand.
    *        @li @c RTLD_NOW: performs all necessary relocations when
    *            @a dll_name is first loaded
-   *        @li RTLD_GLOBAL: makes symbols available for relocation
+   *        @li @c RTLD_GLOBAL: makes symbols available for relocation
    *            processing of any other DLLs.
    * @param close_handle_on_destruction  Indicates whether or not the
    *        close() method will be called to close an open DLL when this
diff --git a/ace/DLL_Manager.h b/ace/DLL_Manager.h
index a59636696ba..ebd9497cf6e 100644
--- a/ace/DLL_Manager.h
+++ b/ace/DLL_Manager.h
@@ -68,14 +68,44 @@ public:
   const ACE_TCHAR *dll_name () const;
 
   /**
-   * This method opens and dynamically links @a dll_name.  The default
-   * mode is <RTLD_LAZY>, which loads identifier symbols but not the
-   * symbols for functions, which are loaded dynamically on-demand.
-   * Other supported modes include: <RTLD_NOW>, which performs all
-   * necessary relocations when @a dll_name is first loaded and
-   * <RTLD_GLOBAL>, which makes symbols available for relocation
-   * processing of any other DLLs.  Returns -1 on failure and 0 on
-   * success.
+   * This method opens and dynamically links a library/DLL.
+   * @param dll_name  The filename or path of the DLL to load. ACE will
+   *        attempt to apply the platform's standard library/DLL prefixes
+   *        and suffixes, allowing a simple, unadorned name to be passed
+   *        regardless of platform. The set of name transforms is listed
+   *        below. A @i decorator is a platform's name designator for a debug
+   *        vs release build. For example, on Windows it is usually "d".
+   *        @li Name + decorator + suffix
+   *        @li Name + suffix
+   *        @li Prefix + name + decorator + suffix
+   *        @li Prefix + name + suffix
+   *        @li Name
+   *        Note that the transforms with @i decorator will be avoided if
+   *        ACE is built with the @c ACE_DISABLE_DEBUG_DLL_CHECK config macro.
+   *
+   *        @Note There is another mode for locating library/DLL files that
+   *        was used in old versions of ACE. The alternate method builds
+   *        more combinations of pathname by combining the names transforms
+   *        above with locations listed in the platform's standard "path"
+   *        locations (e.g., @c LD_LIBRARY_PATH). It can be enabled by building
+   *        ACE with the @c ACE_MUST_HELP_DLOPEN_SEARCH_PATH config macro.
+   *        Use of this option is discouraged since it avoids the standard
+   *        platform search options and security mechanisms.
+   *
+   * @param open_mode  Flags to alter the actions taken when loading the DLL.
+   *        The possible values are:
+   *        @li @c RTLD_LAZY (this the default): loads identifier symbols but
+   *            not the symbols for functions, which are loaded dynamically
+   *            on demand.
+   *        @li @c RTLD_NOW: performs all necessary relocations when
+   *            @a dll_name is first loaded
+   *        @li @c RTLD_GLOBAL: makes symbols available for relocation
+   *            processing of any other DLLs.
+   * @param handle If a value other than @c ACE_INVALID_HANDLE is supplied,
+   *        this object is assigned the specified handle instead of attempting
+   *        to open the specified @a dll_name.
+   * @retval -1 On failure
+   * @retval 0 On success.
    */
   int open (const ACE_TCHAR *dll_name,
             int open_mode,