Libpsl Reference Manual |
|---|
- for Libpsl 0.2.1
+ for Libpsl 0.4.0
.
The latest version of this documentation can be found on-line at
GitHub.
diff --git a/index.sgml b/index.sgml
index 7825391..8ea2118 100644
--- a/index.sgml
+++ b/index.sgml
@@ -21,5 +21,8 @@
+
+const char *
+
+
+psl_get_version ()
+
+
+
+int
+
+
+psl_str_to_utf8lower ()
+
+
const char
This function loads the public suffixes file named fname
.
To free the allocated resources, call psl_free().
-If you want to use punycode representations for functions like psl_is_public_suffix(),
-these have to exist as entries within fname
-. This is a design decision to not pull in
-dependencies for UTF-8 case-handling and IDNA libraries.
-On the contrary, the builtin data already contains punycode entries.
-Have a look into psl2c.c for example code on how to convert UTF-8 to lowercase and to punycode.
+The suffixes are expected to be lowercase UTF-8 encoded if they are international.
-Parameters
+Parameters
@@ -225,7 +241,7 @@ dependencies for UTF-8 case-handling and IDNA libraries.
psl_load_fp (FILE *fp);
This function loads the public suffixes from a FILE pointer.
To free the allocated resources, call psl_free().
-Have a look at psl_load_fp() for punycode considerations.
+The suffixes are expected to be lowercase UTF-8 encoded if they are international.
Parameters
@@ -282,11 +298,14 @@ psl_is_public_suffix (const Mozilla Public Suffix List.
For cookie domain checking see psl_is_cookie_domain_acceptable().
+International domain
+ names have to be either in lowercase UTF-8 or in ASCII form (punycode).
+Other encodings result in unexpected behavior.
psl
is a context returned by either psl_load_file(), psl_load_fp() or
psl_builtin().
-Parameters
+Parameters
const
-Returns
+Returns
1 if domain is a public suffix, 0 if not.
@@ -323,11 +342,14 @@ psl_unregistrable_domain (const This function finds the longest publix suffix part of domain
by the means
of the Mozilla Public Suffix List.
+International domain
+ names have to be either in lowercase UTF-8 or in ASCII form (punycode).
+Other encodings result in unexpected behavior.
psl
is a context returned by either psl_load_file(), psl_load_fp() or
psl_builtin().
-Returns
+Returns
Pointer to longest public suffix part of domain
or NULL if domain
does not contain a public suffix (or if psl
@@ -367,11 +389,14 @@ psl_registrable_domain (const domain
by the means
of the Mozilla Public Suffix List.
+International domain
+ names have to be either in lowercase UTF-8 or in ASCII form (punycode).
+Other encodings result in unexpected behavior.
psl
is a context returned by either psl_load_file(), psl_load_fp() or
psl_builtin().
-Returns
+Returns
Pointer to shortest private suffix part of domain
or NULL if domain
does not contain a private suffix (or if psl
@@ -531,6 +556,10 @@ psl_is_cookie_domain_acceptable (const hostname
.
+For international domain names both, hostname
+ and cookie_domain
+, 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.
Examples:
Cookie domain 'example.com' would be acceptable for hostname 'www.example.com',
@@ -539,7 +568,7 @@ but '.com' or 'com' would NOT be acceptable since 'com' is a public suffix.
<
but NOT for 'forgot.his.name' since 'forgot.his.name' is a public suffix.
-Parameters
+Parameters
Since 0.1
+
+
+
+
+psl_str_to_utf8lower ()
+int
+psl_str_to_utf8lower (const char *str,
+ const char *encoding,
+ const char *locale,
+ char **lower);
+This helper function converts a string to lowercase UTF-8 representation.
+Lowercase UTF-8 is needed as input to the domain checking functions.
+lower
+ is NULL on error.
+The return value 'lower' must be freed after usage.
+
+
+Returns
+ psl_error_t value.
+PSL_SUCCESS: Success
+PSL_ERR_INVALID_ARG: str
+is a NULL value.
+PSL_ERR_CONVERTER: Failed to open the unicode converter with name encoding
+PSL_ERR_TO_UTF16: Failed to convert str
+to unicode
+PSL_ERR_TO_LOWER: Failed to convert unicode to lowercase
+PSL_ERR_TO_UTF8: Failed to convert unicode to UTF-8
+
+
+Since 0.4
+
Types and Values
+enum psl_error_t
+Return codes for PSL functions.
+Negative return codes mean failure.
+Positive values are reserved for non-error return codes.
+
+
+
+