[libheimdal-kadm5-perl] 20/27: Add more comments to the library call patch

[Russ Allbery]

This is an automated email from the git hooks/post-receive script.

rra pushed a commit to branch master
in repository libheimdal-kadm5-perl.

commit 1f4d368de690799113c2f5b8579f2f7847d92c47
Author: Russ Allbery <eagle at eyrie.org>
Date:   Mon Dec 18 04:03:46 2017

    Add more comments to the library call patch
---
 debian/patches/fix-library-calls.patch | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/debian/patches/fix-library-calls.patch b/debian/patches/fix-library-calls.patch
index e960614..63e5866 100644
--- a/debian/patches/fix-library-calls.patch
+++ b/debian/patches/fix-library-calls.patch
@@ -1,6 +1,25 @@
-Description: Call the public API functions, not internal _c functions
+Description: Call the public kadm5 API functions instead of the internal ones
 Author: Russ Allbery <rra at debian.org>
 
+The kadm5_c_* functions are an internal API.  The public functions
+are the ones without the _c, which dispatch to the internal functions
+depending on whether one links with the client library or the server
+library.  By calling the _c functions, we don't get the benefit of
+prototype checking and fail if the internal function signature ever
+changes.
+
+The latter has now happened with Heimdal 1.6 currently used in Debian,
+and as a result the create_principal and chpass_principal functions
+here have stopped working because they provide the wrong number of
+arguments and the Heimdal library sees random stack garbage as the
+additional function arguments.
+
+Replace all C calls to use the versions without _c, since this module
+doesn't attempt to support the _s and _c interfaces simultaneously
+anyway and therefore no benefit accrues from calling the _c functions.
+This also fixes the backward-compatibility problem, since the public
+API did not change, only the internal function API.
+
 diff --git a/Kadm5.xs b/Kadm5.xs
 index f1312f8..8ee5d73 100644
 --- a/Kadm5.xs

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libheimdal-kadm5-perl.git