---
name: "krb5_unparse_name_fixed_flags"
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_unparse_name_fixed_flags"
---

# krb5\_unparse\_name\_fixed\_flags(3)

Kerberos 5 principal handling functions

## NAME

**krb5\_get\_default\_principal**, **krb5\_principal**, **krb5\_build\_principal**, **krb5\_build\_principal\_ext**, **krb5\_build\_principal\_va**, **krb5\_build\_principal\_va\_ext**, **krb5\_copy\_principal**, **krb5\_free\_principal**, **krb5\_make\_principal**, **krb5\_parse\_name**, **krb5\_parse\_name\_flags**, **krb5\_parse\_nametype**, **krb5\_princ\_set\_realm**, **krb5\_principal\_compare**, **krb5\_principal\_compare\_any\_realm**, **krb5\_principal\_get\_comp\_string**, **krb5\_principal\_get\_realm**, **krb5\_principal\_get\_type**, **krb5\_principal\_match**, **krb5\_principal\_set\_type**, **krb5\_realm\_compare**, **krb5\_sname\_to\_principal**, **krb5\_sock\_to\_principal**, **krb5\_unparse\_name**, **krb5\_unparse\_name\_flags**, **krb5\_unparse\_name\_fixed**, **krb5\_unparse\_name\_fixed\_flags**, **krb5\_unparse\_name\_fixed\_short**, **krb5\_unparse\_name\_short** – Kerberos 5 principal handling functions

## LIBRARY

Kerberos 5 Library (libkrb5, -lkrb5)

## SYNOPSIS

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

krb5\_principal;

*void*\

**krb5\_free\_principal**(*krb5\_context context*, *krb5\_principal principal*);

*krb5\_error\_code*\

**krb5\_parse\_name**(*krb5\_context context*, *const char \*name*, *krb5\_principal \*principal*);

*krb5\_error\_code*\

**krb5\_parse\_name\_flags**(*krb5\_context context*, *const char \*name*, *int flags*, *krb5\_principal \*principal*);

*krb5\_error\_code*\

**krb5\_unparse\_name**(*krb5\_context context*, *krb5\_const\_principal principal*, *char \*\*name*);

*krb5\_error\_code*\

**krb5\_unparse\_name\_flags**(*krb5\_context context*, *krb5\_const\_principal principal*, *int flags*, *char \*\*name*);

*krb5\_error\_code*\

**krb5\_unparse\_name\_fixed**(*krb5\_context context*, *krb5\_const\_principal principal*, *char \*name*, *size\_t len*);

*krb5\_error\_code*\

**krb5\_unparse\_name\_fixed\_flags**(*krb5\_context context*, *krb5\_const\_principal principal*, *int flags*, *char \*name*, *size\_t len*);

*krb5\_error\_code*\

**krb5\_unparse\_name\_short**(*krb5\_context context*, *krb5\_const\_principal principal*, *char \*\*name*);

*krb5\_error\_code*\

**krb5\_unparse\_name\_fixed\_short**(*krb5\_context context*, *krb5\_const\_principal principal*, *char \*name*, *size\_t len*);

*void*\

**krb5\_princ\_set\_realm**(*krb5\_context context*, *krb5\_principal principal*, *krb5\_realm \*realm*);

*krb5\_error\_code*\

**krb5\_build\_principal**(*krb5\_context context*, *krb5\_principal \*principal*, *int rlen*, *krb5\_const\_realm realm*, *...*);

*krb5\_error\_code*\

**krb5\_build\_principal\_va**(*krb5\_context context*, *krb5\_principal \*principal*, *int rlen*, *krb5\_const\_realm realm*, *va\_list ap*);

*krb5\_error\_code*\

**krb5\_build\_principal\_ext**(*krb5\_context context*, *krb5\_principal \*principal*, *int rlen*, *krb5\_const\_realm realm*, *...*);

*krb5\_error\_code*\

