Reorganized some sections

Added missing functions

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

3 files changed, 547 insertions, 357 deletions

diff --git a/doc/api/ChangeLog b/doc/api/ChangeLog
index 9347f0c6fe..dfc124b5e0 100644
--- a/doc/api/ChangeLog
+++ b/doc/api/ChangeLog
@@ -1,7 +1,14 @@
+Thu May  4 14:29:45 1995  Ezra Peisach  <epeisach@kangaroo.mit.edu>
+
+	* krb5.tex: Reorganized into subsubsections. Added principal
+		access macros. 
+
+	* libos.tex: Added missing functions (os_context) and reorganized
+		into subsubsections. 
+
 Wed May  3 01:22:11 1995  Ezra Peisach  <epeisach@kangaroo.mit.edu>
 
-	* krb5.tex (subsubsection{The krb5_auth_context}): Added
-	auth_context routines. 
+	* krb5.tex: Added auth_context routines. 
 
 	* free.tex: Add krb5_xfree and krb5_free_data.
 
diff --git a/doc/api/krb5.tex b/doc/api/krb5.tex
index ca77091055..89f89dc4d2 100644
--- a/doc/api/krb5.tex
+++ b/doc/api/krb5.tex
@@ -277,6 +277,274 @@ Sets the replay cache that is used by the authentication routines to \funcparam{
 %% krb5_auth_con_getcksumtype, krb5_auth_con_getivector,
 %% krb5_auth_con_getrcache. -- Ezra
 
+\subsubsection{Principal access functions}
+
+Principals define a uniquely named client or server instance that
+participates in a network communication. The following functions allow
+one to create, modify and access portions of the
+\datatype{krb5_principal}. 
+
+Other functions found in orther portions of the manual include
+\funcname{krb5_sname_to_principal}, \funcname{krb5_free_principal}, 
+
+While it is possible to directly access the data structure in the
+structure, it is recommended that the functions be used. 
+
+\begin{funcdecl}{krb5_parse_name}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{const char *}{name}
+\funcout
+\funcarg{krb5_principal *}{principal}
+\end{funcdecl}
+
+Converts a single-string representation \funcparam{name} of the
+principal name to the multi-part principal format used in the protocols.
+
+A single-string representation of a Kerberos name consists of one or
+more principal name components, separated by slashes, optionally
+followed by the ``@'' character and a realm name.  If the realm name
+is not specified, the local realm is used.
+
+The slash and ``@'' characters may be quoted (i.e., included as part
+of a component rather than as a component separator or realm prefix)
+by preceding them with a backslash (``$\backslash$'') character.
+Similarly, newline, tab, backspace, and null characters may be
+included in a component by using $\backslash{}n$, $\backslash{}t$,
+$\backslash{}b$ or $\backslash{}0$, respectively.
+
+The realm in a Kerberos name may not contain the slash, colon or null
+characters.
+
+\funcparam{*principal} will point to allocated storage which should be freed by
+the caller (using \funcname{krb5_free_principal}) after use.
+
+\funcname{krb5_parse_name} returns KRB5_PARSE_MALFORMED if the string is
+ badly formatted, or ENOMEM if space for the return value can't be
+allocated.
+
+\begin{funcdecl}{krb5_unparse_name}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{krb5_const_principal}{principal}
+\funcout
+\funcarg{char **}{name}
+\end{funcdecl}
+
+Converts the multi-part principal name \funcparam{principal} from the
+format used in the protocols to a single-string representation of the
+name.  The resulting single-string representation will use the format
+and quoting conventions described for \funcname{krb5_parse_name}
+above.
+
+\funcparam{*name} points to allocated storage and should be freed by the caller
+when finished.
+
+\funcname{krb5_unparse_name} returns {\sc KRB_PARSE_MALFORMED} if the principal
+does not contain at least 2 components, and system errors ({\sc ENOMEM} if
+unable to allocate memory).
+
+\begin{funcdecl}{krb5_unparse_name_ext}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{krb5_const_principal}{principal}
+\funcinout
+\funcarg{char **}{name}
+\funcarg{int *}{size}
+\end{funcdecl}
+
+\funcname{krb5_unparse_name_ext} is designed for applications which
+must unparse a large number of principals, and are concerned about the
+speed impact of needing to do a lot of memory allocations and
+deallocations.  It functions similarly to \funcname{krb5_unparse_name}
+except if \funcparam{*name} is non-null, in which case, it is assumed
+to contain an allocated buffer of size \funcparam{*size} and this
+buffer will be resized with \funcname{realloc} to hold the unparsed
+name.  Note that in this case,
+\funcparam{size} must not be null.  
+
+If \funcparam{size} is non-null (whether or not \funcparam{*name} is
+null when the function is called), it will be filled in with the size
+of the unparsed name upon successful return.
+
+\begin{funcdecl}{krb5_princ_realm}{krb5_data}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\end{funcdecl}
+
+A macro which returns the realm of \funcparam{principal}.
+
+\begin{funcdecl}{krb5_princ_set_realm}{void}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\funcparam{krb5_data *}{realm}
+\end{funcdecl}
+
+A macro which returns sets the realm of \funcparam{principal} to
+\funcparam{realm}. 
+
+\begin{funcdecl}{krb5_princ_set_realm_data}{void}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\funcparam{char *}{data}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which returns sets the data portion of the realm of
+\funcparam{principal} to \funcparam{data}. 
+
+\begin{funcdecl}{krb5_princ_set_realm_length}{void}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\funcparam{int}{length}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which returns sets the length \funcparam{principal} to
+\funcparam{length}. 
+
+\begin{funcdecl}{krb5_princ_size}{void}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which gives the number of elements in the principal.
+May also be used on the left size of an assignment.
+
+\begin{funcdecl}{krb5_princ_type}{void}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which gives the type of the principal.
+May also be used on the left size of an assignment.
+
+\begin{funcdecl}{krb5_princ_data}{}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which gives the pointer to data portion of the principal.
+May also be used on the left size of an assignment.
+
+
+\begin{funcdecl}{krb5_princ_component}{}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\funcparam{int}{i}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which gives the pointer to ith element of the principal.
+May also be used on the left size of an assignment.
+
+\begin{funcdecl}{krb5_build_principal}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcout
+\funcarg{krb5_principal *}{princ}
+\funcin
+\funcarg{int}{rlen}
+\funcarg{const char *}{realm}
+\funcarg{char}{*s1, *s2, ..., 0}
+\end{funcdecl}
+\begin{funcdecl}{krb5_build_principal_va}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcout
+\funcarg{krb5_principal *}{princ}
+\funcin
+\funcarg{int}{rlen}
+\funcarg{const char *}{realm}
+\funcarg{va_list}{ap}
+\end{funcdecl}
+
+\begin{sloppypar}
+\funcname{krb5_build_principal} and
+\funcname{krb5_build_principal_va} 
+perform the same function; the former takes variadic arguments, while
+the latter takes a pre-computed varargs pointer.
+\end{sloppypar}
+
+Both functions take a realm name \funcparam{realm}, realm name length
+\funcparam{rlen}, and a list of null-terminated strings, and fill in a
+pointer to a principal structure \funcparam{princ}, making it point to a
+structure representing the named principal.
+The last string must be followed in the argument list by a null pointer.
+
+
+\begin{funcdecl}{krb5_build_principal_ext}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcout
+\funcarg{krb5_principal *}{princ}
+\funcin
+\funcarg{int}{rlen}
+\funcarg{const char *}{realm}
+\funcarg{}{int len1, char *s1, int len2, char *s2, ..., 0}
+\end{funcdecl}
+
+\funcname{krb5_build_principal_ext} is similar to
+\funcname{krb5_build_principal} but it takes its components as a list of
+(length, contents) pairs rather than a list of null-terminated strings.
+A length of zero indicates the end of the list.
+
+\begin{funcdecl}{krb5_copy_principal}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{krb5_const_principal}{inprinc}
+\funcout
+\funcarg{krb5_principal *}{outprinc}
+\end{funcdecl}
+
+Copy a principal structure, filling in \funcparam{*outprinc} to point to
+the newly allocated copy, which should be freed with
+\funcname{krb5_free_principal}.
+
+\begin{funcdecl}{krb5_principal_compare}{krb5_boolean}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{krb5_const_principal}{princ1}
+\funcarg{krb5_const_principal}{princ2}
+\end{funcdecl}
+
+If the two principals are the same, return TRUE, else return FALSE.
+
+\begin{funcdecl}{krb5_realm_compare}{krb5_boolean}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{krb5_const_principal}{princ1}
+\funcarg{krb5_const_principal}{princ2}
+\end{funcdecl}
+
+If the realms of the two principals are the same, return TRUE, else
+return FALSE. 
+
+
+\begin{funcdecl}{krb5_425_conv_principal}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{const char *}{name}
+\funcarg{const char *}{instance}
+\funcarg{const char *}{realm}
+\funcout
+\funcarg{krb5_principal *}{princ}
+\end{funcdecl}
+
+Build a principal \funcparam{princ} from a V4 specification made up of 
+\funcparam{name}.\funcparam{instance}@\funcparam{realm}. The routine is
+site-customized to convert the V4 naming scheme to a V5 one. For
+instance, the V4 ``rcmd'' is changed to ``host''. 
+
+The returned principal should be freed with
+\funcname{krb5_free_principal}. 
+
 \subsubsection{The application functions}
 
 \begin{funcdecl}{krb5_encode_kdc_rep}{krb5_error_code}{\funcin}
@@ -1350,131 +1618,6 @@ The \funcparam{auth_context} flags specify whether timestamps
 
 Returns system errors, integrity errors.
 
-\begin{funcdecl}{krb5_parse_name}{krb5_error_code}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcin
-\funcarg{const char *}{name}
-\funcout
-\funcarg{krb5_principal *}{principal}
-\end{funcdecl}
-
-Converts a single-string representation \funcparam{name} of the
-principal name to the multi-part principal format used in the protocols.
-
-A single-string representation of a Kerberos name consists of one or
-more principal name components, separated by slashes, optionally
-followed by the ``@'' character and a realm name.  If the realm name
-is not specified, the local realm is used.
-
-The slash and ``@'' characters may be quoted (i.e., included as part
-of a component rather than as a component separator or realm prefix)
-by preceding them with a backslash (``$\backslash$'') character.
-Similarly, newline, tab, backspace, and null characters may be
-included in a component by using $\backslash{}n$, $\backslash{}t$,
-$\backslash{}b$ or $\backslash{}0$, respectively.
-
-The realm in a Kerberos name may not contain the slash, colon or null
-characters.
-
-\funcparam{*principal} will point to allocated storage which should be freed by
-the caller (using \funcname{krb5_free_principal}) after use.
-
-\funcname{krb5_parse_name} returns KRB5_PARSE_MALFORMED if the string is
- badly formatted, or ENOMEM if space for the return value can't be
-allocated.
-
-\begin{funcdecl}{krb5_unparse_name}{krb5_error_code}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcin
-\funcarg{krb5_const_principal}{principal}
-\funcout
-\funcarg{char **}{name}
-\end{funcdecl}
-
-Converts the multi-part principal name \funcparam{principal} from the
-format used in the protocols to a single-string representation of the
-name.  The resulting single-string representation will use the format
-and quoting conventions described for \funcname{krb5_parse_name}
-above.
-
-\funcparam{*name} points to allocated storage and should be freed by the caller
-when finished.
-
-\funcname{krb5_unparse_name} returns {\sc KRB_PARSE_MALFORMED} if the principal
-does not contain at least 2 components, and system errors ({\sc ENOMEM} if
-unable to allocate memory).
-
-\begin{funcdecl}{krb5_unparse_name_ext}{krb5_error_code}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcin
-\funcarg{krb5_const_principal}{principal}
-\funcinout
-\funcarg{char **}{name}
-\funcarg{int *}{size}
-\end{funcdecl}
-
-\funcname{krb5_unparse_name_ext} is designed for applications which
-must unparse a large number of principals, and are concerned about the
-speed impact of needing to do a lot of memory allocations and
-deallocations.  It functions similarly to \funcname{krb5_unparse_name}
-except if \funcparam{*name} is non-null, in which case, it is assumed
-to contain an allocated buffer of size \funcparam{*size} and this
-buffer will be resized with \funcname{realloc} to hold the unparsed
-name.  Note that in this case,
-\funcparam{size} must not be null.  
-
-If \funcparam{size} is non-null (whether or not \funcparam{*name} is
-null when the function is called), it will be filled in with the size
-of the unparsed name upon successful return.
-
-\begin{funcdecl}{krb5_build_principal}{krb5_error_code}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcout
-\funcarg{krb5_principal *}{princ}
-\funcin
-\funcarg{int}{rlen}
-\funcarg{const char *}{realm}
-\funcarg{char}{*s1, *s2, ..., 0}
-\end{funcdecl}
-\begin{funcdecl}{krb5_build_principal_va}{krb5_error_code}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcout
-\funcarg{krb5_principal *}{princ}
-\funcin
-\funcarg{int}{rlen}
-\funcarg{const char *}{realm}
-\funcarg{va_list}{ap}
-\end{funcdecl}
-
-\begin{sloppypar}
-\funcname{krb5_build_principal} and
-\funcname{krb5_build_principal_va} 
-perform the same function; the former takes variadic arguments, while
-the latter takes a pre-computed varargs pointer.
-\end{sloppypar}
-
-Both functions take a realm name \funcparam{realm}, realm name length
-\funcparam{rlen}, and a list of null-terminated strings, and fill in a
-pointer to a principal structure \funcparam{princ}, making it point to a
-structure representing the named principal.
-The last string must be followed in the argument list by a null pointer.
-
-
-\begin{funcdecl}{krb5_build_principal_ext}{krb5_error_code}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcout
-\funcarg{krb5_principal *}{princ}
-\funcin
-\funcarg{int}{rlen}
-\funcarg{const char *}{realm}
-\funcarg{}{int len1, char *s1, int len2, char *s2, ..., 0}
-\end{funcdecl}
-
-\funcname{krb5_build_principal_ext} is similar to
-\funcname{krb5_build_principal} but it takes its components as a list of
-(length, contents) pairs rather than a list of null-terminated strings.
-A length of zero indicates the end of the list.
-
 \begin{funcdecl}{krb5_address_search}{krb5_boolean}{\funcinout}
 \funcarg{krb5_context}{context}
 \funcin
@@ -1494,15 +1637,6 @@ If \funcparam{addr} is listed in \funcparam{addrlist}, or
 
 If the two addresses are the same, return TRUE, else return FALSE.
 
-\begin{funcdecl}{krb5_principal_compare}{krb5_boolean}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcin
-\funcarg{krb5_const_principal}{princ1}
-\funcarg{krb5_const_principal}{princ2}
-\end{funcdecl}
-
-If the two principals are the same, return TRUE, else return FALSE.
-
 \begin{funcdecl}{krb5_fulladdr_order}{int}{\funcinout}
 \funcarg{krb5_context}{context}
 \funcin
@@ -1617,18 +1751,6 @@ to the newly allocated copy, which should be freed with
 Copy a data structure, filling in \funcparam{*outdata} to point to the
 newly allocated copy, which should be freed with \funcname{krb5_free_data}.
 
-\begin{funcdecl}{krb5_copy_principal}{krb5_error_code}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcin
-\funcarg{krb5_const_principal}{inprinc}
-\funcout
-\funcarg{krb5_principal *}{outprinc}
-\end{funcdecl}
-
-Copy a principal structure, filling in \funcparam{*outprinc} to point to
-the newly allocated copy, which should be freed with
-\funcname{krb5_free_principal}.
-
 \begin{funcdecl}{krb5_copy_ticket}{krb5_error_code}{\funcinout}
 \funcarg{krb5_context}{context}
 \funcin
@@ -1642,17 +1764,6 @@ the newly allocated copy, which should be freed with
 \funcname{krb5_free_ticket}.
 
 
-\begin{funcdecl}{krb5_realm_compare}{krb5_boolean}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcin
-\funcarg{krb5_const_principal}{princ1}
-\funcarg{krb5_const_principal}{princ2}
-\end{funcdecl}
-
-If the realms of the two principals are the same, return TRUE, else
-return FALSE. 
-
-
 \begin{funcdecl}{krb5_get_server_rcache}{krb5_error_code}{\funcinout}
 \funcarg{krb5_context}{context}
 \funcin
diff --git a/doc/api/libos.tex b/doc/api/libos.tex
index 19a1c40bca..7b91631e4c 100644
--- a/doc/api/libos.tex
+++ b/doc/api/libos.tex
@@ -29,38 +29,145 @@ for password reading.
 
 \end{description}
 
-\begin{funcdecl}{krb5_read_password}{krb5_error_code}{\funcin}
+\subsubsection{Operating specific context}
+The \datatype{krb5_context} has space for operating system specific
+data. These functions are called from \funcname{krb5_init_context} and
+\funcname{krb5_free_context}, but are included here for completeness.
+
+\begin{funcdecl}{krb5_os_init_context}{krb5_error_code}{\funcinout}
 \funcarg{krb5_context}{context}
-\funcarg{char *}{prompt}
-\funcarg{char *}{prompt2}
+\end{funcdecl}
+
+\internalfunc
+
+Initializes \funcparam{context{\ptsto}os_context} and establishes the
+location of the initial configuration files. 
+
+\begin{funcdecl}{krb5_os_free_context}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\end{funcdecl}
+
+\internalfunc
+
+Frees the operating system specific portion of \funcparam{context}. 
+
+\subsubsection{Configuration based functions}
+These functions allow access to configuration specific information. In
+some cases, the configuration may be overriden by program control.
+
+
+\begin{funcdecl}{krb5_set_config_files}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{const char **}{filenames}
+\end{funcdecl}
+
+Sets the list of configuration files to be examined in determining
+machine defaults. \funcparam{filenames} is an array of files to check in
+order. The array must have a NULL entry as the last element.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_get_krbhst}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{const krb5_data *}{realm}
 \funcout
