api-funcspec.tex: update semantics for admin_dbname and admin_lockfile

so they always key off dbname

api-server-design.tex: add new osa_adb database functions: create_db,
destroy_db, rename_db

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

2 files changed, 38 insertions, 26 deletions

diff --git a/doc/kadm5/api-funcspec.tex b/doc/kadm5/api-funcspec.tex
index 91e7c02..a1cc798 100644
--- a/doc/kadm5/api-funcspec.tex
+++ b/doc/kadm5/api-funcspec.tex
@@ -391,7 +391,8 @@ typedef struct _kadm5_config_params {
 %
 The following list describes each of the fields of the structure,
 along with the profile relation it overrides, its mask value, its
-default value, and whether it is valid on the client, server, or both.
+default value, and whether it is valid on the client, server, or both,
+or neither.
 \begin{description}
 \item[mask] No variable.  No mask value.  A bitfield specifying which
 fields of the structure contain valid information.  A caller sets this
@@ -429,31 +430,13 @@ kadmind_port field, overriding any value of the kadmind_port variable.
 database name to use; the Kerberos database stores principal
 information.  The default is DEFAULT_KDB_FILE.
 
-\item[admin_dbname] Variable: admin_database_name.  ADBNAME.  Server.
-The administration database name to use; the administration database
-stores policy information.  If DBNAME is specified in the input
-parameters and ADBNAME is not, the admin_database_name variable is
-overridden and the field is set to the value of dbname followed by
-``.kadm5''.  The default, if DBNAME is not set and the variable is not
-defined, is also the value of dbname followed by ``.kadm5'', if dbname
-is set.  NOTE: The ADBNAME mask value is allowed to be set by callers
-{\it only} for testing purposes; it should {\it never} be set by
-normal clients, which instead should allow it to be derived from the
-database name.
+\item[admin_dbname] Variable: admin_database_name.  ADBNAME.
+Neither.  If the dbname field is set, this field is set to the value
+of dbname followed by ``.kadm5''.
 
 \item[admin_lockfile] Variable: admin_database_lockfile.
-ADB_LOCKFILE.  Server.  The administration database lock file name,
-used to lock the administration database.  If ADBNAME or DBNAME is
-specified in the input parameters and ADB_LOCKFILE is not, the
-admin_database_lockfile variable is overridden and the field is set to
-the value of admin_dbname followed by ``.lock'' (this depends on
-admin_dbname already being set based on DBNAME as described above).
-The default, if neither DBNAME nor ADBNAME is set in the input
-parameters and the variable is not defined, is admin_dbname followed
-by ``.lock'', if admin_dbname is set.  NOTE: The ADBNAME mask value is
-allowed to be set by callers {\it only} for testing purposes; it
-should {\it never} be set by normal clients, which instead should
-allow it to be derived from the database name.
+ADB_LOCKFILE.  Neither.  If the admin_dbname field is set, this field
+is set to the value of admin_dbname followed by ``.lock''.
 
 \item[acl_file] Variable: acl_file.  ACL_FILE.  Server.  The admin
 server's ACL file.  The default is DEFAULT_KADM5_ACL_FILE.
diff --git a/doc/kadm5/api-server-design.tex b/doc/kadm5/api-server-design.tex
index fd80c2e..2fed80a 100644
--- a/doc/kadm5/api-server-design.tex
+++ b/doc/kadm5/api-server-design.tex
@@ -705,12 +705,41 @@ the iteration function are undefined.
 \subsubsection{Function descriptions}
 
 \begin{verbatim}
+osa_adb_ret_t osa_adb_create_T_db(kadm5_config_params *params)
+\end{verbatim}
+%
+Create the database and lockfile specified in params.  The database
+must not already exist, or EEXIST is returned.  The lock file is only
+created after the database file has been created successfully.
+
+\begin{verbatim}
+osa_adb_ret_t osa_adb_rename_T_db(kadm5_config_params *fromparams,
+				  kadm5_config_params *toparams)
+\end{verbatim}
+%
+Rename the database named by fromparams to that named by toparams.
+Both databases and lock files must already exist.  When the function
+returns, the database named by fromparams no longer exists, and
+toparams has been overwritten with fromparams.  This function acquires
+a permanent lock on both databases for the duration of its operation,
+so a failure is likely to leave the databases unusable.
+
+\begin{verbatim}
+osa_adb_ret_t osa_adb_destroy_policy_db(kadm5_config_params *params)
+\end{verbatim}
+%
+Destroy the database named by params.  The database file and lock file
+are deleted.
+
+\begin{verbatim}
 osa_adb_ret_t
 osa_adb_open_T(osa_adb_T_t *db, char *filename);
 \end{verbatim}
 %
-Open the database named filename.  Returns OSA_ADB_FAILURE if it
-cannot open the database.
+Open the database named filename.  Returns OSA_ADB_NOLOCKFILE if the
+database does not exist or if the lock file is missing.  The database
+is not actually opened in the operating-system file sense until a lock
+is acquire.
 
 \begin{verbatim}
 osa_adb_ret_t