Namespaces and inter-library private symbols

[ghudson@MIT.EDU]

I'd like to get a consensus on how we should handle library functions
which are not part of the public API but are used by other parts of
the tree.  Currently, we inconsistently do one of three things:

1. Use the accessor.  (Examples: ASN.1 encoders as used by the pkinit
module; HMAC as used by gss-krb5.)

2. Name the function krb5_foo, export it, but prototype it in k5-int.h
instead of krb5.h.  (Examples: krb5_get_cred_from_kdc as used by ksu;
krb5_free_realm_tree as used by kdc.)

3. Name the function krb5int_foo, export it, prototype it in k5-int.h,
and use it directly from the other part of the tree.  (Examples:
krb5int_cc_default as used by gss-krb5; krb5int_init_context_kdc as
used by kdc and libkadm5.)

I would like to better understand why we have the accessor and when it
should be used, if ever.  I consider it an overly heavyweight solution
to the problem.  Tom tells me that the initial justification had
something to do with Windows, but he didn't have details.

I think we have a partial consensus that (2) is bad, because those
symbols can show up as available in an autoconf test even if they
aren't part of the API in that version of Kerberos.  We've continued
to add new examples of (2) in recent work, however--examples are
krb5_c_weak_enctype (recently renamed to krb5int_c_weak enctype) and
krb5_get_credentials_for_proxy.

I would like to see us move towards using (3) uniformly.  If I receive
no feedback, I will document this as the preferred practice in
http://k5wiki.kerberos.org/wiki/Coding_style/Practices#Namespaces and
start converting cases to that form as I run into them.

A fourth option is to invent a new namespace for inter-library private
symbols, so that we can easily differentiate between "internal to this
library" and "internal to the krb5 tree."  That might result in a lot
of symbol renaming over time, though.