<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
  <!ENTITY version SYSTEM "version.xml"> 
]>
<refentry id="libpsl-Public-Suffix-List-functions">
<refmeta>
<refentrytitle role="top_of_page" id="libpsl-Public-Suffix-List-functions.top_of_page">libpsl</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  LIBPSL Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>libpsl</refname>
<refpurpose>Public Suffix List library functions</refpurpose>
</refnamediv>
<refsect1 id="libpsl-Public-Suffix-List-functions.stability-level">
<title>Stability Level</title>
Unstable, unless otherwise indicated
</refsect1>

<refsynopsisdiv id="libpsl-Public-Suffix-List-functions.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
#include &lt;libpsl.h&gt;

enum                <link linkend="psl-error-t">psl_error_t</link>;
typedef             <link linkend="psl-ctx-t">psl_ctx_t</link>;
<link linkend="psl-ctx-t"><returnvalue>psl_ctx_t</returnvalue></link> *         <link linkend="psl-load-file">psl_load_file</link>                       (<parameter>const <link linkend="char"><type>char</type></link> *fname</parameter>);
<link linkend="psl-ctx-t"><returnvalue>psl_ctx_t</returnvalue></link> *         <link linkend="psl-load-fp">psl_load_fp</link>                         (<parameter><link linkend="FILE:CAPS"><type>FILE</type></link> *fp</parameter>);
const <link linkend="psl-ctx-t"><returnvalue>psl_ctx_t</returnvalue></link> *   <link linkend="psl-builtin">psl_builtin</link>                         (<parameter><type>void</type></parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="psl-free">psl_free</link>                            (<parameter><link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>);
<link linkend="int"><returnvalue>int</returnvalue></link>                 <link linkend="psl-is-public-suffix">psl_is_public_suffix</link>                (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *domain</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="psl-unregistrable-domain">psl_unregistrable_domain</link>            (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *domain</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="psl-registrable-domain">psl_registrable_domain</link>              (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *domain</parameter>);
<link linkend="int"><returnvalue>int</returnvalue></link>                 <link linkend="psl-suffix-count">psl_suffix_count</link>                    (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>);
<link linkend="int"><returnvalue>int</returnvalue></link>                 <link linkend="psl-suffix-exception-count">psl_suffix_exception_count</link>          (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>);
<link linkend="time-t"><returnvalue>time_t</returnvalue></link>              <link linkend="psl-builtin-compile-time">psl_builtin_compile_time</link>            (<parameter><type>void</type></parameter>);
<link linkend="time-t"><returnvalue>time_t</returnvalue></link>              <link linkend="psl-builtin-file-time">psl_builtin_file_time</link>               (<parameter><type>void</type></parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="psl-builtin-sha1sum">psl_builtin_sha1sum</link>                 (<parameter><type>void</type></parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="psl-builtin-filename">psl_builtin_filename</link>                (<parameter><type>void</type></parameter>);
<link linkend="int"><returnvalue>int</returnvalue></link>                 <link linkend="psl-is-cookie-domain-acceptable">psl_is_cookie_domain_acceptable</link>     (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *hostname</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *cookie_domain</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="psl-get-version">psl_get_version</link>                     (<parameter><type>void</type></parameter>);
<link linkend="psl-error-t"><returnvalue>psl_error_t</returnvalue></link>         <link linkend="psl-str-to-utf8lower">psl_str_to_utf8lower</link>                (<parameter>const <link linkend="char"><type>char</type></link> *str</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *encoding</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *locale</parameter>,
                                                         <parameter><link linkend="char"><type>char</type></link> **lower</parameter>);
</synopsis>
</refsynopsisdiv>

<refsect1 id="libpsl-Public-Suffix-List-functions.description" role="desc">
<title role="desc.title">Description</title>
<para>
[Public Suffix List](http://publicsuffix.org/) library functions.
</para>
</refsect1>
<refsect1 id="libpsl-Public-Suffix-List-functions.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="psl-error-t" role="enum">
<title>enum psl_error_t</title>
<indexterm zone="psl-error-t"><primary>psl_error_t</primary></indexterm>
<programlisting>typedef enum {
	PSL_SUCCESS = 0,
	PSL_ERR_INVALID_ARG = -1,
	PSL_ERR_CONVERTER = -2, /* failed to open libicu utf-16 converter */
	PSL_ERR_TO_UTF16 = -3, /* failed to convert to utf-16 */
	PSL_ERR_TO_LOWER = -4, /* failed to convert utf-16 to lowercase */
	PSL_ERR_TO_UTF8 = -5 /* failed to convert utf-16 to utf-8 */
} psl_error_t;
</programlisting>
<para>
Return codes for PSL functions.
Negative return codes mean failure.
Positive values are reserved for non-error return codes.
</para><variablelist role="enum">
<varlistentry id="PSL-SUCCESS:CAPS" role="constant">
<term><literal>PSL_SUCCESS</literal></term>
<listitem><simpara>Successful return.
</simpara></listitem>
</varlistentry>
<varlistentry id="PSL-ERR-INVALID-ARG:CAPS" role="constant">
<term><literal>PSL_ERR_INVALID_ARG</literal></term>
<listitem><simpara>Invalid argument.
</simpara></listitem>
</varlistentry>
<varlistentry id="PSL-ERR-CONVERTER:CAPS" role="constant">
<term><literal>PSL_ERR_CONVERTER</literal></term>
<listitem><simpara>Failed to open libicu utf-16 converter
</simpara></listitem>
</varlistentry>
<varlistentry id="PSL-ERR-TO-UTF16:CAPS" role="constant">
<term><literal>PSL_ERR_TO_UTF16</literal></term>
<listitem><simpara>Failed to convert to utf-16.
</simpara></listitem>
</varlistentry>
<varlistentry id="PSL-ERR-TO-LOWER:CAPS" role="constant">
<term><literal>PSL_ERR_TO_LOWER</literal></term>
<listitem><simpara>Failed to convert utf-16 to lowercase.
</simpara></listitem>
</varlistentry>
<varlistentry id="PSL-ERR-TO-UTF8:CAPS" role="constant">
<term><literal>PSL_ERR_TO_UTF8</literal></term>
<listitem><simpara>Failed to convert utf-16 to utf-8.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="psl-ctx-t" role="typedef">
<title>psl_ctx_t</title>
<indexterm zone="psl-ctx-t"><primary>psl_ctx_t</primary></indexterm>
<programlisting>typedef struct _psl_ctx_st psl_ctx_t;
</programlisting>
</refsect2>
<refsect2 id="psl-load-file" role="function" condition="since:0.1">
<title>psl_load_file ()</title>
<indexterm zone="psl-load-file" role="0.1"><primary>psl_load_file</primary></indexterm>
<programlisting><link linkend="psl-ctx-t"><returnvalue>psl_ctx_t</returnvalue></link> *         psl_load_file                       (<parameter>const <link linkend="char"><type>char</type></link> *fname</parameter>);</programlisting>
<para>
This function loads the public suffixes file named <parameter>fname</parameter>.
To free the allocated resources, call <link linkend="psl-free"><function>psl_free()</function></link>.
</para>
<para>
The suffixes are expected to be lowercase UTF-8 encoded if they are international.
</para><variablelist role="params">
<varlistentry><term><parameter>fname</parameter>&#160;:</term>
<listitem><simpara>Name of PSL file</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>Pointer to a PSL context or <link linkend="NULL:CAPS"><literal>NULL</literal></link> on failure.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-load-fp" role="function" condition="since:0.1">
<title>psl_load_fp ()</title>
<indexterm zone="psl-load-fp" role="0.1"><primary>psl_load_fp</primary></indexterm>
<programlisting><link linkend="psl-ctx-t"><returnvalue>psl_ctx_t</returnvalue></link> *         psl_load_fp                         (<parameter><link linkend="FILE:CAPS"><type>FILE</type></link> *fp</parameter>);</programlisting>
<para>
This function loads the public suffixes from a FILE pointer.
To free the allocated resources, call <link linkend="psl-free"><function>psl_free()</function></link>.
</para>
<para>
The suffixes are expected to be lowercase UTF-8 encoded if they are international.
</para><variablelist role="params">
<varlistentry><term><parameter>fp</parameter>&#160;:</term>
<listitem><simpara>FILE pointer</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>Pointer to a PSL context or <link linkend="NULL:CAPS"><literal>NULL</literal></link> on failure.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-builtin" role="function" condition="since:0.1">
<title>psl_builtin ()</title>
<indexterm zone="psl-builtin" role="0.1"><primary>psl_builtin</primary></indexterm>
<programlisting>const <link linkend="psl-ctx-t"><returnvalue>psl_ctx_t</returnvalue></link> *   psl_builtin                         (<parameter><type>void</type></parameter>);</programlisting>
<para>
This function returns the PSL context that has been generated and built in at compile-time.
You don't have to free the returned context explicitely.
</para>
<para>
The builtin data also contains punycode entries, one for each international domain name.
</para>
<para>
If the generation of built-in data has been disabled during compilation, <link linkend="NULL:CAPS"><literal>NULL</literal></link> will be returned.
So if using the builtin psl context, you can provide UTF-8 or punycode representations of domains to
functions like <link linkend="psl-is-public-suffix"><function>psl_is_public_suffix()</function></link>.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>Pointer to the built in PSL data or NULL if this data is not available.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-free" role="function">
<title>psl_free ()</title>
<indexterm zone="psl-free"><primary>psl_free</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                psl_free                            (<parameter><link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>);</programlisting>
</refsect2>
<refsect2 id="psl-is-public-suffix" role="function" condition="since:0.1">
<title>psl_is_public_suffix ()</title>
<indexterm zone="psl-is-public-suffix" role="0.1"><primary>psl_is_public_suffix</primary></indexterm>
<programlisting><link linkend="int"><returnvalue>int</returnvalue></link>                 psl_is_public_suffix                (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *domain</parameter>);</programlisting>
<para>
This function checks if <parameter>domain</parameter> is a public suffix by the means of the
[Mozilla Public Suffix List](http://publicsuffix.org).
</para>
<para>
For cookie domain checking see <link linkend="psl-is-cookie-domain-acceptable"><function>psl_is_cookie_domain_acceptable()</function></link>.
</para>
<para>
International <parameter>domain</parameter> names have to be either in lowercase UTF-8 or in ASCII form (punycode).
Other encodings result in unexpected behavior.
</para>
<para>
<parameter>psl</parameter> is a context returned by either <link linkend="psl-load-file"><function>psl_load_file()</function></link>, <link linkend="psl-load-fp"><function>psl_load_fp()</function></link> or
<link linkend="psl-builtin"><function>psl_builtin()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>psl</parameter>&#160;:</term>
<listitem><simpara>PSL context</simpara></listitem></varlistentry>
<varlistentry><term><parameter>domain</parameter>&#160;:</term>
<listitem><simpara>Domain string</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>1 if domain is a public suffix, 0 if not.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-unregistrable-domain" role="function" condition="since:0.1">
<title>psl_unregistrable_domain ()</title>
<indexterm zone="psl-unregistrable-domain" role="0.1"><primary>psl_unregistrable_domain</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        psl_unregistrable_domain            (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *domain</parameter>);</programlisting>
<para>
This function finds the longest publix suffix part of <parameter>domain</parameter> by the means
of the [Mozilla Public Suffix List](http://publicsuffix.org).
</para>
<para>
International <parameter>domain</parameter> names have to be either in lowercase UTF-8 or in ASCII form (punycode).
Other encodings result in unexpected behavior.
</para>
<para>
<parameter>psl</parameter> is a context returned by either <link linkend="psl-load-file"><function>psl_load_file()</function></link>, <link linkend="psl-load-fp"><function>psl_load_fp()</function></link> or
<link linkend="psl-builtin"><function>psl_builtin()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>psl</parameter>&#160;:</term>
<listitem><simpara>PSL context</simpara></listitem></varlistentry>
<varlistentry><term><parameter>domain</parameter>&#160;:</term>
<listitem><simpara>Domain string</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>Pointer to longest public suffix part of <parameter>domain</parameter> or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>domain</parameter>
does not contain a public suffix (or if <parameter>psl</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>).</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-registrable-domain" role="function" condition="since:0.1">
<title>psl_registrable_domain ()</title>
<indexterm zone="psl-registrable-domain" role="0.1"><primary>psl_registrable_domain</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        psl_registrable_domain              (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *domain</parameter>);</programlisting>
<para>
This function finds the shortest private suffix part of <parameter>domain</parameter> by the means
of the [Mozilla Public Suffix List](http://publicsuffix.org).
</para>
<para>
International <parameter>domain</parameter> names have to be either in lowercase UTF-8 or in ASCII form (punycode).
Other encodings result in unexpected behavior.
</para>
<para>
<parameter>psl</parameter> is a context returned by either <link linkend="psl-load-file"><function>psl_load_file()</function></link>, <link linkend="psl-load-fp"><function>psl_load_fp()</function></link> or
<link linkend="psl-builtin"><function>psl_builtin()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>psl</parameter>&#160;:</term>
<listitem><simpara>PSL context</simpara></listitem></varlistentry>
<varlistentry><term><parameter>domain</parameter>&#160;:</term>
<listitem><simpara>Domain string</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>Pointer to shortest private suffix part of <parameter>domain</parameter> or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>domain</parameter>
does not contain a private suffix (or if <parameter>psl</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>).</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-suffix-count" role="function" condition="since:0.1">
<title>psl_suffix_count ()</title>
<indexterm zone="psl-suffix-count" role="0.1"><primary>psl_suffix_count</primary></indexterm>
<programlisting><link linkend="int"><returnvalue>int</returnvalue></link>                 psl_suffix_count                    (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>);</programlisting>
<para>
This function returns number of public suffixes maintained by <parameter>psl</parameter>.
The number of exceptions within the Public Suffix List are not included.
</para>
<para>
If the generation of built-in data has been disabled during compilation, 0 will be returned.
</para><variablelist role="params">
<varlistentry><term><parameter>psl</parameter>&#160;:</term>
<listitem><simpara>PSL context pointer</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>Number of public suffixes entries in PSL context.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-suffix-exception-count" role="function" condition="since:0.1">
<title>psl_suffix_exception_count ()</title>
<indexterm zone="psl-suffix-exception-count" role="0.1"><primary>psl_suffix_exception_count</primary></indexterm>
<programlisting><link linkend="int"><returnvalue>int</returnvalue></link>                 psl_suffix_exception_count          (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>);</programlisting>
<para>
This function returns number of public suffix exceptions maintained by <parameter>psl</parameter>.
</para>
<para>
If the generation of built-in data has been disabled during compilation, 0 will be returned.
</para><variablelist role="params">
<varlistentry><term><parameter>psl</parameter>&#160;:</term>
<listitem><simpara>PSL context pointer</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>Number of public suffix exceptions in PSL context.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-builtin-compile-time" role="function" condition="since:0.1">
<title>psl_builtin_compile_time ()</title>
<indexterm zone="psl-builtin-compile-time" role="0.1"><primary>psl_builtin_compile_time</primary></indexterm>
<programlisting><link linkend="time-t"><returnvalue>time_t</returnvalue></link>              psl_builtin_compile_time            (<parameter><type>void</type></parameter>);</programlisting>
<para>
This function returns the time when the Publix Suffix List has been compiled into C code (by psl2c).
</para>
<para>
If the generation of built-in data has been disabled during compilation, 0 will be returned.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>time_t value or 0.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-builtin-file-time" role="function" condition="since:0.1">
<title>psl_builtin_file_time ()</title>
<indexterm zone="psl-builtin-file-time" role="0.1"><primary>psl_builtin_file_time</primary></indexterm>
<programlisting><link linkend="time-t"><returnvalue>time_t</returnvalue></link>              psl_builtin_file_time               (<parameter><type>void</type></parameter>);</programlisting>
<para>
This function returns the mtime of the Publix Suffix List file that has been built in.
</para>
<para>
If the generation of built-in data has been disabled during compilation, 0 will be returned.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>time_t value or 0.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-builtin-sha1sum" role="function" condition="since:0.1">
<title>psl_builtin_sha1sum ()</title>
<indexterm zone="psl-builtin-sha1sum" role="0.1"><primary>psl_builtin_sha1sum</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        psl_builtin_sha1sum                 (<parameter><type>void</type></parameter>);</programlisting>
<para>
This function returns the SHA1 checksum of the Publix Suffix List file that has been built in.
The returned string is in lowercase hex encoding, e.g. "2af1e9e3044eda0678bb05949d7cca2f769901d8".
</para>
<para>
If the generation of built-in data has been disabled during compilation, an empty string will be returned.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>String containing SHA1 checksum or an empty string.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-builtin-filename" role="function" condition="since:0.1">
<title>psl_builtin_filename ()</title>
<indexterm zone="psl-builtin-filename" role="0.1"><primary>psl_builtin_filename</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        psl_builtin_filename                (<parameter><type>void</type></parameter>);</programlisting>
<para>
This function returns the file name of the Publix Suffix List file that has been built in.
</para>
<para>
If the generation of built-in data has been disabled during compilation, an empty string will be returned.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>String containing the PSL file name or an empty string.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-is-cookie-domain-acceptable" role="function" condition="since:0.1">
<title>psl_is_cookie_domain_acceptable ()</title>
<indexterm zone="psl-is-cookie-domain-acceptable" role="0.1"><primary>psl_is_cookie_domain_acceptable</primary></indexterm>
<programlisting><link linkend="int"><returnvalue>int</returnvalue></link>                 psl_is_cookie_domain_acceptable     (<parameter>const <link linkend="psl-ctx-t"><type>psl_ctx_t</type></link> *psl</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *hostname</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *cookie_domain</parameter>);</programlisting>
<para>
This helper function checks whether <parameter>cookie_domain</parameter> is an acceptable cookie domain value for the request
<parameter>hostname</parameter>.
</para>
<para>
For international domain names both, <parameter>hostname</parameter> and <parameter>cookie_domain</parameter>, have to be either in lowercase UTF-8
or in ASCII form (punycode). Other encodings or mixing UTF-8 and punycode result in unexpected behavior.
</para>
<para>
Examples:
1. Cookie domain 'example.com' would be acceptable for hostname 'www.example.com',
but '.com' or 'com' would NOT be acceptable since 'com' is a public suffix.
</para>
<para>
2. Cookie domain 'his.name' would be acceptable for hostname 'remember.his.name',
 but NOT for 'forgot.his.name' since 'forgot.his.name' is a public suffix.
</para><variablelist role="params">
<varlistentry><term><parameter>psl</parameter>&#160;:</term>
<listitem><simpara>PSL context pointer</simpara></listitem></varlistentry>
<varlistentry><term><parameter>hostname</parameter>&#160;:</term>
<listitem><simpara>The request hostname.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cookie_domain</parameter>&#160;:</term>
<listitem><simpara>The domain value from a cookie</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>1 if acceptable, 0 if not acceptable.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.1</para></refsect2>
<refsect2 id="psl-get-version" role="function" condition="since:0.2.5">
<title>psl_get_version ()</title>
<indexterm zone="psl-get-version" role="0.2.5"><primary>psl_get_version</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        psl_get_version                     (<parameter><type>void</type></parameter>);</programlisting>
<para>
Get libpsl version.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>String containing version of libpsl.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.2.5</para></refsect2>
<refsect2 id="psl-str-to-utf8lower" role="function" condition="since:0.4">
<title>psl_str_to_utf8lower ()</title>
<indexterm zone="psl-str-to-utf8lower" role="0.4"><primary>psl_str_to_utf8lower</primary></indexterm>
<programlisting><link linkend="psl-error-t"><returnvalue>psl_error_t</returnvalue></link>         psl_str_to_utf8lower                (<parameter>const <link linkend="char"><type>char</type></link> *str</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *encoding</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *locale</parameter>,
                                                         <parameter><link linkend="char"><type>char</type></link> **lower</parameter>);</programlisting>
<para>
This helper function converts a string to lowercase UTF-8 representation.
Lowercase UTF-8 is needed as input to the domain checking functions.
</para>
<para>
<parameter>lower</parameter> is set to <link linkend="NULL:CAPS"><literal>NULL</literal></link> on error.
</para>
<para>
The return value 'lower' must be freed after usage.
</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter>&#160;:</term>
<listitem><simpara>string to convert</simpara></listitem></varlistentry>
<varlistentry><term><parameter>encoding</parameter>&#160;:</term>
<listitem><simpara>charset encoding of <parameter>str</parameter>, e.g. 'iso-8859-1' or <link linkend="NULL:CAPS"><literal>NULL</literal></link></simpara></listitem></varlistentry>
<varlistentry><term><parameter>locale</parameter>&#160;:</term>
<listitem><simpara>locale of <parameter>str</parameter> for to lowercase conversion, e.g. 'de' or <link linkend="NULL:CAPS"><literal>NULL</literal></link></simpara></listitem></varlistentry>
<varlistentry><term><parameter>lower</parameter>&#160;:</term>
<listitem><simpara>return value containing the converted string</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>psl_error_t value.
PSL_SUCCESS: Success
PSL_ERR_INVALID_ARG: <parameter>str</parameter> is a <link linkend="NULL:CAPS"><literal>NULL</literal></link> value.
PSL_ERR_CONVERTER: Failed to open the unicode converter with name <parameter>encoding</parameter>
PSL_ERR_TO_UTF16: Failed to convert <parameter>str</parameter> to unicode
PSL_ERR_TO_LOWER: Failed to convert unicode to lowercase
PSL_ERR_TO_UTF8: Failed to convert unicode to UTF-8</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.4</para></refsect2>

</refsect1>

</refentry>
