Describe constants and the include files they should be in.

Explicitly mention that com_err can return non OVSEC_ error codes

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@2723 dc483132-0cff-0310-8789-dd5450dbe970

1 files changed, 27 insertions, 4 deletions

diff --git a/doc/kadm5/api-funcspec.tex b/doc/kadm5/api-funcspec.tex
index 248967612..c3427623a 100644
--- a/doc/kadm5/api-funcspec.tex
+++ b/doc/kadm5/api-funcspec.tex
@@ -71,7 +71,7 @@ going through the admin server.
 \subsection{Data Structures}
 
 This section describes the data structures used by the Admin API that
-are unique to \secure{}.
+are unique to \secure{}.  They are defined in ovsec_admin/admin.h.
 
 \subsubsection{Principals, ovsec_kadm_principal_ent_t}
 \label{sec:principal-structure}
@@ -343,6 +343,26 @@ REF_COUNT               & 0x080000 & pw_refcnt & O, 0 & O
 \label{tab:policy-bits}
 \end{table}
 
+\subsection{Constants}
+
+Several values are fixed and known through \#define's in include files.  
+
+These are defined in <ovsec_admin/admin.h>:
+
+\begin{description}
+\item[admin service principal] ADM_PRINCIPAL (``admin'')
+\item[admin history key] HIST_PRINCIPAL (``admin/history'')
+\item[server acl file path] ACLFILE (``/krb/ovsec_admin.acl'')
+\end{description}
+
+The location of the admin policy and principal databases are defined
+in <ovsec_admin/adb.h>:
+
+\begin{description}
+\item[admin policy database] POLICY_DB (``/krb5/policy.db'')
+\item[admin principal database] PRINCIPAL_DB (``/krb5/principal.db'')
+\end{description}
+
 \subsection{Error Codes}
 
 The error codes that can be returned by admin functions are listed
@@ -353,9 +373,12 @@ omitted from the list presented with each function.
 The admin system guarantees that a function that returns an error code
 has no other side effect.
 
-The Admin system will use \v{com_err} for error codes.  The error code
-table name will be ``kadm'', and the offsets will be the same as the
-order presented here.
+The Admin system will use \v{com_err} for error codes.  Note, this
+means that \v{com_err} codes may returned from functions that the
+admin routines call (e.g. the kerberos library). Callers should not
+expect that only OVSEC errors will be returned.  The Admin system
+error code table name will be ``kadm'', and the offsets will be the
+same as the order presented here.
 
 \begin{description}
 \item[* OVSEC_KADM_OK] Operation successful.