**krb5\_build\_principal\_va\_ext**(*krb5\_context context*, *krb5\_principal \*principal*, *int rlen*, *krb5\_const\_realm realm*, *va\_list ap*);

*krb5\_error\_code*\

**krb5\_make\_principal**(*krb5\_context context*, *krb5\_principal \*principal*, *krb5\_const\_realm realm*, *...*);

*krb5\_error\_code*\

**krb5\_copy\_principal**(*krb5\_context context*, *krb5\_const\_principal inprinc*, *krb5\_principal \*outprinc*);

*krb5\_boolean*\

**krb5\_principal\_compare**(*krb5\_context context*, *krb5\_const\_principal princ1*, *krb5\_const\_principal princ2*);

*krb5\_boolean*\

**krb5\_principal\_compare\_any\_realm**(*krb5\_context context*, *krb5\_const\_principal princ1*, *krb5\_const\_principal princ2*);

*const char \**\

**krb5\_principal\_get\_comp\_string**(*krb5\_context context*, *krb5\_const\_principal principal*, *unsigned int component*);

*const char \**\

**krb5\_principal\_get\_realm**(*krb5\_context context*, *krb5\_const\_principal principal*);

*int*\

**krb5\_principal\_get\_type**(*krb5\_context context*, *krb5\_const\_principal principal*);

*krb5\_boolean*\

**krb5\_principal\_match**(*krb5\_context context*, *krb5\_const\_principal principal*, *krb5\_const\_principal pattern*);

*void*\

**krb5\_principal\_set\_type**(*krb5\_context context*, *krb5\_principal principal*, *int type*);

*krb5\_boolean*\

**krb5\_realm\_compare**(*krb5\_context context*, *krb5\_const\_principal princ1*, *krb5\_const\_principal princ2*);

*krb5\_error\_code*\

**krb5\_sname\_to\_principal**(*krb5\_context context*, *const char \*hostname*, *const char \*sname*, *int32\_t type*, *krb5\_principal \*ret\_princ*);

*krb5\_error\_code*\

**krb5\_sock\_to\_principal**(*krb5\_context context*, *int socket*, *const char \*sname*, *int32\_t type*, *krb5\_principal \*principal*);

*krb5\_error\_code*\

**krb5\_get\_default\_principal**(*krb5\_context context*, *krb5\_principal \*princ*);

*krb5\_error\_code*\

**krb5\_parse\_nametype**(*krb5\_context context*, *const char \*str*, *int32\_t \*type*);

## DESCRIPTION

krb5\_principal holds the name of a user or service in Kerberos.

A principal has two parts, a PrincipalName and a realm. The PrincipalName consists of one or more components. In printed form, the components are separated by /. The PrincipalName also has a name-type.

Examples of a principal are nisse/root@EXAMPLE.COM and host/datan.kth.se@KTH.SE. **krb5\_parse\_name**() and **krb5\_parse\_name\_flags**() passes a principal name in *name* to the kerberos principal structure. **krb5\_parse\_name\_flags**() takes an extra *flags* argument the following flags can be passed in

- KRB5\_PRINCIPAL\_PARSE\_NO\_REALM

  requires the input string to be without a realm, and no realm is stored in the *principal* return argument.

- KRB5\_PRINCIPAL\_PARSE\_REQUIRE\_REALM

  requires the input string to with a realm.

**krb5\_unparse\_name**() and **krb5\_unparse\_name\_flags**() prints the principal *princ* to the string *name*. *name* should be freed with [free(3)](/free/3.md). To the *flags* argument the following flags can be passed in

- KRB5\_PRINCIPAL\_UNPARSE\_SHORT

  no realm if the realm is one of the local realms.

- KRB5\_PRINCIPAL\_UNPARSE\_NO\_REALM

  never include any realm in the principal name.

- KRB5\_PRINCIPAL\_UNPARSE\_DISPLAY

  don't quote

