KRB5_KRBHST_INIT(3)      BSD Library Functions Manual      KRB5_KRBHST_INIT(3)

NNAAMMEE
     kkrrbb55__kkrrbbhhsstt__iinniitt, kkrrbb55__kkrrbbhhsstt__iinniitt__ffllaaggss, 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
     ##iinncclluuddee <<kkrrbb55..hh>>

     _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__iinniitt__ffllaaggss(_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, _i_n_t _f_l_a_g_s, _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() (or kkrrbb55__kkrrbbhhsstt__iinniitt__ffllaaggss()) with the _r_e_a_l_m of inter-
     est 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.

     The _f_l_a_g argument to kkrrbb55__kkrrbbhhsstt__iinniitt__ffllaaggss is the same flags as
     kkrrbb55__sseenndd__ttoo__kkddcc__ffllaaggss() uses.  Possible values are:

           KRB5_KRBHST_FLAGS_MASTER     only talk to master (readwrite) KDC
           KRB5_KRBHST_FLAGS_LARGE_MSG  this is a large message, so use trans-
                                        port that can handle that.

     For each call to kkrrbb55__kkrrbbhhsstt__nneexxtt() information on 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
     information 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.

EEXXAAMMPPLLEESS
     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);

SSEEEE AALLSSOO
     getaddrinfo(3), krb5_get_krbhst(3), krb5_send_to_kdc_flags(3)

HHIISSTTOORRYY
     These functions first appeared in Heimdal 0.3g.

HEIMDAL                          May 10, 2005                          HEIMDAL