KRB5_KRBHST_INIT(3)        UNIX Programmer's Manual        KRB5_KRBHST_INIT(3)

NNAAMMEE
     kkrrbb55__kkrrbbhhsstt__iinniitt, kkrrbb55__kkrrbbhhsstt__nneexxtt, kkrrbb55__kkrrbbhhsstt__nneexxtt__aass__ssttrriinngg,
     kkrrbb55__kkrrbbhhsstt__rreesseett, kkrrbb55__kkrrbbhhsstt__ffrreeee, kkrrbb55__kkrrbbhhsstt__ffoorrmmaatt__ssttrriinngg,
     kkrrbb55__kkrrbbhhsstt__ggeett__aaddddrriinnffoo - lookup Kerberos KDC hosts

LLIIBBRRAARRYY
     Kerberos 5 Library (libkrb5, -lkrb5)

SSYYNNOOPPSSIISS
     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__kkrrbbhhsstt__iinniitt(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _c_o_n_s_t _c_h_a_r _*_r_e_a_l_m,
             _u_n_s_i_g_n_e_d _i_n_t _t_y_p_e, _k_r_b_5___k_r_b_h_s_t___h_a_n_d_l_e _*_h_a_n_d_l_e)

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__kkrrbbhhsstt__nneexxtt(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___k_r_b_h_s_t___h_a_n_d_l_e _h_a_n_d_l_e,
             _k_r_b_5___k_r_b_h_s_t___i_n_f_o _*_*_h_o_s_t)

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__kkrrbbhhsstt__nneexxtt__aass__ssttrriinngg(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
             _k_r_b_5___k_r_b_h_s_t___h_a_n_d_l_e _h_a_n_d_l_e, _c_h_a_r _*_h_o_s_t_n_a_m_e, _s_i_z_e___t _h_o_s_t_l_e_n)

     _v_o_i_d
     kkrrbb55__kkrrbbhhsstt__rreesseett(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___k_r_b_h_s_t___h_a_n_d_l_e _h_a_n_d_l_e)

     _v_o_i_d
     kkrrbb55__kkrrbbhhsstt__ffrreeee(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___k_r_b_h_s_t___h_a_n_d_l_e _h_a_n_d_l_e)

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__kkrrbbhhsstt__ffoorrmmaatt__ssttrriinngg(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
             _c_o_n_s_t _k_r_b_5___k_r_b_h_s_t___i_n_f_o _*_h_o_s_t, _c_h_a_r _*_h_o_s_t_n_a_m_e, _s_i_z_e___t _h_o_s_t_l_e_n)

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__kkrrbbhhsstt__ggeett__aaddddrriinnffoo(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___k_r_b_h_s_t___i_n_f_o _*_h_o_s_t,
             _s_t_r_u_c_t _a_d_d_r_i_n_f_o _*_*_a_i)

DDEESSCCRRIIPPTTIIOONN
     These functions are used to sequence through all Kerberos hosts of a par-
     ticular realm and service. The service type can be the KDCs, the adminis-
     trative servers, the password changing servers, or the servers for Ker-
     beros 4 ticket conversion.

     First a handle to a particular service is obtained by calling
     kkrrbb55__kkrrbbhhsstt__iinniitt() with the _r_e_a_l_m of interest and the type of service to
     lookup. The _t_y_p_e can be one of:

           KRB5_KRBHST_KDC
           KRB5_KRBHST_ADMIN
           KRB5_KRBHST_CHANGEPW
           KRB5_KRBHST_KRB524

     The _h_a_n_d_l_e is returned to the caller, and should be passed to the other
     functions.

     For each call to kkrrbb55__kkrrbbhhsstt__nneexxtt() information a new host is returned.
     The former function returns in _h_o_s_t a pointer to a structure containing
     information about the host, such as protocol, hostname, and port:

           typedef struct krb5_krbhst_info {
               enum { KRB5_KRBHST_UDP,
                      KRB5_KRBHST_TCP,
                      KRB5_KRBHST_HTTP } proto;
               unsigned short port;
               struct addrinfo *ai;
               struct krb5_krbhst_info *next;
               char hostname[1];
           } krb5_krbhst_info;

     The related function, kkrrbb55__kkrrbbhhsstt__nneexxtt__aass__ssttrriinngg(), return the same in-
     formation as a url-like string.

     When there are no more hosts, these functions return KRB5_KDC_UNREACH.

     To re-iterate over all hosts, call kkrrbb55__kkrrbbhhsstt__rreesseett() and the next call
     to kkrrbb55__kkrrbbhhsstt__nneexxtt() will return the first host.

     When done with the handle, kkrrbb55__kkrrbbhhsstt__ffrreeee() should be called.

     To use a _k_r_b_5___k_r_b_h_s_t___i_n_f_o, there are two functions:
     kkrrbb55__kkrrbbhhsstt__ffoorrmmaatt__ssttrriinngg() that will return a printable representation
     of that struct and kkrrbb55__kkrrbbhhsstt__ggeett__aaddddrriinnffoo() that will return a _s_t_r_u_c_t
     _a_d_d_r_i_n_f_o that can then be used for communicating with the server men-
     tioned.

EEXXAAMMPPLLEE
     The following code will print the KDCs of the realm ``MY.REALM''.

           krb5_krbhst_handle handle;
           char host[MAXHOSTNAMELEN];
           krb5_krbhst_init(context, "MY.REALM", KRB5_KRBHST_KDC, &handle);
           while(krb5_krbhst_next_as_string(context, handle,
                                            host, sizeof(host)) == 0)
               printf("%s\n", host);
           krb5_krbhst_free(context, handle);

HHIISSTTOORRYY
     These functions first appeared in Heimdal 0.3g.

SSEEEE AALLSSOO
     getaddrinfo(3),  krb5_get_krbhst(3)

 HEIMDAL                         June 17, 2001                               2