specify library names and locations. more include file references. Fix

typos in chpass_util description.

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

1 files changed, 29 insertions, 13 deletions

diff --git a/doc/kadm5/api-funcspec.tex b/doc/kadm5/api-funcspec.tex
index 57545699d..8a4052861 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{}.  They are defined in ovsec_admin/admin.h.
+are unique to \secure{}.  They are defined in $<$ovsec_admin/admin.h$>$.
 
 \subsubsection{Principals, ovsec_kadm_principal_ent_t}
 \label{sec:principal-structure}
@@ -294,7 +294,8 @@ specified.  The values for forbidden fields are defined in the
 function semantics.
 
 The masks for principals are in table \ref{tab:princ-bits} and the
-masks for policies are in table \ref{tab:policy-bits}.  The
+masks for policies are in table \ref{tab:policy-bits}.  They are
+defined in $<ovsec_admin/admin.h$>$. The
 OVSEC_KADM_ prefix has been removed from the Name fields.  In the
 Create and Modify fields, M means mandatory, F means forbidden, and O
 means optional.  Create fields that are optional specify the default
@@ -346,11 +347,17 @@ REF_COUNT               & 0x080000 & pw_refcnt & O, 0 & O
 \label{tab:policy-bits}
 \end{table}
 
-\subsection{Constants}
+\subsection{Constants, Header Files, Libraries}
 
-Several values are fixed and known through \#define's in include files.  
+For release 1.0 both all of the files decribed in this section are
+rooted off of the ``stage'' directory in the build tree.  If we export
+this interface in future releases they will move to the ``install''
+tree. Include files are found under ``stage/include'', libraries under
+``stage/lib''.
 
-These are defined in $<$ovsec_admin/admin.h$>$:
+$<$ovsec_admin/admin.h$>$ contains ovsec_kadm routine prototypes, data
+structures, mask bitfields defines, and the following name and
+location definitions:
 
 \begin{description}
 \item[admin service principal] ADM_PRINCIPAL (``ovsec_kadm/admin'')
@@ -359,6 +366,8 @@ These are defined in $<$ovsec_admin/admin.h$>$:
 \item[server acl file path] ACLFILE (``/krb/ovsec_admin.acl'')
 \end{description}
 
+OVSEC_KADM errors are described in $<$ovsec_admin/kadm_err.h$>$.
+
 The location of the admin policy and principal databases are defined
 in $<$ovsec_admin/adb.h$>$:
 
@@ -367,6 +376,11 @@ in $<$ovsec_admin/adb.h$>$:
 \item[admin principal database] PRINCIPAL_DB (``/krb5/principal.db'')
 \end{description}
 
+Client applications will link against libclient.a and server programs
+against libsrv.a. Right now both clients and servers also need to link
+against libcommon.a but we should put that in both libclient.a and
+libsrv.a to simplify the linking process.
+
 \subsection{Error Codes}
 
 The error codes that can be returned by admin functions are listed
@@ -382,7 +396,8 @@ 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.
+same as the order presented here. The error table include file will be
+$<$ovsec_admin/kadm_err.h$>$.
 
 \begin{description}
 \item[* OVSEC_KADM_OK] Operation successful.
@@ -863,13 +878,14 @@ described below. 1024 bytes is recommended.
 \begin{enumerate}
 \item If new_pw is NULL, this routine will prompt the user for
 ``New Password:'' and ``New Password (again):'' and read (without
-echoing) the password input. This will use krb5_read_password and only
-terminal-based applications will make use of this. If the passwords
-don't match the string ``New passwords do not match - password not
-changed.'' will be copied into msg_ret, and the error code
-KRB5_LIBOS_BADPWDMATCH will be returned.  For while reading the new
-password, copy the string ``<com_err message$>$ occurred while trying to
-change password.''  following by a blank line and ``Password not
+echoing) the password input. Since it is likely that this will simply
+call krb5_read_password only terminal-based applications will make use
+of the password reading functionality. If the passwords don't match
+the string ``New passwords do not match - password not changed.'' will
+be copied into msg_ret, and the error code KRB5_LIBOS_BADPWDMATCH will
+be returned.  For other errors that ocurr while reading the new
+password, copy the string ``<com_err message$>$ occurred while trying
+to read new password.''  followed by a blank line and ``Password not
 changed.'' into msg_ret and return the error code returned by
 krb5_read_password.