@@ -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
201191On Windows, :mod: `!ctypes ` uses win32 structured exception handling to prevent
202192crashes 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+
587591If you have defined your own classes which you pass to function calls, you have
588592to implement a :meth: `~_CData.from_param ` class method for them to be able to use them
589593in 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