[Python-checkins] GH-92892: Add section about variadic functions to ctypes documentation (GH-99529)

[miss-islington]

https://github.com/python/cpython/commit/5252ad2b646ee7bbcccee86a42cf48bbb321a6e2
commit: 5252ad2b646ee7bbcccee86a42cf48bbb321a6e2
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-11-22T10:57:45-08:00
summary:

GH-92892: Add section about variadic functions to ctypes documentation (GH-99529)


On some platforms, and in particular macOS/arm64, the calling
convention for variadic arguments is different from the regular
calling convention. Add a section to the documentation to document
this.
(cherry picked from commit bc3a11d21ddef28047b18c0f6a5068fa9fb16da2)

Co-authored-by: Ronald Oussoren <ronaldoussoren at mac.com>

files:
A Misc/NEWS.d/next/Documentation/2022-11-16-12-52-23.gh-issue-92892.TS-P0j.rst
M Doc/library/ctypes.rst

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 9f8737b731ee..077a205695a5 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -373,6 +373,26 @@ that they can be converted to the required C data type::
    31
    >>>
 
+.. _ctypes-calling-variadic-functions:
+
+Calling varadic functions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On a lot of platforms calling variadic functions through ctypes is exactly the same
+as calling functions with a fixed number of parameters. On some platforms, and in
+particular ARM64 for Apple Platforms, the calling convention for variadic functions
+is different than that for regular functions.
+
+On those platforms it is required to specify the *argtypes* attribute for the
+regular, non-variadic, function arguments:
+
+.. code-block:: python3
+
+   libc.printf.argtypes = [ctypes.c_char_p]
+
+Because specifying the attribute does inhibit portability it is adviced to always
+specify ``argtypes`` for all variadic functions.
+
 
 .. _ctypes-calling-functions-with-own-custom-data-types:
 
diff --git a/Misc/NEWS.d/next/Documentation/2022-11-16-12-52-23.gh-issue-92892.TS-P0j.rst b/Misc/NEWS.d/next/Documentation/2022-11-16-12-52-23.gh-issue-92892.TS-P0j.rst
new file mode 100644
index 000000000000..54e421d19d9d
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-11-16-12-52-23.gh-issue-92892.TS-P0j.rst
@@ -0,0 +1 @@
+Document that calling variadic functions with ctypes requires special care on macOS/arm64 (and possibly other platforms).