-\funcarg{char *}{return_pwd}
-\funcinout
-\funcarg{int *}{size_return}
+\funcarg{char ***}{hostlist}
 \end{funcdecl}
 
-Read a password from the keyboard.  The first \funcparam{*size_return}
-bytes of the password entered are returned in \funcparam{return_pwd}.
-If fewer than \funcparam{*size_return} bytes are typed as a password,
-the remainder of \funcparam{return_pwd} is zeroed.  Upon success, the
-total number of bytes filled in is stored in \funcparam{*size_return}.
+Figures out the Kerberos server names for the given \funcparam{realm},
+filling in \funcparam{hostlist} with a null terminated array of
+pointers to hostnames. 
+ 
+If \funcparam{realm} is unknown, the filled-in pointer is set to NULL.
 
-\funcparam{prompt} is used as the prompt for the first reading of a password.
-It is printed to the terminal, and then a password is read from the
-keyboard.  No newline or spaces are emitted between the prompt and the
-cursor, unless the newline/space is included in the prompt.
+The pointer array and strings pointed to are all in allocated storage,
+and should be freed by the caller when finished.
 
-If \funcparam{prompt2} is a null pointer, then the password is read
-once.  If \funcparam{prompt2} is set, then it is used as a prompt to
-read another password in the same manner as described for
-\funcparam{prompt}.  After the second password is read, the two
-passwords are compared, and an error is returned if they are not
-identical.
+Returns system errors.
 
