gh-119349: Add ctypes.util function to list loaded shared libraries

Doc/library/ctypes.rst

@@ -1406,6 +1406,32 @@ the shared library name at development time, and hardcode that into the wrapper
 module instead of using :func:`~ctypes.util.find_library` to locate the library at runtime.
 
 
+.. _ctypes-listing-loaded-shared-libraries:
+
+Listing loaded shared libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When writing code that relies on code loaded from shared libraries, it can be
+useful to know which shared libraries have already been loaded into the current
+process.
+
+The :mod:`!ctypes.util` module provides the :func:`~ctypes.util.dllist` function,
+which calls the different APIs provided by the various platforms to help determine
+which shared libraries have already been loaded into the current process.
+
+
+.. data:: dllist()
+   :module: ctypes.util
+   :noindex:
+
+   Try to provide a list of paths of the shared libraries loaded into the current
+   process.  These paths are not normalized or processed in any way. If the
+   function is not able to determine the list of loaded libraries (either because
+   the current platform does not support it, or because an error occurred), it
+   returns ``None``.
+
+The exact functionality is system dependent.
+
 .. _ctypes-loading-shared-libraries:
 
 Loading shared libraries
@@ -2083,6 +2109,21 @@ Utility functions
    .. availability:: Windows
 
 
+.. function:: dllist()
+   :module: ctypes.util
+
+   Try to provide a list of paths of the shared libraries loaded into the current
+   process.  These paths are not normalized or processed in any way. If the
+   function is not able to determine the list of loaded libraries (either because
+   the current platform is not Windows, MacOS, or Linux and does not support the
+   the ``dl_iterate_phdr`` API in libc, or because an error occurred), it
+   returns ``None``.
+
+   The exact functionality is system dependent.
+
+   .. versionadded:: 3.14
+
+
 .. function:: FormatError([code])
 
    Returns a textual description of the error code *code*.  If no error code is

Doc/whatsnew/3.14.rst

@@ -357,6 +357,9 @@ ctypes
   complex C types.
   (Contributed by Sergey B Kirpichev in :gh:`61103`).
 
+* Added :func:`ctypes.util.dllist` for listing the shared libraries
+  loaded by the current process.
+  (Contributed by Brian Ward in :gh:`119349`.)
 
 datetime
 --------

Lib/ctypes/util.py

@@ -67,6 +67,68 @@ def find_library(name):
                 return fname
         return None
 
+    import ctypes
+    from ctypes import wintypes
+
+    # https://learn.microsoft.com/windows/win32/api/psapi/nf-psapi-enumprocessmodules
+    # https://learn.microsoft.com/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulefilenamew
+
+    _kernel32 = ctypes.WinDLL('kernel32', use_last_error=True)
+    _get_current_process = _kernel32["GetCurrentProcess"]
+    _get_current_process.restype = wintypes.HANDLE
+
+    _k32_get_module_file_name = _kernel32["GetModuleFileNameW"]
+    _k32_get_module_file_name.restype = wintypes.DWORD
+    _k32_get_module_file_name.argtypes = (
+        wintypes.HMODULE,
+        wintypes.LPWSTR,
+        wintypes.DWORD,
+    )
+
+    _psapi = ctypes.WinDLL('psapi', use_last_error=True)
+    _enum_process_modules = _psapi["EnumProcessModules"]
+    _enum_process_modules.restype = wintypes.BOOL
+    _enum_process_modules.argtypes = (
+        wintypes.HANDLE,
+        ctypes.POINTER(wintypes.HMODULE),
+        wintypes.DWORD,
+        wintypes.LPDWORD,
+    )
+
+    def _get_module_filename(module: wintypes.HMODULE):
+        name = (wintypes.WCHAR * 32767)() # UNICODE_STRING_MAX_CHARS
+        if _k32_get_module_file_name(module, name, len(name)):
+            return name.value
+        return None
+
+
+    def _get_module_handles():
+        process = _get_current_process()
+        space_needed = wintypes.DWORD()
+        n = 1024
+        while True:
+            modules = (wintypes.HMODULE * n)()
+            if not _enum_process_modules(process,
+                                         modules,
+                                         ctypes.sizeof(modules),
+                                         ctypes.byref(space_needed)):
+                err = ctypes.get_last_error()
+                msg = ctypes.FormatError(err).strip()
+                raise ctypes.WinError(err, f"EnumProcessModules failed: {msg}")
+            n = space_needed.value // ctypes.sizeof(wintypes.HMODULE)
+            if n <= len(modules):
+                return modules[:n]
+
+    def dllist():
+        try:
+            modules = _get_module_handles()
+        except OSError:
+            return None
+        # skip first entry, which is the executable itself
+        libraries = [name for h in modules[1:]
+                        if (name := _get_module_filename(h)) is not None]
+        return libraries
+
 elif os.name == "posix" and sys.platform in {"darwin", "ios", "tvos", "watchos"}:
     from ctypes.macholib.dyld import dyld_find as _dyld_find
     def find_library(name):
@@ -80,6 +142,21 @@ def find_library(name):
                 continue
         return None
 
