diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 0b3ad4573f5fcf..98200093e15e19 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1524,6 +1524,17 @@ way is to instantiate :py:class:`CDLL` or one of its subclasses: copy, and the function :func:`ctypes.set_errno` changes the ctypes private copy to a new value and returns the former value. + .. note:: + + On some platforms (notably Linux), loading a library by absolute path (e.g. + ``CDLL('/lib/libc.so.6')``) may cause ``use_errno=True`` to malfunction. + If the absolute path resolves to a different :manpage:`dlopen(3)` instance + of the library than the one already linked into the process, the two + instances have *separate* :data:`errno` variables and ctypes will swap the + wrong one. To avoid this, load the library by its unqualified name (e.g. + ``CDLL('libc.so.6')``) or use :func:`!find_library` to obtain a name that + the linker can resolve to the already-loaded instance. + The *use_last_error* parameter, when set to true, enables the same mechanism for the Windows error code which is managed by the :func:`GetLastError` and :func:`!SetLastError` Windows API functions; :func:`ctypes.get_last_error` and diff --git a/Misc/NEWS.d/next/Documentation/2026-03-26-00-00-00.gh-issue-52008.y2n4w9.rst b/Misc/NEWS.d/next/Documentation/2026-03-26-00-00-00.gh-issue-52008.y2n4w9.rst new file mode 100644 index 00000000000000..f055f23981e0aa --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-03-26-00-00-00.gh-issue-52008.y2n4w9.rst @@ -0,0 +1,4 @@ +Add a note to :class:`ctypes.CDLL` documenting that loading a shared library +via an absolute path can silently break ``use_errno=True`` on Linux, because +:manpage:`dlopen(3)` may return a separate library instance with its own +:data:`errno` variable.