-Echoing is turned off when the password is read.
+\begin{funcdecl}{krb5_free_krbhst}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{char * const *}{hostlist}
+\end{funcdecl}
 
-If there is an error in reading or verifying the password, an error code
-is returned; else zero is returned.
+Frees the storage taken by a host list returned by \funcname{krb5_get_krbhst}.
+
+\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcout
+\funcarg{char **}{lrealm}
+\end{funcdecl}
+
+Retrieves the default realm to be used if no user-specified realm is
+available (e.g. to interpret a user-typed principal name with the
+realm omitted for convenience), filling in \funcparam{lrealm} with a
+pointer to the default realm in allocated storage.
+
+It is the caller's responsibility for freeing the allocated storage
+pointed to be \funcparam{lream} when it is finished with it.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_set_default_realm}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{char *}{realm}
+\end{funcdecl}
+
+Sets the default realm to be used if no user-specified realm is
+available (e.g. to interpret a user-typed principal name with the
+realm omitted for convenience). (c.f. krb5_get_default_realm)
+
+If \funcparam{realm} is NULL, then the operating system default value
+will used.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_get_host_realm}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{const char *}{host}
+\funcout
+\funcarg{char ***}{realmlist}
+\end{funcdecl}
+
+Figures out the Kerberos realm names for \funcparam{host}, filling in
+\funcparam{realmlist} with a
+pointer to an argv[] style list of names, terminated with a null pointer.
+ 
+If \funcparam{host} is NULL, the local host's realms are determined.
+
+If there are no known realms for the host, the filled-in pointer is set
+to NULL.
+
+The pointer array and strings pointed to are all in allocated storage,
+and should be freed by the caller when finished.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_free_host_realm}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{char * const *}{realmlist}
+\end{funcdecl}
+
+Frees the storage taken by a \funcparam{realmlist} returned by
+\funcname{krb5_get_local_realm}.
+
+\begin{funcdecl}{krb5_get_realm_domain}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{const char *}{realm}
+\funcout
+\funcarg{char **}{domain}
+\end{funcdecl}
+
+Determines the proper name of a realm. This is mainly so that a krb4
+principal can be converted properly into a krb5 one. If
+\funcparam{realm} is null, the function will assume the default realm of
+the host. The returned \funcparam{*domain} is allocated and must be
+freed by the caller. 
+
+\subsubsection{Disk based functions}
+These functions all relate to disk based I/O.
 
 \begin{funcdecl}{krb5_lock_file}{krb5_error_code}{\funcin}
 \funcarg{krb5_context}{context}
