<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="glib-Hostname-Utilities">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Hostname-Utilities.top_of_page">Hostname Utilities</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Hostname Utilities</refname>
<refpurpose>Internet hostname utilities</refpurpose>
</refnamediv>

<refsect1 id="glib-Hostname-Utilities.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_return" colwidth="150px"/>
<colspec colname="functions_name"/>
<tbody>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-hostname-to-ascii">g_hostname_to_ascii</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-hostname-to-unicode">g_hostname_to_unicode</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-hostname-is-non-ascii">g_hostname_is_non_ascii</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-hostname-is-ascii-encoded">g_hostname_is_ascii_encoded</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-hostname-is-ip-address">g_hostname_is_ip_address</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="glib-Hostname-Utilities.includes"><title>Includes</title><synopsis>#include &lt;glib.h&gt;
#include &lt;glib/gi18n.h&gt;
</synopsis></refsect1>

<refsect1 id="glib-Hostname-Utilities.description" role="desc">
<title role="desc.title">Description</title>
<para>Functions for manipulating internet hostnames; in particular, for
converting between Unicode and ASCII-encoded forms of
Internationalized Domain Names (IDNs).</para>
<para>The
<ulink url="http://www.ietf.org/rfc/rfc3490.txt">Internationalized Domain Names for Applications (IDNA)</ulink>
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".)</para>

</refsect1>
<refsect1 id="glib-Hostname-Utilities.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="g-hostname-to-ascii" role="function" condition="since:2.22">
<title>g_hostname_to_ascii&#160;()</title>
<indexterm zone="g-hostname-to-ascii" role="2.22"><primary sortas="hostname_to_ascii">g_hostname_to_ascii</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_hostname_to_ascii (<parameter>const <link linkend="gchar"><type>gchar</type></link> *hostname</parameter>);</programlisting>
<para>Converts <parameter>hostname</parameter>
 to its canonical ASCII form; an ASCII-only
string containing no uppercase letters and not ending with a
trailing dot.</para>
<refsect3 id="g-hostname-to-ascii.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>hostname</para></entry>
<entry role="parameter_description"><para>a valid UTF-8 or ASCII hostname</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-hostname-to-ascii.returns" role="returns">
<title>Returns</title>
<para> an ASCII hostname, which must be freed, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if
<parameter>hostname</parameter>
is in some way invalid.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.22">2.22</link></para></refsect2>
<refsect2 id="g-hostname-to-unicode" role="function" condition="since:2.22">
<title>g_hostname_to_unicode&#160;()</title>
<indexterm zone="g-hostname-to-unicode" role="2.22"><primary sortas="hostname_to_unicode">g_hostname_to_unicode</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_hostname_to_unicode (<parameter>const <link linkend="gchar"><type>gchar</type></link> *hostname</parameter>);</programlisting>
<para>Converts <parameter>hostname</parameter>
 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.</para>
<para>Of course if <parameter>hostname</parameter>
 is not an internationalized hostname, then
the canonical presentation form will be entirely ASCII.</para>
<refsect3 id="g-hostname-to-unicode.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>hostname</para></entry>
<entry role="parameter_description"><para>a valid UTF-8 or ASCII hostname</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-hostname-to-unicode.returns" role="returns">
<title>Returns</title>
<para> a UTF-8 hostname, which must be freed, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if
<parameter>hostname</parameter>
is in some way invalid.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.22">2.22</link></para></refsect2>
<refsect2 id="g-hostname-is-non-ascii" role="function" condition="since:2.22">
<title>g_hostname_is_non_ascii&#160;()</title>
<indexterm zone="g-hostname-is-non-ascii" role="2.22"><primary sortas="hostname_is_non_ascii">g_hostname_is_non_ascii</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_hostname_is_non_ascii (<parameter>const <link linkend="gchar"><type>gchar</type></link> *hostname</parameter>);</programlisting>
<para>Tests if <parameter>hostname</parameter>
 contains Unicode characters. If this returns
<link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, you need to encode the hostname with <link linkend="g-hostname-to-ascii"><function>g_hostname_to_ascii()</function></link>
before using it in non-IDN-aware contexts.</para>
<para>Note that a hostname might contain a mix of encoded and unencoded
segments, and so it is possible for <link linkend="g-hostname-is-non-ascii"><function>g_hostname_is_non_ascii()</function></link> and
<link linkend="g-hostname-is-ascii-encoded"><function>g_hostname_is_ascii_encoded()</function></link> to both return <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> for a name.</para>
<refsect3 id="g-hostname-is-non-ascii.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>hostname</para></entry>
<entry role="parameter_description"><para>a hostname</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-hostname-is-non-ascii.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>hostname</parameter>
contains any non-ASCII characters</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.22">2.22</link></para></refsect2>
<refsect2 id="g-hostname-is-ascii-encoded" role="function" condition="since:2.22">
<title>g_hostname_is_ascii_encoded&#160;()</title>
<indexterm zone="g-hostname-is-ascii-encoded" role="2.22"><primary sortas="hostname_is_ascii_encoded">g_hostname_is_ascii_encoded</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_hostname_is_ascii_encoded (<parameter>const <link linkend="gchar"><type>gchar</type></link> *hostname</parameter>);</programlisting>
<para>Tests if <parameter>hostname</parameter>
 contains segments with an ASCII-compatible
encoding of an Internationalized Domain Name. If this returns
<link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, you should decode the hostname with <link linkend="g-hostname-to-unicode"><function>g_hostname_to_unicode()</function></link>
before displaying it to the user.</para>
<para>Note that a hostname might contain a mix of encoded and unencoded
segments, and so it is possible for <link linkend="g-hostname-is-non-ascii"><function>g_hostname_is_non_ascii()</function></link> and
<link linkend="g-hostname-is-ascii-encoded"><function>g_hostname_is_ascii_encoded()</function></link> to both return <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> for a name.</para>
<refsect3 id="g-hostname-is-ascii-encoded.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>hostname</para></entry>
<entry role="parameter_description"><para>a hostname</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-hostname-is-ascii-encoded.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>hostname</parameter>
contains any ASCII-encoded
segments.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.22">2.22</link></para></refsect2>
<refsect2 id="g-hostname-is-ip-address" role="function" condition="since:2.22">
<title>g_hostname_is_ip_address&#160;()</title>
<indexterm zone="g-hostname-is-ip-address" role="2.22"><primary sortas="hostname_is_ip_address">g_hostname_is_ip_address</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_hostname_is_ip_address (<parameter>const <link linkend="gchar"><type>gchar</type></link> *hostname</parameter>);</programlisting>
<para>Tests if <parameter>hostname</parameter>
 is the string form of an IPv4 or IPv6 address.
(Eg, "192.168.0.1".)</para>
<refsect3 id="g-hostname-is-ip-address.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>hostname</para></entry>
<entry role="parameter_description"><para>a hostname (or IP address in string form)</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-hostname-is-ip-address.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>hostname</parameter>
is an IP address</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.22">2.22</link></para></refsect2>

</refsect1>
<refsect1 id="glib-Hostname-Utilities.other_details" role="details">
<title role="details.title">Types and Values</title>

</refsect1>

</refentry>
