https://github.com/python/cpython/commit/b97f5e7556b9d9d4315a835d4101e6cd7ce006d7 commit: b97f5e7556b9d9d4315a835d4101e6cd7ce006d7 branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: ZeroIntensity <[email protected]> date: 2026-10-19T21:16:08Z summary:
[3.14] gh-112423: Clarify how to use `errcheck` for `ctypes` function pointers (GH-159776) (GH-159784) (cherry picked from commit 8b2a37361a227b813402fd98ca19f1a316bfe028) Co-authored-by: Peter Bierma <[email protected]> files: M Doc/library/ctypes.rst diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index a34a35e31d78e2..4568d7a8013813 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1908,13 +1908,33 @@ in :mod:`!ctypes`) which inherits from the private :class:`_CFuncPtr` class: same callable object to check or post process the results of several functions. - *arguments* is a tuple containing the parameters originally passed to - the function call, this allows specializing the behavior on the + *arguments* is a tuple containing the parameters passed to the + function call, including any output parameters that :mod:`!ctypes` + created for the call; this allows specializing the behavior on the arguments used. - The object that this function returns will be returned from the - foreign function call, but it can also check the result value - and raise an exception if the foreign function call failed. + If the callable returns the *arguments* tuple it received, unchanged, + :mod:`!ctypes` continues its normal processing of the result, which + includes returning output parameters (see + :ref:`ctypes-function-prototypes`). Any other object returned by the + callable is returned from the foreign function call instead. The + callable can also check the result value and raise an exception if the + foreign function call failed. + + For example, this callable raises an exception when the foreign function + signals failure with a negative return value, and otherwise leaves the + result to :mod:`!ctypes`:: + + def errcheck(result, func, arguments): + if result < 0: + raise RuntimeError(f"call failed with error {result}") + return arguments + + This one instead replaces the result, converting a C ``int`` used as a + boolean into a :class:`bool`:: + + def errcheck(result, func, arguments): + return result != 0 .. audit-event:: ctypes.set_exception code foreign-functions _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