@@ -109,32 +216,62 @@ Assures that the changes made to the file pointed to by the file
 handle
 fp are forced out to disk.
 
-\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcin}
+\subsubsection{Network based routines}
+
+These routines send and receive network data the specifics 
+of addresses and families on a given operating system.
+
+\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\funcin}
 \funcarg{krb5_context}{context}
 \funcout
+\funcarg{krb5_address ***}{addr}
+\end{funcdecl}
+
+Return all the protocol addresses of this host.
+
+Compile-time configuration flags will indicate which protocol family
+addresses might be returned.
+\funcparam{*addr} is filled in to point to an array of address pointers,
+terminated by a null pointer.  All the storage pointed to is allocated
+and should be freed by the caller with \funcname{krb5_free_address}
+when no longer needed.
+
+\begin{funcdecl}{krb5_gen_portaddr}{krb5_error_code}{\funcin}
 \funcarg{krb5_context}{context}
-\funcarg{krb5_int32 *}{timeret}
+\funcarg{const krb5_address *}{adr}
+\funcarg{krb5_const_pointer}{ptr}
+\funcout
+\funcarg{krb5_address **}{outaddr}
 \end{funcdecl}
 
-Retrieves the system time of day, in seconds since the local system's
-epoch.
-[The ASN.1 encoding routines must convert this to the standard ASN.1
-encoding as needed]
+Given an address \funcparam{adr} and an additional address-type specific
+portion pointed to by
+\funcparam{port} this routine
+combines them into a freshly-allocated
+\datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} and fills in
+\funcparam{*outaddr} to point to this address.  For IP addresses,
+\funcparam{ptr} should point to a network-byte-order TCP or UDP port
+number.  Upon success, \funcparam{*outaddr} will point to an allocated
+address which should be freed with \funcname{krb5_free_address}.
 
