Hostname Utilities

Hostname Utilities — Internet hostname utilities

Functions

Includes

#include <glib.h>
#include <glib/gi18n.h>

Description

Functions for manipulating internet hostnames; in particular, for converting between Unicode and ASCII-encoded forms of Internationalized Domain Names (IDNs).

The Internationalized Domain Names for Applications (IDNA) standards allow for the use of Unicode domain names in applications, while providing backward-compatibility with the old ASCII-only DNS, by defining an ASCII-Compatible Encoding of any given Unicode name, which can be used with non-IDN-aware applications and protocols. (For example, "Παν語.org" maps to "xn--4wa8awb4637h.org".)

Functions

g_hostname_to_ascii ()

gchar *
g_hostname_to_ascii (const gchar *hostname);

Converts hostname to its canonical ASCII form; an ASCII-only string containing no uppercase letters and not ending with a trailing dot.

Parameters

hostname

a valid UTF-8 or ASCII hostname

 

Returns

an ASCII hostname, which must be freed, or NULL if hostname is in some way invalid.

[nullable][transfer full]

Since: 2.22


g_hostname_to_unicode ()

gchar *
g_hostname_to_unicode (const gchar *hostname);

Converts hostname to its canonical presentation form; a UTF-8 string in Unicode normalization form C, containing no uppercase letters, no forbidden characters, and no ASCII-encoded segments, and not ending with a trailing dot.

Of course if hostname is not an internationalized hostname, then the canonical presentation form will be entirely ASCII.

Parameters

hostname

a valid UTF-8 or ASCII hostname

 

Returns

a UTF-8 hostname, which must be freed, or NULL if hostname is in some way invalid.

[nullable][transfer full]

Since: 2.22


g_hostname_is_non_ascii ()

gboolean
g_hostname_is_non_ascii (const gchar *hostname);

Tests if hostname contains Unicode characters. If this returns TRUE, you need to encode the hostname with g_hostname_to_ascii() before using it in non-IDN-aware contexts.

Note that a hostname might contain a mix of encoded and unencoded segments, and so it is possible for g_hostname_is_non_ascii() and g_hostname_is_ascii_encoded() to both return TRUE for a name.

Parameters

hostname

a hostname

 

Returns

TRUE if hostname contains any non-ASCII characters

Since: 2.22


g_hostname_is_ascii_encoded ()

gboolean
g_hostname_is_ascii_encoded (const gchar *hostname);

Tests if hostname contains segments with an ASCII-compatible encoding of an Internationalized Domain Name. If this returns TRUE, you should decode the hostname with g_hostname_to_unicode() before displaying it to the user.

Note that a hostname might contain a mix of encoded and unencoded segments, and so it is possible for g_hostname_is_non_ascii() and g_hostname_is_ascii_encoded() to both return TRUE for a name.

Parameters

hostname

a hostname

 

Returns

TRUE if hostname contains any ASCII-encoded segments.

Since: 2.22


g_hostname_is_ip_address ()

gboolean
g_hostname_is_ip_address (const gchar *hostname);

Tests if hostname is the string form of an IPv4 or IPv6 address. (Eg, "192.168.0.1".)

Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).

Parameters

hostname

a hostname (or IP address in string form)

 

Returns

TRUE if hostname is an IP address

Since: 2.22