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 16Kerberos 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 34These functions are used to sequence through all Kerberos hosts of a 35particular realm and service. The service type can be the KDCs, the 36administrative servers, the password changing servers, or the servers 37for Kerberos 4 ticket conversion. 38.Pp 39First a handle to a particular service is obtained by calling 40.Fn krb5_krbhst_init 41with the 42.Fa realm 43of interest and the type of service to lookup. The 44.Fa type 45can 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 54The 55.Fa handle 56is returned to the caller, and should be passed to the other 57functions. 58.Pp 59For each call to 60.Fn krb5_krbhst_next 61information a new host is returned. The former function returns in 62.Fa host 63a pointer to a structure containing information about the host, such 64as protocol, hostname, and port: 65.Bd -literal -offset indent 66typedef 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 77The related function, 78.Fn krb5_krbhst_next_as_string , 79return the same information as a url-like string. 80.Pp 81When there are no more hosts, these functions return 82.Dv KRB5_KDC_UNREACH . 83.Pp 84To re-iterate over all hosts, call 85.Fn krb5_krbhst_reset 86and the next call to 87.Fn krb5_krbhst_next 88will return the first host. 89.Pp 90When done with the handle, 91.Fn krb5_krbhst_free 92should be called. 93.Pp 94To use a 95.Va krb5_krbhst_info , 96there are two functions: 97.Fn krb5_krbhst_format_string 98that will return a printable representation of that struct 99and 100.Fn krb5_krbhst_get_addrinfo 101that will return a 102.Va struct addrinfo 103that can then be used for communicating with the server mentioned. 104.Sh EXAMPLE 105The following code will print the KDCs of the realm 106.Dq MY.REALM . 107.Bd -literal -offset indent 108krb5_krbhst_handle handle; 109char host[MAXHOSTNAMELEN]; 110krb5_krbhst_init(context, "MY.REALM", KRB5_KRBHST_KDC, &handle); 111while(krb5_krbhst_next_as_string(context, handle, 112 host, sizeof(host)) == 0) 113 printf("%s\\n", host); 114krb5_krbhst_free(context, handle); 115.Ed 116.\" .Sh BUGS 117.Sh HISTORY 118These functions first appeared in Heimdal 0.3g. 119.Sh SEE ALSO 120.Xr getaddrinfo 3 , 121.Xr krb5_get_krbhst 3 122