-\begin{funcdecl}{krb5_us_timeofday}{krb5_error_code}{\funcin}
+
+\begin{funcdecl}{krb5_sendto_kdc}{krb5_error_code}{\funcin}
 \funcarg{krb5_context}{context}
+\funcarg{const krb5_data *}{send}
+\funcarg{const krb5_data *}{realm}
 \funcout
-\funcarg{krb5_int32 *}{seconds}
-\funcarg{krb5_int32 *}{microseconds}
+\funcarg{krb5_data *}{receive}
 \end{funcdecl}
 
-Retrieves the system time of day, in seconds since the local system's
-epoch.
-[The ASN.1 encoding routines must convert this to the standard ASN.1
-encoding as needed]
+Send the message \funcparam{send} to a KDC for realm \funcparam{realm} and
+return the response (if any) in \funcparam{receive}.
+
+If the message is sent and a response is received, 0 is returned,
+otherwise an error code is returned.
+
+The storage for \funcparam{receive} is allocated and should be freed by
+the caller when finished.
 
-{\raggedright The seconds portion is returned in \funcparam{*seconds}, the
-microseconds portion in \funcparam{*microseconds}.}
 
 \begin{funcdecl}{krb5_net_read}{int}{\funcin}
 \funcarg{krb5_context}{context}
