crypto/heimdal/lib/krb5/krb5_principal_get_realm.3

   1 .\" Copyright (c) 2001 Kungliga Tekniska Högskolan
   2 .\" $Id: krb5_principal_get_realm.3,v 1.4 2002/08/28 15:30:56 joda Exp $
   3 .Dd June 20, 2001
   4 .Dt KRB5_PRINCIPAL_GET_REALM 3
   5 .Os HEIMDAL
   6 .Sh NAME
   7 .Nm krb5_principal_get_realm ,
   8 .Nm krb5_principal_get_comp_string
   9 .Nd decompose a principal
  10 .Sh LIBRARY
  11 Kerberos 5 Library (libkrb5, -lkrb5)
  12 .Sh SYNOPSIS
  13 .Fd #include <krb5.h>
  14 .Ft "const char *"
  15 .Fn krb5_principal_get_realm "krb5_context context" "krb5_principal principal"
  16 .Ft "const char *"
  17 .Fn krb5_principal_get_comp_string "krb5_context context" "krb5_principal principal" "unsigned int component"
  18 .Sh DESCRIPTION
  19 These functions return parts of the
  20 .Fa principal ,
  21 either the realm or a specific component. The returned string points
  22 to data inside the principal, so they are valid only as long as the
  23 principal exists.
  24 .Pp
  25 The
  26 .Fa component
  27 argument to
  28 .Fn krb5_principal_get_comp_string
  29 is the component number to return, from zero to the total number of
  30 components minus one. If a the requested component number is out of range,
  31 .Dv NULL
  32 is returned.
  33 .Pp
  34 These functions can be seen as a replacement for the
  35 .Fn krb5_princ_realm ,
  36 .Fn krb5_princ_component
  37 and related macros, described as intermal in the MIT API
  38 specification. A difference is that these functions return strings,
  39 not
  40 .Dv krb5_data .
  41 A reason to return
  42 .Dv krb5_data
  43 was that it was believed that principal components could contain
  44 binary data, but this belief was unfounded, and it has been decided
  45 that principal components are infact UTF8, so it's safe to use zero
  46 terminated strings.
  47 .Pp
  48 It's generally not necessary to look at the components of a principal.
  49 .Sh SEE ALSO
  50 .Xr krb5_unparse_name 3