Skip to content

Commit 0781f7e

Browse files
[3.14] gh-82439: Clarify the behavior of argtypes under different calling conventions (GH-160065) (GH-160073)
(cherry picked from commit 874736e) Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
1 parent 1a80008 commit 0781f7e

1 file changed

Lines changed: 26 additions & 21 deletions

File tree

‎Doc/library/ctypes.rst‎

Lines changed: 26 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -180,23 +180,13 @@ handle (passing ``None`` as single argument to call it with a ``NULL`` pointer):
180180
0x1d000000
181181
>>>
182182

183-
:exc:`ValueError` is raised when you call an ``stdcall`` function with the
184-
``cdecl`` calling convention, or vice versa::
185-
186-
>>> cdll.kernel32.GetModuleHandleA(None) # doctest: +WINDOWS
187-
Traceback (most recent call last):
188-
File "<stdin>", line 1, in <module>
189-
ValueError: Procedure probably called with not enough arguments (4 bytes missing)
190-
>>>
191-
192-
>>> windll.msvcrt.printf(b"spam") # doctest: +WINDOWS
193-
Traceback (most recent call last):
194-
File "<stdin>", line 1, in <module>
195-
ValueError: Procedure probably called with too many arguments (4 bytes in excess)
196-
>>>
197-
198-
To find out the correct calling convention you have to look into the C header
199-
file or the documentation for the function you want to call.
183+
:mod:`!ctypes` cannot determine a function's calling convention or signature.
184+
Consult the function's C header file or documentation to choose the correct calling
185+
convention and set the :attr:`~_CFuncPtr.argtypes` attribute, as described in
186+
:ref:`ctypes-specifying-required-argument-types`. Without
187+
:attr:`~_CFuncPtr.argtypes`, the number of arguments is not checked. Calling a
188+
function with an incorrect calling convention or with incorrect arguments can
189+
corrupt memory or crash Python.
200190

201191
On Windows, :mod:`!ctypes` uses win32 structured exception handling to prevent
202192
crashes from general protection faults when functions are called with invalid
@@ -584,6 +574,20 @@ prototype for a C function), and tries to convert the arguments to valid types::
584574
13
585575
>>>
586576

577+
Setting :attr:`~_CFuncPtr.argtypes` also causes :mod:`!ctypes` to raise
578+
:exc:`TypeError` if too few arguments are passed::
579+
580+
>>> printf(b"%s %d %f\n", b"X", 2)
581+
Traceback (most recent call last):
582+
File "<stdin>", line 1, in <module>
583+
TypeError: this function takes at least 4 arguments (3 given)
584+
585+
Functions using the ``stdcall`` calling convention require exactly as many
586+
arguments as there are items in :attr:`~_CFuncPtr.argtypes`. Functions using
587+
the ``cdecl`` calling convention accept additional arguments, to support
588+
variadic functions. The declaration must match the function's actual signature;
589+
ctypes cannot verify this.
590+
587591
If you have defined your own classes which you pass to function calls, you have
588592
to implement a :meth:`~_CData.from_param` class method for them to be able to use them
589593
in the :attr:`~_CFuncPtr.argtypes` sequence. The :meth:`~_CData.from_param` class method receives
@@ -1875,10 +1879,11 @@ in :mod:`!ctypes`) which inherits from the private :class:`_CFuncPtr` class:
18751879
.. attribute:: argtypes
18761880

18771881
Assign a tuple of ctypes types to specify the argument types that the
1878-
function accepts. Functions using the ``stdcall`` calling convention can
1879-
only be called with the same number of arguments as the length of this
1880-
tuple; functions using the C calling convention accept additional,
1881-
unspecified arguments as well.
1882+
function accepts. :exc:`TypeError` is raised if the function is called
1883+
with fewer arguments than the length of this tuple. Functions using the
1884+
``stdcall`` calling convention also raise :exc:`TypeError` if called with
1885+
more arguments; functions using the ``cdecl`` calling convention accept
1886+
additional, unspecified arguments as well.
18821887

18831888
When a foreign function is called, each actual argument is passed to the
18841889
:meth:`~_CData.from_param` class method of the items in the :attr:`argtypes`

0 commit comments

Comments
 (0)