Various documentation updates per reviews

Author: WardBrian

Doc/library/ctypes.rst

@@ -1419,6 +1419,15 @@ 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.
 
+The exact output of this function will be system dependent. On most platforms,
+the first entry of this list represents the current process itself, which may
+be an empty string.
+For example, on glibc-based Linux, the return may look like::
+
+   >>> from ctypes.util import dllist
+   >>> dllist()
+   ['', 'linux-vdso.so.1', '/lib/x86_64-linux-gnu/libm.so.6', '/lib/x86_64-linux-gnu/libc.so.6', ... ]
+
 .. _ctypes-loading-shared-libraries:
 
 Loading shared libraries
@@ -2108,7 +2117,7 @@ Utility functions
    executable file. It may be an empty string.
 
    .. availability:: Windows, macOS, iOS, glibc, BSD libc, musl
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 .. function:: FormatError([code])
 

Doc/whatsnew/3.14.rst

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

Lib/ctypes/util.py

@@ -67,11 +67,11 @@ def find_library(name):
                 return fname
         return None
 
-    import ctypes
-    from ctypes import wintypes
-
+    # Listing loaded DLLs on Windows relies on the following APIs:
     # https://learn.microsoft.com/windows/win32/api/psapi/nf-psapi-enumprocessmodules
     # https://learn.microsoft.com/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulefilenamew
+    import ctypes
+    from ctypes import wintypes
 
     _kernel32 = ctypes.WinDLL('kernel32', use_last_error=True)
     _get_current_process = _kernel32["GetCurrentProcess"]
@@ -120,6 +120,7 @@ def _get_module_handles():
                 return modules[:n]
 
     def dllist():
+        """Return a list of loaded shared libraries in the current process."""
         modules = _get_module_handles()
         libraries = [name for h in modules
                         if (name := _get_module_filename(h)) is not None]
@@ -138,14 +139,16 @@ def find_library(name):
                 continue
         return None
 
+    # Listing loaded libraries on Apple systems relies on the following API:
+    # https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/dyld.3.html
     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():
+        """Return a list of loaded shared libraries in the current process."""
         num_images = _libc._dyld_image_count()
         libraries = [os.fsdecode(name) for i in range(num_images)
                         if (name := _dyld_get_image_name(i)) is not None]
@@ -414,7 +417,9 @@ def find_library(name):
                    _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
+# Listing loaded libraries on other systems will try to use
+# functions common to Linux and a few other Unix-like systems.
+# See the following for several platforms' documentation of the same API:
 # 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
@@ -454,6 +459,7 @@ def _info_callback(info, _size, data):
         _dl_iterate_phdr.restype = ctypes.c_int
 
         def dllist():
+            """Return a list of loaded shared libraries in the current process."""
             libraries = []
             _dl_iterate_phdr(_info_callback,
                              ctypes.byref(ctypes.py_object(libraries)))

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

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