@@ -183,63 +320,8 @@ using the network connection pointed to by \funcparam{fd}.
 Reads data from the network as a message, using the network connection
 pointed to by fd.
 
-\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcout
-\funcarg{krb5_address ***}{addr}
-\end{funcdecl}
-
-Return all the protocol addresses of this host.
-
-Compile-time configuration flags will indicate which protocol family
-addresses might be returned.
-\funcparam{*addr} is filled in to point to an array of address pointers,
-terminated by a null pointer.  All the storage pointed to is allocated
-and should be freed by the caller with \funcname{krb5_free_address}
-when no longer needed.
-
-
-\begin{funcdecl}{krb5_sendto_kdc}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{const krb5_data *}{send}
-\funcarg{const krb5_data *}{realm}
-\funcout
-\funcarg{krb5_data *}{receive}
-\end{funcdecl}
-
-Send the message \funcparam{send} to a KDC for realm \funcparam{realm} and
-return the response (if any) in \funcparam{receive}.
-
-If the message is sent and a response is received, 0 is returned,
-otherwise an error code is returned.
-
-The storage for \funcparam{receive} is allocated and should be freed by
-the caller when finished.
-
-\begin{funcdecl}{krb5_get_krbhst}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{const krb5_data *}{realm}
-\funcout
-\funcarg{char ***}{hostlist}
-\end{funcdecl}
-
-Figures out the Kerberos server names for the given \funcparam{realm},
-filling in \funcparam{hostlist} with a null terminated array of
-pointers to hostnames. 
- 
-If \funcparam{realm} is unknown, the filled-in pointer is set to NULL.
-
-The pointer array and strings pointed to are all in allocated storage,
-and should be freed by the caller when finished.
-
-Returns system errors.
-
-\begin{funcdecl}{krb5_free_krbhst}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{char * const *}{hostlist}
-\end{funcdecl}
-
-Frees the storage taken by a host list returned by \funcname{krb5_get_krbhst}.
+\subsubsection{Operating specific access functions}
+These functions are involved with access control decisions and policies.
 
 \begin{funcdecl}{krb5_aname_to_localname}{krb5_error_code}{\funcin}
 \funcarg{krb5_context}{context}
@@ -259,75 +341,122 @@ The translation will be null terminated in all non-error returns.
 
 Returns system errors.
 
-\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code}{\funcin}
+\begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{krb5_principal}{principal}
+\funcarg{const char *}{luser}
+\end{funcdecl}
+
+Given a Kerberos principal \funcparam{principal}, and a local username
+\funcparam{luser},
+determine whether user is authorized to login to the account \funcparam{luser}.
+Returns TRUE if authorized, FALSE if not authorized.
+
+\begin{funcdecl}{krb5_sname_to_principal}{krb5_error_code}{\funcin}
 \funcarg{krb5_context}{context}
