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