docs/reference/glib/html/glib-Hostname-Utilities.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Hostname Utilities</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-utilities.html" title="GLib Utilities">
   9 <link rel="prev" href="glib-URI-Functions.html" title="URI Functions">
  10 <link rel="next" href="glib-Shell-related-Utilities.html" title="Shell-related Utilities">
  11 <meta name="generator" content="GTK-Doc V1.13 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 <link rel="chapter" href="glib.html" title="GLib Overview">
  14 <link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals">
  15 <link rel="chapter" href="glib-core.html" title="GLib Core Application Support">
  16 <link rel="chapter" href="glib-utilities.html" title="GLib Utilities">
  17 <link rel="chapter" href="glib-data-types.html" title="GLib Data Types">
  18 <link rel="chapter" href="tools.html" title="GLib Tools">
  19 <link rel="index" href="api-index-full.html" title="Index">
  20 <link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
  21 <link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
  22 <link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
  23 <link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
  24 <link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
  25 <link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
  26 <link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
  27 <link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
  28 <link rel="index" href="api-index-2-16.html" title="Index of new symbols in 2.16">
  29 <link rel="index" href="api-index-2-18.html" title="Index of new symbols in 2.18">
  30 <link rel="index" href="api-index-2-20.html" title="Index of new symbols in 2.20">
  31 <link rel="index" href="api-index-2-22.html" title="Index of new symbols in 2.22">
  32 <link rel="index" href="api-index-2-24.html" title="Index of new symbols in 2.24">
  33 </head>
  34 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  35 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  36 <tr valign="middle">
  37 <td><a accesskey="p" href="glib-URI-Functions.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  38 <td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  39 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  40 <th width="100%" align="center">GLib Reference Manual</th>
  41 <td><a accesskey="n" href="glib-Shell-related-Utilities.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  42 </tr>
  43 <tr><td colspan="5" class="shortcuts">
  44 <a href="#glib-Hostname-Utilities.synopsis" class="shortcut">Top</a>
  45                    |
  46                   <a href="#glib-Hostname-Utilities.description" class="shortcut">Description</a>
  47 </td></tr>
  48 </table>
  49 <div class="refentry" title="Hostname Utilities">
  50 <a name="glib-Hostname-Utilities"></a><div class="titlepage"></div>
  51 <div class="refnamediv"><table width="100%"><tr>
  52 <td valign="top">
  53 <h2><span class="refentrytitle"><a name="glib-Hostname-Utilities.top_of_page"></a>Hostname Utilities</span></h2>
  54 <p>Hostname Utilities — Internet hostname utilities</p>
  55 </td>
  56 <td valign="top" align="right"></td>
  57 </tr></table></div>
  58 <div class="refsynopsisdiv" title="Synopsis">
  59 <a name="glib-Hostname-Utilities.synopsis"></a><h2>Synopsis</h2>
  60 <pre class="synopsis">
  61 #include &lt;glib.h&gt;
  62
  63 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Hostname-Utilities.html#g-hostname-to-ascii" title="g_hostname_to_ascii ()">g_hostname_to_ascii</a>                 (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *hostname);
  64 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Hostname-Utilities.html#g-hostname-to-unicode" title="g_hostname_to_unicode ()">g_hostname_to_unicode</a>               (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *hostname);
  65
  66 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Hostname-Utilities.html#g-hostname-is-non-ascii" title="g_hostname_is_non_ascii ()">g_hostname_is_non_ascii</a>             (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *hostname);
  67 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Hostname-Utilities.html#g-hostname-is-ascii-encoded" title="g_hostname_is_ascii_encoded ()">g_hostname_is_ascii_encoded</a>         (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *hostname);
  68
  69 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Hostname-Utilities.html#g-hostname-is-ip-address" title="g_hostname_is_ip_address ()">g_hostname_is_ip_address</a>            (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *hostname);
  70 </pre>
  71 </div>
  72 <div class="refsect1" title="Description">
  73 <a name="glib-Hostname-Utilities.description"></a><h2>Description</h2>
  74 <p>
  75 Functions for manipulating internet hostnames; in particular, for
  76 converting between Unicode and ASCII-encoded forms of
  77 Internationalized Domain Names (IDNs).
  78 </p>
  79 <p>
  80 The <a class="ulink" href="http://www.ietf.org/rfc/rfc3490.txt" target="_top">Internationalized Domain
  81 Names for Applications (IDNA)</a> standards allow for the use
  82 of Unicode domain names in applications, while providing
  83 backward-compatibility with the old ASCII-only DNS, by defining an
  84 ASCII-Compatible Encoding of any given Unicode name, which can be
  85 used with non-IDN-aware applications and protocols. (For example,
  86 "Παν語.org" maps to "xn--4wa8awb4637h.org".)</p>
  87 </div>
  88 <div class="refsect1" title="Details">
  89 <a name="glib-Hostname-Utilities.details"></a><h2>Details</h2>
  90 <div class="refsect2" title="g_hostname_to_ascii ()">
  91 <a name="g-hostname-to-ascii"></a><h3>g_hostname_to_ascii ()</h3>
  92 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_hostname_to_ascii                 (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *hostname);</pre>
  93 <p>
  94 Converts <em class="parameter"><code>hostname</code></em> to its canonical ASCII form; an ASCII-only
  95 string containing no uppercase letters and not ending with a
  96 trailing dot.</p>
  97 <div class="variablelist"><table border="0">
  98 <col align="left" valign="top">
  99 <tbody>
 100 <tr>
 101 <td><p><span class="term"><em class="parameter"><code>hostname</code></em> :</span></p></td>
 102 <td> a valid UTF-8 or ASCII hostname
 103 </td>
 104 </tr>
 105 <tr>
 106 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 107 <td> an ASCII hostname, which must be freed, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if
 108 <em class="parameter"><code>hostname</code></em> is in some way invalid.
 109
 110 </td>
 111 </tr>
 112 </tbody>
 113 </table></div>
 114 <p class="since">Since 2.22</p>
 115 </div>
 116 <hr>
 117 <div class="refsect2" title="g_hostname_to_unicode ()">
 118 <a name="g-hostname-to-unicode"></a><h3>g_hostname_to_unicode ()</h3>
 119 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_hostname_to_unicode               (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *hostname);</pre>
 120 <p>
 121 Converts <em class="parameter"><code>hostname</code></em> to its canonical presentation form; a UTF-8
 122 string in Unicode normalization form C, containing no uppercase
 123 letters, no forbidden characters, and no ASCII-encoded segments,
 124 and not ending with a trailing dot.
 125 </p>
 126 <p>
 127 Of course if <em class="parameter"><code>hostname</code></em> is not an internationalized hostname, then
 128 the canonical presentation form will be entirely ASCII.</p>
 129 <div class="variablelist"><table border="0">
 130 <col align="left" valign="top">
 131 <tbody>
 132 <tr>
 133 <td><p><span class="term"><em class="parameter"><code>hostname</code></em> :</span></p></td>
 134 <td> a valid UTF-8 or ASCII hostname
 135 </td>
 136 </tr>
 137 <tr>
 138 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 139 <td> a UTF-8 hostname, which must be freed, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if
 140 <em class="parameter"><code>hostname</code></em> is in some way invalid.
 141
 142 </td>
 143 </tr>
 144 </tbody>
 145 </table></div>
 146 <p class="since">Since 2.22</p>
 147 </div>
 148 <hr>
 149 <div class="refsect2" title="g_hostname_is_non_ascii ()">
 150 <a name="g-hostname-is-non-ascii"></a><h3>g_hostname_is_non_ascii ()</h3>
 151 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_hostname_is_non_ascii             (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *hostname);</pre>
 152 <p>
 153 Tests if <em class="parameter"><code>hostname</code></em> contains Unicode characters. If this returns
 154 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, you need to encode the hostname with <a class="link" href="glib-Hostname-Utilities.html#g-hostname-to-ascii" title="g_hostname_to_ascii ()"><code class="function">g_hostname_to_ascii()</code></a>
 155 before using it in non-IDN-aware contexts.
 156 </p>
 157 <p>
 158 Note that a hostname might contain a mix of encoded and unencoded
 159 segments, and so it is possible for <a class="link" href="glib-Hostname-Utilities.html#g-hostname-is-non-ascii" title="g_hostname_is_non_ascii ()"><code class="function">g_hostname_is_non_ascii()</code></a> and
 160 <a class="link" href="glib-Hostname-Utilities.html#g-hostname-is-ascii-encoded" title="g_hostname_is_ascii_encoded ()"><code class="function">g_hostname_is_ascii_encoded()</code></a> to both return <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> for a name.</p>
 161 <div class="variablelist"><table border="0">
 162 <col align="left" valign="top">
 163 <tbody>
 164 <tr>
 165 <td><p><span class="term"><em class="parameter"><code>hostname</code></em> :</span></p></td>
 166 <td> a hostname
 167 </td>
 168 </tr>
 169 <tr>
 170 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 171 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>hostname</code></em> contains any non-ASCII characters
 172
 173 </td>
 174 </tr>
 175 </tbody>
 176 </table></div>
 177 <p class="since">Since 2.22</p>
 178 </div>
 179 <hr>
 180 <div class="refsect2" title="g_hostname_is_ascii_encoded ()">
 181 <a name="g-hostname-is-ascii-encoded"></a><h3>g_hostname_is_ascii_encoded ()</h3>
 182 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_hostname_is_ascii_encoded         (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *hostname);</pre>
 183 <p>
 184 Tests if <em class="parameter"><code>hostname</code></em> contains segments with an ASCII-compatible
 185 encoding of an Internationalized Domain Name. If this returns
 186 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, you should decode the hostname with <a class="link" href="glib-Hostname-Utilities.html#g-hostname-to-unicode" title="g_hostname_to_unicode ()"><code class="function">g_hostname_to_unicode()</code></a>
 187 before displaying it to the user.
 188 </p>
 189 <p>
 190 Note that a hostname might contain a mix of encoded and unencoded
 191 segments, and so it is possible for <a class="link" href="glib-Hostname-Utilities.html#g-hostname-is-non-ascii" title="g_hostname_is_non_ascii ()"><code class="function">g_hostname_is_non_ascii()</code></a> and
 192 <a class="link" href="glib-Hostname-Utilities.html#g-hostname-is-ascii-encoded" title="g_hostname_is_ascii_encoded ()"><code class="function">g_hostname_is_ascii_encoded()</code></a> to both return <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> for a name.</p>
 193 <div class="variablelist"><table border="0">
 194 <col align="left" valign="top">
 195 <tbody>
 196 <tr>
 197 <td><p><span class="term"><em class="parameter"><code>hostname</code></em> :</span></p></td>
 198 <td> a hostname
 199 </td>
 200 </tr>
 201 <tr>
 202 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 203 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>hostname</code></em> contains any ASCII-encoded
 204 segments.
 205
 206 </td>
 207 </tr>
 208 </tbody>
 209 </table></div>
 210 <p class="since">Since 2.22</p>
 211 </div>
 212 <hr>
 213 <div class="refsect2" title="g_hostname_is_ip_address ()">
 214 <a name="g-hostname-is-ip-address"></a><h3>g_hostname_is_ip_address ()</h3>
 215 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_hostname_is_ip_address            (const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *hostname);</pre>
 216 <p>
 217 Tests if <em class="parameter"><code>hostname</code></em> is the string form of an IPv4 or IPv6 address.
 218 (Eg, "192.168.0.1".)</p>
 219 <div class="variablelist"><table border="0">
 220 <col align="left" valign="top">
 221 <tbody>
 222 <tr>
 223 <td><p><span class="term"><em class="parameter"><code>hostname</code></em> :</span></p></td>
 224 <td> a hostname (or IP address in string form)
 225 </td>
 226 </tr>
 227 <tr>
 228 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 229 <td> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>hostname</code></em> is an IP address
 230
 231 </td>
 232 </tr>
 233 </tbody>
 234 </table></div>
 235 <p class="since">Since 2.22</p>
 236 </div>
 237 </div>
 238 </div>
 239 <div class="footer">
 240 <hr>
 241           Generated by GTK-Doc V1.13</div>
 242 </body>
 243 </html>