+\funcarg{const char *}{hostname}
+\funcarg{const char *}{sname}
+\funcarg{krb5_int32}{type}
 \funcout
-\funcarg{char **}{lrealm}
+\funcarg{krb5_principal *}{ret_princ}
 \end{funcdecl}
 
-Retrieves the default realm to be used if no user-specified realm is
-available (e.g. to interpret a user-typed principal name with the
-realm omitted for convenience), filling in \funcparam{lrealm} with a
-pointer to the default realm in allocated storage.
+Given a hostname \funcparam{hostname} and a generic service name
+\funcparam{sname}, this function generates a full principal name to be
+used when authenticating with the named service on the host.  The full
+prinicpal name is  returned  in \funcparam{ret_princ}.
 
-It is the caller's responsibility for freeing the allocated storage
-pointed to be \funcparam{lream} when it is finished with it.
+The realm of the
+principal is determined internally by calling \funcname{krb5_get_host_realm}.
 
-Returns system errors.
+The \funcparam{type} argument controls how
+\funcname{krb5_sname_to_principal} generates the principal name,
+\funcparam{ret_princ}, for the named service, \funcparam{sname}.
+Currently, two values 	are supported: KRB5_NT_SRV_HOST, and
+KRB5_NT_UNKNOWN.  
 
-\begin{funcdecl}{krb5_set_default_realm}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{char *}{realm}
-\end{funcdecl}
+If \funcparam{type} is set to
+KRB5_NT_SRV_HOST, the hostname will be
+canonicalized, i.e. a fully qualified lowercase hostname using
+the primary name and the domain name, before \funcparam{ret_princ} is
+generated in the form
+"sname/hostname@LOCAL.REALM." Most applications should use
+KRB5_NT_SRV_HOST.  
 
-Sets the default realm to be used if no user-specified realm is
-available (e.g. to interpret a user-typed principal name with the
-realm omitted for convenience). (c.f. krb5_get_default_realm)
+However, if \funcparam{type} is set to KRB5_NT_UNKNOWN,
+while the generated principal name will have 	the form
+"sname/hostname@LOCAL.REALM" the hostname will not be canonicalized
+first.  It will appear exactly as it was passed in \funcparam{hostname}.  
 
-If \funcparam{realm} is NULL, then the operating system default value
-will used.
+The caller should release \funcparam{ret_princ}'s storage by calling
+\funcname{krb5_free_principal} when it is finished with the principal.
 
-Returns system errors.
 
-\begin{funcdecl}{krb5_get_host_realm}{krb5_error_code}{\funcin}
+
+\subsubsection{Miscellaneous operating specific functions}
+These functions handle the other operating specific functions that do
+not fall into any other major class.
+
+\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcin}
 \funcarg{krb5_context}{context}
-\funcarg{const char *}{host}
 \funcout
-\funcarg{char ***}{realmlist}
+\funcarg{krb5_context}{context}
+\funcarg{krb5_int32 *}{timeret}
 \end{funcdecl}
 
-Figures out the Kerberos realm names for \funcparam{host}, filling in
-\funcparam{realmlist} with a
-pointer to an argv[] style list of names, terminated with a null pointer.
- 
-If \funcparam{host} is NULL, the local host's realms are determined.
+Retrieves the system time of day, in seconds since the local system's
+epoch.
+[The ASN.1 encoding routines must convert this to the standard ASN.1
+encoding as needed]
 
-If there are no known realms for the host, the filled-in pointer is set
-to NULL.
+\begin{funcdecl}{krb5_us_timeofday}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcout
+\funcarg{krb5_int32 *}{seconds}
+\funcarg{krb5_int32 *}{microseconds}
+\end{funcdecl}
 
-The pointer array and strings pointed to are all in allocated storage,
-and should be freed by the caller when finished.
+Retrieves the system time of day, in seconds since the local system's
+epoch.
+[The ASN.1 encoding routines must convert this to the standard ASN.1
+encoding as needed]
 
-Returns system errors.
+{\raggedright The seconds portion is returned in \funcparam{*seconds}, the
+microseconds portion in \funcparam{*microseconds}.}
 
-\begin{funcdecl}{krb5_free_host_realm}{krb5_error_code}{\funcin}
+\begin{funcdecl}{krb5_read_password}{krb5_error_code}{\funcin}
 \funcarg{krb5_context}{context}
-\funcarg{char * const *}{realmlist}
+\funcarg{char *}{prompt}
+\funcarg{char *}{prompt2}
+\funcout
+\funcarg{char *}{return_pwd}
+\funcinout
+\funcarg{int *}{size_return}
 \end{funcdecl}
 
