Skip to content

Commit a303722

Browse files
committed
gh-52008: document that absolute paths can break use_errno=True in ctypes
Loading a shared library via an absolute path (e.g. CDLL('/lib/libc.so.6')) can cause use_errno=True to silently malfunction on Linux because dlopen may return a separate library instance with its own errno variable. Add a note to the CDLL.use_errno parameter docs warning about this and recommending the use of an unqualified name or ctypes.util.find_library instead.
1 parent 36e4ffc commit a303722

File tree

1 file changed

+11
-0
lines changed

1 file changed

+11
-0
lines changed

Doc/library/ctypes.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1524,6 +1524,17 @@ way is to instantiate :py:class:`CDLL` or one of its subclasses:
15241524
copy, and the function :func:`ctypes.set_errno` changes the ctypes private copy
15251525
to a new value and returns the former value.
15261526

1527+
.. note::
1528+
1529+
On some platforms (notably Linux), loading a library by absolute path (e.g.
1530+
``CDLL('/lib/libc.so.6')``) may cause ``use_errno=True`` to malfunction.
1531+
If the absolute path resolves to a different :manpage:`dlopen(3)` instance
1532+
of the library than the one already linked into the process, the two
1533+
instances have *separate* :data:`errno` variables and ctypes will swap the
1534+
wrong one. To avoid this, load the library by its unqualified name (e.g.
1535+
``CDLL('libc.so.6')`` or use :func:`ctypes.util.find_library` to obtain
1536+
a name that the linker can resolve to the already-loaded instance.
1537+
15271538
The *use_last_error* parameter, when set to true, enables the same mechanism for
15281539
the Windows error code which is managed by the :func:`GetLastError` and
15291540
:func:`!SetLastError` Windows API functions; :func:`ctypes.get_last_error` and

0 commit comments

Comments
 (0)