libpsl

libpsl — Public Suffix List library functions

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libpsl.h>

enum                psl_error_t;
typedef             psl_ctx_t;
psl_ctx_t *         psl_load_file                       (const char *fname);
psl_ctx_t *         psl_load_fp                         (FILE *fp);
const psl_ctx_t *   psl_builtin                         (void);
void                psl_free                            (psl_ctx_t *psl);
int                 psl_is_public_suffix                (const psl_ctx_t *psl,
                                                         const char *domain);
const char *        psl_unregistrable_domain            (const psl_ctx_t *psl,
                                                         const char *domain);
const char *        psl_registrable_domain              (const psl_ctx_t *psl,
                                                         const char *domain);
int                 psl_suffix_count                    (const psl_ctx_t *psl);
int                 psl_suffix_exception_count          (const psl_ctx_t *psl);
time_t              psl_builtin_compile_time            (void);
time_t              psl_builtin_file_time               (void);
const char *        psl_builtin_sha1sum                 (void);
const char *        psl_builtin_filename                (void);
int                 psl_is_cookie_domain_acceptable     (const psl_ctx_t *psl,
                                                         const char *hostname,
                                                         const char *cookie_domain);
const char *        psl_get_version                     (void);
psl_error_t         psl_str_to_utf8lower                (const char *str,
                                                         const char *encoding,
                                                         const char *locale,
                                                         char **lower);

Description

[Public Suffix List](http://publicsuffix.org/) library functions.

Details

enum psl_error_t

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;

Return codes for PSL functions. Negative return codes mean failure. Positive values are reserved for non-error return codes.

PSL_SUCCESS

Successful return.

PSL_ERR_INVALID_ARG

Invalid argument.

PSL_ERR_CONVERTER

Failed to open libicu utf-16 converter

PSL_ERR_TO_UTF16

Failed to convert to utf-16.

PSL_ERR_TO_LOWER

Failed to convert utf-16 to lowercase.

PSL_ERR_TO_UTF8

Failed to convert utf-16 to utf-8.

psl_ctx_t

typedef struct _psl_ctx_st psl_ctx_t;

psl_load_file ()

psl_ctx_t *         psl_load_file                       (const char *fname);

This function loads the public suffixes file named fname. To free the allocated resources, call psl_free().

The suffixes are expected to be lowercase UTF-8 encoded if they are international.

fname :

Name of PSL file

Returns :

Pointer to a PSL context or NULL on failure.

Since 0.1


psl_load_fp ()

psl_ctx_t *         psl_load_fp                         (FILE *fp);

This function loads the public suffixes from a FILE pointer. To free the allocated resources, call psl_free().

The suffixes are expected to be lowercase UTF-8 encoded if they are international.

fp :

FILE pointer

Returns :

Pointer to a PSL context or NULL on failure.

Since 0.1


psl_builtin ()

const psl_ctx_t *   psl_builtin                         (void);

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.

The builtin data also contains punycode entries, one for each international domain name.

If the generation of built-in data has been disabled during compilation, NULL will be returned. So if using the builtin psl context, you can provide UTF-8 or punycode representations of domains to functions like psl_is_public_suffix().

Returns :

Pointer to the built in PSL data or NULL if this data is not available.

Since 0.1


psl_free ()

void                psl_free                            (psl_ctx_t *psl);

psl_is_public_suffix ()

int                 psl_is_public_suffix                (const psl_ctx_t *psl,
                                                         const char *domain);

This function checks if domain is a public suffix by the means of the [Mozilla Public Suffix List](http://publicsuffix.org).

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().

psl :

PSL context

domain :

Domain string

Returns :

1 if domain is a public suffix, 0 if not.

Since 0.1


psl_unregistrable_domain ()

const char *        psl_unregistrable_domain            (const psl_ctx_t *psl,
                                                         const char *domain);

This function finds the longest publix suffix part of domain by the means of the [Mozilla Public Suffix List](http://publicsuffix.org).

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().

psl :

PSL context

domain :

Domain string

Returns :

Pointer to longest public suffix part of domain or NULL if domain does not contain a public suffix (or if psl is NULL).

Since 0.1


psl_registrable_domain ()

const char *        psl_registrable_domain              (const psl_ctx_t *psl,
                                                         const char *domain);

This function finds the shortest private suffix part of domain by the means of the [Mozilla Public Suffix List](http://publicsuffix.org).

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().

psl :

PSL context

domain :

Domain string

Returns :

Pointer to shortest private suffix part of domain or NULL if domain does not contain a private suffix (or if psl is NULL).

Since 0.1


psl_suffix_count ()

int                 psl_suffix_count                    (const psl_ctx_t *psl);

This function returns number of public suffixes maintained by psl. The number of exceptions within the Public Suffix List are not included.

If the generation of built-in data has been disabled during compilation, 0 will be returned.

psl :

PSL context pointer

Returns :

Number of public suffixes entries in PSL context.

Since 0.1


psl_suffix_exception_count ()

int                 psl_suffix_exception_count          (const psl_ctx_t *psl);

This function returns number of public suffix exceptions maintained by psl.

If the generation of built-in data has been disabled during compilation, 0 will be returned.

psl :

PSL context pointer

Returns :

Number of public suffix exceptions in PSL context.

Since 0.1


psl_builtin_compile_time ()

time_t              psl_builtin_compile_time            (void);

This function returns the time when the Publix Suffix List has been compiled into C code (by psl2c).

If the generation of built-in data has been disabled during compilation, 0 will be returned.

Returns :

time_t value or 0.

Since 0.1


psl_builtin_file_time ()

time_t              psl_builtin_file_time               (void);

This function returns the mtime of the Publix Suffix List file that has been built in.

If the generation of built-in data has been disabled during compilation, 0 will be returned.

Returns :

time_t value or 0.

Since 0.1


psl_builtin_sha1sum ()

const char *        psl_builtin_sha1sum                 (void);

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".

If the generation of built-in data has been disabled during compilation, an empty string will be returned.

Returns :

String containing SHA1 checksum or an empty string.

Since 0.1


psl_builtin_filename ()

const char *        psl_builtin_filename                (void);

This function returns the file name of the Publix Suffix List file that has been built in.

If the generation of built-in data has been disabled during compilation, an empty string will be returned.

Returns :

String containing the PSL file name or an empty string.

Since 0.1


psl_is_cookie_domain_acceptable ()

int                 psl_is_cookie_domain_acceptable     (const psl_ctx_t *psl,
                                                         const char *hostname,
                                                         const char *cookie_domain);

This helper function checks whether cookie_domain is an acceptable cookie domain value for the request 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: 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.

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.

psl :

PSL context pointer

hostname :

The request hostname.

cookie_domain :

The domain value from a cookie

Returns :

1 if acceptable, 0 if not acceptable.

Since 0.1


psl_get_version ()

const char *        psl_get_version                     (void);

Get libpsl version.

Returns :

String containing version of libpsl.

Since 0.2.5


psl_str_to_utf8lower ()

psl_error_t         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 set to NULL on error.

The return value 'lower' must be freed after usage.

str :

string to convert

encoding :

charset encoding of str, e.g. 'iso-8859-1' or NULL

locale :

locale of str for to lowercase conversion, e.g. 'de' or NULL

lower :

return value containing the converted string

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