manpage

git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@10137 ec53bebd-3082-4978-b11e-865c3cabbd6b

lib/krb5/krb5_principal_get_realm.3

@@ -0,0 +1,48 @@
+.\" Copyright (c) 2001 Kungliga Tekniska H<>gskolan
+.\" $Id$
+.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