---
name: "krb5_krbhst_free"
section: "3"
platform: "linux"
package: "heimdal-dev"
version: "7.8.git20221117.28daf24+dfsg-9+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/krb5_krbhst_free"
---

# krb5\_krbhst\_free(3)

lookup Kerberos KDC hosts

## NAME

**krb5\_krbhst\_init**, **krb5\_krbhst\_init\_flags**, **krb5\_krbhst\_next**, **krb5\_krbhst\_next\_as\_string**, **krb5\_krbhst\_reset**, **krb5\_krbhst\_free**, **krb5\_krbhst\_format\_string**, **krb5\_krbhst\_get\_addrinfo** – lookup Kerberos KDC hosts

## LIBRARY

Kerberos 5 Library (libkrb5, -lkrb5)

## SYNOPSIS

**#include \<krb5.h\>**

*krb5\_error\_code*\

**krb5\_krbhst\_init**(*krb5\_context context*, *const char \*realm*, *unsigned int type*, *krb5\_krbhst\_handle \*handle*);

*krb5\_error\_code*\

**krb5\_krbhst\_init\_flags**(*krb5\_context context*, *const char \*realm*, *unsigned int type*, *int flags*, *krb5\_krbhst\_handle \*handle*);

*krb5\_error\_code*\

**krb5\_krbhst\_next**(*krb5\_context context*, *krb5\_krbhst\_handle handle*, *krb5\_krbhst\_info \*\*host*);

*krb5\_error\_code*\

**krb5\_krbhst\_next\_as\_string**(*krb5\_context context*, *krb5\_krbhst\_handle handle*, *char \*hostname*, *size\_t hostlen*);

*void*\

**krb5\_krbhst\_reset**(*krb5\_context context*, *krb5\_krbhst\_handle handle*);

*void*\

**krb5\_krbhst\_free**(*krb5\_context context*, *krb5\_krbhst\_handle handle*);

*krb5\_error\_code*\

**krb5\_krbhst\_format\_string**(*krb5\_context context*, *const krb5\_krbhst\_info \*host*, *char \*hostname*, *size\_t hostlen*);

*krb5\_error\_code*\

**krb5\_krbhst\_get\_addrinfo**(*krb5\_context context*, *krb5\_krbhst\_info \*host*, *struct addrinfo \*\*ai*);

## DESCRIPTION

These functions are used to sequence through all Kerberos hosts of a particular realm and service. The service type can be the KDCs, the administrative servers, the password changing servers, or the servers for Kerberos 4 ticket conversion.

First a handle to a particular service is obtained by calling **krb5\_krbhst\_init**() (or **krb5\_krbhst\_init\_flags**()) with the *realm* of interest and the type of service to lookup. The *type* can be one of:

- KRB5\_KRBHST\_KDC

  - KRB5\_KRBHST\_ADMIN

  - KRB5\_KRBHST\_CHANGEPW

  - KRB5\_KRBHST\_KRB524

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

The *flag* argument to **krb5\_krbhst\_init\_flags** is the same flags as **krb5\_send\_to\_kdc\_flags**() 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 transport that can handle that.

For each call to **krb5\_krbhst\_next**() information on a new host is returned. The former function returns in *host* 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, **krb5\_krbhst\_next\_as\_string**(), 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 **krb5\_krbhst\_reset**() and the next call to **krb5\_krbhst\_next**() will return the first host.

When done with the handle, **krb5\_krbhst\_free**() should be called.

To use a *krb5\_krbhst\_info*, there are two functions: **krb5\_krbhst\_format\_string**() that will return a printable representation of that struct and **krb5\_krbhst\_get\_addrinfo**() that will return a *struct* *addrinfo* that can then be used for communicating with the server mentioned.

## EXAMPLES

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

## SEE ALSO

[getaddrinfo(3)](/getaddrinfo/3.md), [krb5\_get\_krbhst(3)](/krb5_get_krbhst/3.md), krb5\_send\_to\_kdc\_flags(3)

## HISTORY

These functions first appeared in Heimdal 0.3g.