crypto/heimdal/lib/krb5/krb5_build_principal.3

   1 .\" Copyright (c) 1997 Kungliga Tekniska Högskolan
   2 .\" $Id: krb5_build_principal.3,v 1.5 2002/08/28 15:30:47 joda Exp $
   3 .Dd August 8, 1997
   4 .Dt KRB5_BUILD_PRINCIPAL 3
   5 .Os HEIMDAL
   6 .Sh NAME
   7 .Nm krb5_build_principal ,
   8 .Nm krb5_build_principal_ext ,
   9 .Nm krb5_build_principal_va ,
  10 .Nm krb5_build_principal_va_ext ,
  11 .Nm krb5_make_principal
  12 .Nd principal creation functions
  13 .Sh LIBRARY
  14 Kerberos 5 Library (libkrb5, -lkrb5)
  15 .Sh SYNOPSIS
  16 .Fd #include <krb5.h>
  17 .Ft krb5_error_code
  18 .Fn krb5_build_principal "krb5_context context" "krb5_principal *principal" "int realm_len" "krb5_const_realm realm" "..."
  19 .Ft krb5_error_code
  20 .Fn krb5_build_principal_ext "krb5_context context" "krb5_principal *principal" "int realm_len" "krb5_const_realm realm" "..."
  21 .Ft krb5_error_code
  22 .Fn krb5_build_principal_va "krb5_context context" "krb5_principal *principal" "int realm_len" "krb5_const_realm realm" "va_list ap"
  23 .Ft krb5_error_code
  24 .Fn krb5_build_principal_va_ext "krb5_context context" "krb5_principal *principal" "int realm_len" "krb5_const_realm realm" "va_list ap"
  25 .Ft krb5_error_code
  26 .Fn krb5_make_principal "krb5_context context" "krb5_principal *principal" "krb5_const_realm realm" "..."
  27 .Sh DESCRIPTION
  28 These functions create a Kerberos 5 principal from a realm and a list
  29 of components.
  30 All of these functions return an allocated principal in the
  31 .Fa principal
  32 parameter, this should be freed with
  33 .Fn krb5_free_principal
  34 after use.
  35 .Pp
  36 The
  37 .Dq build
  38 functions take a
  39 .Fa realm
  40 and the length of the realm.  The
  41 .Fn krb5_build_principal
  42 and
  43 .Fn krb5_build_principal_va
  44 also takes a list of components (zero-terminated strings), terminated
  45 with
  46 .Dv NULL .
  47 The
  48 .Fn krb5_build_principal_ext
  49 and
  50 .Fn krb5_build_principal_va_ext
  51 takes a list of length-value pairs, the list is terminated with a zero
  52 length.
  53 .Pp
  54 The
  55 .Fn krb5_make_principal
  56 is a wrapper around
  57 .Fn krb5_build_principal .
  58 If the realm is
  59 .Dv NULL ,
  60 the default realm will be used.
  61 .Sh BUGS
  62 You can not have a NUL in a component. Until someone can give a good
  63 example of where it would be a good idea to have NUL's in a component,
  64 this will not be fixed.
  65 .Sh SEE ALSO
  66 .Xr krb5_425_conv_principal 3 ,
  67 .Xr krb5_free_principal 3 ,
  68 .Xr krb5_parse_name 3 ,
  69 .Xr krb5_sname_to_principal 3 ,
  70 .Xr krb5_unparse_name 3