-Frees the storage taken by a \funcparam{realmlist} returned by
-\funcname{krb5_get_local_realm}.
+Read a password from the keyboard.  The first \funcparam{*size_return}
+bytes of the password entered are returned in \funcparam{return_pwd}.
+If fewer than \funcparam{*size_return} bytes are typed as a password,
+the remainder of \funcparam{return_pwd} is zeroed.  Upon success, the
+total number of bytes filled in is stored in \funcparam{*size_return}.
 
-\begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{krb5_principal}{principal}
-\funcarg{const char *}{luser}
-\end{funcdecl}
+\funcparam{prompt} is used as the prompt for the first reading of a password.
+It is printed to the terminal, and then a password is read from the
+keyboard.  No newline or spaces are emitted between the prompt and the
+cursor, unless the newline/space is included in the prompt.
+
+If \funcparam{prompt2} is a null pointer, then the password is read
+once.  If \funcparam{prompt2} is set, then it is used as a prompt to
+read another password in the same manner as described for
+\funcparam{prompt}.  After the second password is read, the two
+passwords are compared, and an error is returned if they are not
+identical.
+
+Echoing is turned off when the password is read.
+
+If there is an error in reading or verifying the password, an error code
+is returned; else zero is returned.
 
-Given a Kerberos principal \funcparam{principal}, and a local username
-\funcparam{luser},
-determine whether user is authorized to login to the account \funcparam{luser}.
-Returns TRUE if authorized, FALSE if not authorized.
 
 \begin{funcdecl}{krb5_random_confounder}{krb5_error_code}{\funcin}
 \funcarg{krb5_context}{context}
@@ -340,24 +469,6 @@ Given a length and a pointer, fills in the area pointed to by
 \funcparam{fillin} with \funcparam{size} random octets suitable for use
 in a confounder.
 
-\begin{funcdecl}{krb5_gen_portaddr}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{const krb5_address *}{adr}
-\funcarg{krb5_const_pointer}{ptr}
-\funcout
-\funcarg{krb5_address **}{outaddr}
-\end{funcdecl}
-
-Given an address \funcparam{adr} and an additional address-type specific
-portion pointed to by
-\funcparam{port} this routine
-combines them into a freshly-allocated
-\datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} and fills in
-\funcparam{*outaddr} to point to this address.  For IP addresses,
-\funcparam{ptr} should point to a network-byte-order TCP or UDP port
-number.  Upon success, \funcparam{*outaddr} will point to an allocated
-address which should be freed with \funcname{krb5_free_address}.
-
 \begin{funcdecl}{krb5_gen_replay_name}{krb5_error_code}{\funcin}
 \funcarg{krb5_context}{context}
 \funcarg{const krb5_address *}{inaddr}
@@ -380,42 +491,3 @@ finished using it.  When using IP addresses, the components in
 % outputs char * when krb5_get_server_rcache expects krb5_data''
 % (OpenVision Cambridge bug number 1582) causes the code of this
 % function to change, the documentation above will have to be updated.
-
-\begin{funcdecl}{krb5_sname_to_principal}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{const char *}{hostname}
-\funcarg{const char *}{sname}
-\funcarg{krb5_int32}{type}
-\funcout
-\funcarg{krb5_principal *}{ret_princ}
-\end{funcdecl}
-
-Given a hostname \funcparam{hostname} and a generic service name
-\funcparam{sname}, this function generates a full principal name to be
-used when authenticating with the named service on the host.  The full
-prinicpal name is  returned  in \funcparam{ret_princ}.
-
-The realm of the
-principal is determined internally by calling \funcname{krb5_get_host_realm}.
-
-The \funcparam{type} argument controls how
-\funcname{krb5_sname_to_principal} generates the principal name,
-\funcparam{ret_princ}, for the named service, \funcparam{sname}.
-Currently, two values 	are supported: KRB5_NT_SRV_HOST, and
-KRB5_NT_UNKNOWN.  
-
-If \funcparam{type} is set to
-KRB5_NT_SRV_HOST, the hostname will be
-canonicalized, i.e. a fully qualified lowercase hostname using
-the primary name and the domain name, before \funcparam{ret_princ} is
-generated in the form
-"sname/hostname@LOCAL.REALM." Most applications should use
-KRB5_NT_SRV_HOST.  
-
-However, if \funcparam{type} is set to KRB5_NT_UNKNOWN,
-while the generated principal name will have 	the form
-"sname/hostname@LOCAL.REALM" the hostname will not be canonicalized
-first.  It will appear exactly as it was passed in \funcparam{hostname}.  
-
-The caller should release \funcparam{ret_princ}'s storage by calling
-\funcname{krb5_free_principal} when it is finished with the principal.