+    import ctypes
+
+    # https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/dyld.3.html
+    _libc = ctypes.CDLL(find_library("c"))
+    _dyld_get_image_name = _libc["_dyld_get_image_name"]
+    _dyld_get_image_name.restype = ctypes.c_char_p
+
+    def dllist():
+        num_images = _libc._dyld_image_count()
+        # start at 1 to skip executable
+        libraries = [os.fsdecode(name) for i in range(1, num_images)
+                        if (name := _dyld_get_image_name(i)) is not None]
+
+        return libraries
+
 elif sys.platform.startswith("aix"):
     # AIX has two styles of storing shared libraries
     # GNU auto_tools refer to these as svr4 and aix
@@ -341,6 +418,51 @@ def find_library(name):
             return _findSoname_ldconfig(name) or \
                    _get_soname(_findLib_gcc(name)) or _get_soname(_findLib_ld(name))
 
+
+# other systems use functions common to Linux and a few other Unix-like systems
+# https://man7.org/linux/man-pages/man3/dl_iterate_phdr.3.html
+# https://man.freebsd.org/cgi/man.cgi?query=dl_iterate_phdr
+# https://man.openbsd.org/dl_iterate_phdr
+# https://docs.oracle.com/cd/E88353_01/html/E37843/dl-iterate-phdr-3c.html
+# this relies on find_library, which is why it is defined at the end
+if (os.name == "posix" and
+    sys.platform not in {"darwin", "ios", "tvos", "watchos"}):
+    import ctypes
+    _libc_path = find_library("c")
+    if (_libc_path is None or
+        not hasattr((_libc := ctypes.CDLL(_libc_path)), "dl_iterate_phdr")):
+        def dllist():
+            return None
+    else:
+        class _dl_phdr_info(ctypes.Structure):
+            _fields_ = [
+                ("dlpi_addr", ctypes.c_void_p),
+                ("dlpi_name", ctypes.c_char_p),
+                ("dlpi_phdr", ctypes.c_void_p),
+                ("dlpi_phnum", ctypes.c_ushort),
+            ]
+
+
+        @ctypes.CFUNCTYPE(
+            ctypes.c_int,
+            ctypes.POINTER(_dl_phdr_info),
+            ctypes.c_size_t,
+            ctypes.POINTER(ctypes.py_object),
+        )
+        def _info_callback(info, _size, data):
+            libraries = data.contents.value
+            name = os.fsdecode(info.contents.dlpi_name)
+            libraries.append(name)
+            return 0
+
+
+        def dllist():
+            libraries = []
+            _libc.dl_iterate_phdr(_info_callback,
+                                    ctypes.byref(ctypes.py_object(libraries)))
+            # remove the first entry, which is the executable itself
+            return libraries[1:]
+
 ################################################################
 # test code
 
@@ -384,5 +506,7 @@ def test():
             print(cdll.LoadLibrary("libcrypt.so"))
             print(find_library("crypt"))
 
+        print(dllist())
+
 if __name__ == "__main__":
     test()

Lib/test/test_ctypes/test_dllist.py

@@ -0,0 +1,61 @@
+import os
+import sys
+import test.support
+import unittest
+from ctypes import CDLL
+from ctypes.util import dllist
+from test.support import import_helper
+
+
+WINDOWS = os.name == 'nt'
+APPLE = sys.platform in {"darwin", "ios", "tvos", "watchos"}
+AIX = sys.platform.startswith("aix")
+
+if WINDOWS:
+    SYSTEM_LIBRARY = 'KERNEL32.DLL'
+elif APPLE:
+    SYSTEM_LIBRARY = 'libSystem.B.dylib'
+elif AIX:
+    SYSTEM_LIBRARY = None
+else:
+    SYSTEM_LIBRARY = 'libc.so'
+
+class ListSharedLibraries(unittest.TestCase):
+
+    def test_lists_system(self):
+        dlls = dllist()
+
+        if SYSTEM_LIBRARY is not None:
+            self.assertIsNotNone(dlls)
+            self.assertGreater(len(dlls), 0, f'loaded={dlls}')
+            self.assertTrue(any(SYSTEM_LIBRARY in dll for dll in dlls), f'loaded={dlls}')
+        else:
+            # unsupported platform
+            self.assertIsNone(dlls)
+
+    def test_lists_updates(self):
+        dlls = dllist()
+
+        if dlls is not None:
+            if any("_ctypes_test" in dll for dll in dlls):
+                self.skipTest("Test library is already loaded")
+
+            _ctypes_test = import_helper.import_module("_ctypes_test")
+            test_module = CDLL(_ctypes_test.__file__)
+            dlls2 = dllist()
+            self.assertIsNotNone(dlls2)
+
+            dlls1 = set(dlls)
+            dlls2 = set(dlls2)
+            if test.support.verbose:
+                print("Newly loaded shared libraries:")
+                for dll in (dlls2 - dlls1):
+                    print("\t", dll)
+
+            self.assertGreater(dlls2, dlls1)
+            self.assertTrue(any("_ctypes_test" in dll for dll in dlls2))
+
+
+
+if __name__ == "__main__":
+    unittest.main()

Misc/ACKS

@@ -1990,6 +1990,7 @@ Edward C Wang
 Jiahua Wang
 Ke Wang
 Liang-Bo Wang
+Brian Ward
 Greg Ward
 Tom Wardill
 Zachary Ware

Misc/NEWS.d/next/Library/2024-08-12-11-58-15.gh-issue-119349.-xTnHl.rst

@@ -0,0 +1,2 @@
+Added the :func:`ctypes.util.dllist` function to list the loaded shared
+libraries for the current process.