On failure *name* is set to NULL. **krb5\_unparse\_name\_fixed**() and **krb5\_unparse\_name\_fixed\_flags**() behaves just like **krb5\_unparse**(), but instead unparses the principal into a fixed size buffer.

**krb5\_unparse\_name\_short**() just returns the principal without the realm if the principal is in the default realm. If the principal isn't, the full name is returned. **krb5\_unparse\_name\_fixed\_short**() works just like **krb5\_unparse\_name\_short**() but on a fixed size buffer.

**krb5\_build\_principal**() builds a principal from the realm *realm* that has the length *rlen*. The following arguments form the components of the principal. The list of components is terminated with NULL.

**krb5\_build\_principal\_va**() works like **krb5\_build\_principal**() using vargs.

**krb5\_build\_principal\_ext**() and **krb5\_build\_principal\_va\_ext**() take a list of length-value pairs, the list is terminated with a zero length.

**krb5\_make\_principal**() works the same way as **krb5\_build\_principal**(), except it figures out the length of the realm itself.

**krb5\_copy\_principal**() makes a copy of a principal. The copy needs to be freed with **krb5\_free\_principal**().

**krb5\_principal\_compare**() compares the two principals, including realm of the principals and returns TRUE if they are the same and FALSE if not.

**krb5\_principal\_compare\_any\_realm**() works the same way as **krb5\_principal\_compare**() but doesn't compare the realm component of the principal.

**krb5\_realm\_compare**() compares the realms of the two principals and returns TRUE is they are the same, and FALSE if not.

**krb5\_principal\_match**() matches a *principal* against a *pattern*. The pattern is a globbing expression, where each component (separated by /) is matched against the corresponding component of the principal.

The **krb5\_principal\_get\_realm**() and **krb5\_principal\_get\_comp\_string**() functions return parts of the *principal*, either the realm or a specific component. Both functions return string pointers to data inside the principal, so they are valid only as long as the principal exists.

The *component* argument to **krb5\_principal\_get\_comp\_string**() is the index of the component to return, from zero to the total number of components minus one. If the index is out of range NULL is returned.

**krb5\_principal\_get\_realm**() and **krb5\_principal\_get\_comp\_string**() are replacements for **krb5\_princ\_component**() and related macros, described as internal in the MIT API specification. Unlike the macros, these functions return strings, not krb5\_data. A reason to return krb5\_data was that it was believed that principal components could contain binary data, but this belief was unfounded, and it has been decided that principal components are infact UTF8, so it's safe to use zero terminated strings.

It's generally not necessary to look at the components of a principal.

**krb5\_principal\_get\_type**() and **krb5\_principal\_set\_type**() get and sets the name type for a principal. Name type handling is tricky and not often needed, don't use this unless you know what you do.

**krb5\_sname\_to\_principal**() and **krb5\_sock\_to\_principal**() are for easy creation of “service” principals that can, for instance, be used to lookup a key in a keytab. For both functions the *sname* parameter will be used for the first component of the created principal. If *sname* is NULL, “host” will be used instead.

**krb5\_sname\_to\_principal**() will use the passed *hostname* for the second component. If *type* is KRB5\_NT\_SRV\_HST this name will be looked up with **gethostbyname**(). If *hostname* is NULL, the local hostname will be used.

**krb5\_sock\_to\_principal**() will use the “sockname” of the passed *socket*, which should be a bound AF\_INET or AF\_INET6 socket. There must be a mapping between the address and “sockname”. The function may try to resolve the name in DNS.

**krb5\_get\_default\_principal**() tries to find out what's a reasonable default principal by looking at the environment it is running in.

**krb5\_parse\_nametype**() parses and returns the name type integer value in *type*. On failure the function returns an error code and set the error string.

## SEE ALSO

[krb5\_config(3)](/krb5_config/3.md), [krb5.conf(5)](/krb5.conf/5.md)

## BUGS

You can not have a NUL in a component in some of the variable argument functions above. Until someone can give a good example of where it would be a good idea to have NUL's in a component, this will not be fixed.