crypto/heimdal/lib/krb5/krb5_krbhst_init.3

   1 .\" Copyright (c) 2001 Kungliga Tekniska Högskolan
   2 .\" $Id: krb5_krbhst_init.3,v 1.5 2002/08/28 15:30:54 joda Exp $
   3 .Dd June 17, 2001
   4 .Dt KRB5_KRBHST_INIT 3
   5 .Os HEIMDAL
   6 .Sh NAME
   7 .Nm krb5_krbhst_init ,
   8 .Nm krb5_krbhst_next ,
   9 .Nm krb5_krbhst_next_as_string ,
  10 .Nm krb5_krbhst_reset ,
  11 .Nm krb5_krbhst_free ,
  12 .Nm krb5_krbhst_format_string ,
  13 .Nm krb5_krbhst_get_addrinfo
  14 .Nd lookup Kerberos KDC hosts
  15 .Sh LIBRARY
  16 Kerberos 5 Library (libkrb5, -lkrb5)
  17 .Sh SYNOPSIS
  18 .Fd #include <krb5.h>
  19 .Ft krb5_error_code
  20 .Fn krb5_krbhst_init "krb5_context context" "const char *realm" "unsigned int type" "krb5_krbhst_handle *handle"
  21 .Ft krb5_error_code
  22 .Fn "krb5_krbhst_next" "krb5_context context" "krb5_krbhst_handle handle" "krb5_krbhst_info **host"
  23 .Ft krb5_error_code
  24 .Fn krb5_krbhst_next_as_string "krb5_context context" "krb5_krbhst_handle handle" "char *hostname" "size_t hostlen"
  25 .Ft void
  26 .Fn krb5_krbhst_reset "krb5_context context" "krb5_krbhst_handle handle"
  27 .Ft void
  28 .Fn krb5_krbhst_free "krb5_context context" "krb5_krbhst_handle handle"
  29 .Ft krb5_error_code
  30 .Fn krb5_krbhst_format_string "krb5_context context" "const krb5_krbhst_info *host" "char *hostname" "size_t hostlen"
  31 .Ft krb5_error_code
  32 .Fn krb5_krbhst_get_addrinfo "krb5_context context" "krb5_krbhst_info *host" "struct addrinfo **ai"
  33 .Sh DESCRIPTION
  34 These functions are used to sequence through all Kerberos hosts of a
  35 particular realm and service. The service type can be the KDCs, the
  36 administrative servers, the password changing servers, or the servers
  37 for Kerberos 4 ticket conversion.
  38 .Pp
  39 First a handle to a particular service is obtained by calling
  40 .Fn krb5_krbhst_init
  41 with the
  42 .Fa realm
  43 of interest and the type of service to lookup. The
  44 .Fa type
  45 can be one of:
  46 .Pp
  47 .Bl -hang -compact -offset indent
  48 .It KRB5_KRBHST_KDC
  49 .It KRB5_KRBHST_ADMIN
  50 .It KRB5_KRBHST_CHANGEPW
  51 .It KRB5_KRBHST_KRB524
  52 .El
  53 .Pp
  54 The
  55 .Fa handle
  56 is returned to the caller, and should be passed to the other
  57 functions.
  58 .Pp
  59 For each call to
  60 .Fn krb5_krbhst_next
  61 information a new host is returned. The former function returns in
  62 .Fa host
  63 a pointer to a structure containing information about the host, such
  64 as protocol, hostname, and port:
  65 .Bd -literal -offset indent
  66 typedef struct krb5_krbhst_info {
  67     enum { KRB5_KRBHST_UDP,
  68            KRB5_KRBHST_TCP,
  69            KRB5_KRBHST_HTTP } proto;
  70     unsigned short port;
  71     struct addrinfo *ai;
  72     struct krb5_krbhst_info *next;
  73     char hostname[1];
  74 } krb5_krbhst_info;
  75 .Ed
  76 .Pp
  77 The related function,
  78 .Fn krb5_krbhst_next_as_string ,
  79 return the same information as a url-like string.
  80 .Pp
  81 When there are no more hosts, these functions return
  82 .Dv KRB5_KDC_UNREACH .
  83 .Pp
  84 To re-iterate over all hosts, call
  85 .Fn krb5_krbhst_reset
  86 and the next call to
  87 .Fn krb5_krbhst_next
  88 will return the first host.
  89 .Pp
  90 When done with the handle,
  91 .Fn krb5_krbhst_free
  92 should be called.
  93 .Pp
  94 To use a
  95 .Va krb5_krbhst_info ,
  96 there are two functions:
  97 .Fn krb5_krbhst_format_string
  98 that will return a printable representation of that struct
  99 and
 100 .Fn krb5_krbhst_get_addrinfo
 101 that will return a
 102 .Va struct addrinfo
 103 that can then be used for communicating with the server mentioned.
 104 .Sh EXAMPLE
 105 The following code will print the KDCs of the realm
 106 .Dq MY.REALM .
 107 .Bd -literal -offset indent
 108 krb5_krbhst_handle handle;
 109 char host[MAXHOSTNAMELEN];
 110 krb5_krbhst_init(context, "MY.REALM", KRB5_KRBHST_KDC, &handle);
 111 while(krb5_krbhst_next_as_string(context, handle,
 112                                  host, sizeof(host)) == 0)
 113     printf("%s\\n", host);
 114 krb5_krbhst_free(context, handle);
 115 .Ed
 116 .\" .Sh BUGS
 117 .Sh HISTORY
 118 These functions first appeared in Heimdal 0.3g.
 119 .Sh SEE ALSO
 120 .Xr getaddrinfo 3 ,
 121 .Xr krb5_get_krbhst 3