1 files changed, 48 insertions, 0 deletions
diff --git a/crypto/heimdal/lib/krb5/krb5_principal_get_realm.3 b/crypto/heimdal/lib/krb5/krb5_principal_get_realm.3
new file mode 100644
index 0000000..07bffa4
--- /dev/null
+++ b/crypto/heimdal/lib/krb5/krb5_principal_get_realm.3
@@ -0,0 +1,48 @@
+.\" Copyright (c) 2001 Kungliga Tekniska Högskolan
+.\" $Id: krb5_principal_get_realm.3,v 1.2 2001/11/09 09:36:51 joda Exp $
+.Dd June 20, 2001
+.Dt KRB5_PRINCIPAL_GET_REALM 3
+.Os HEIMDAL
+.Sh NAME
+.Nm krb5_principal_get_realm ,
+.Nm krb5_principal_get_comp_string
+.Nd decompose a principal
+.Sh SYNOPSIS
+.Fd #include <krb5.h>
+.Ft "const char *"
+.Fn krb5_principal_get_realm "krb5_context context" "krb5_principal principal"
+.Ft "const char *"
+.Fn krb5_principal_get_comp_string "krb5_context context" "krb5_principal principal" "unsigned int component"
+.Sh DESCRIPTION
+These functions return parts of the
+.Fa principal ,
+either the realm or a specific component. The returned string points
+to data inside the principal, so they are valid only as long as the
+principal exists.
+.Pp
+The 
+.Fa component
+argument to
+.Fn krb5_principal_get_comp_string
+is the component number to return, from zero to the total number of
+components minus one. If a the requested component number is out of range, 
+.Dv NULL
+is returned.
+.Pp
+These functions can be seen as a replacement for the 
+.Fn krb5_princ_realm ,
+.Fn krb5_princ_component
+and related macros, described as intermal in the MIT API
+specification. A difference is that these functions return strings,
+not
+.Dv krb5_data .
+A reason to return 
+.Dv krb5_data 
+was that it was believed that principal components could contain
+binary data, but this belief was unfounded, and it has been decided
+that principal components are infact UTF8, so it's safe to use zero
+terminated strings.
+.Pp
+It's generally not necessary to look at the components of a principal.
+.Sh SEE ALSO
+.Xr krb5_unparse_name 3