libpsl man page

libpsl — Public Suffix List library functions

Stability Level

Stable, unless otherwise indicated

Functions

psl_ctx_t *psl_load_file ()
psl_ctx_t *psl_load_fp ()
const psl_ctx_t *psl_builtin ()
voidpsl_free ()
intpsl_is_public_suffix ()
intpsl_is_public_suffix2 ()
const char *psl_unregistrable_domain ()
const char *psl_registrable_domain ()
intpsl_suffix_count ()
intpsl_suffix_exception_count ()
intpsl_suffix_wildcard_count ()
time_tpsl_builtin_file_time ()
const char *psl_builtin_sha1sum ()
const char *psl_builtin_filename ()
intpsl_builtin_outdated ()
intpsl_is_cookie_domain_acceptable ()
const char *psl_get_version ()
intpsl_check_version_number ()
psl_error_tpsl_str_to_utf8lower ()

Types and Values

#definePsl_version
#definePsl_version_major
#definePsl_version_minor
#definePsl_version_number
#definePsl_version_patch
#definePsl_type_icann
#definePsl_type_private
#definePsl_type_any
enumpsl_error_t
typedefpsl_ctx_t

Includes

#include <libpsl.h>

Description

Public Suffix List[1] library functions.

Functions

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 UTF-8 encoded (lowercase + NFCK) if they are international.

Parameters

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 UTF-8 encoded (lowercase + NFCK) if they are international.

Parameters

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. When using the builtin psl context, you can provide UTF-8 (lowercase + NFCK) or ASCII/ACE (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);

This function frees the the PSL context that has been retrieved via psl_load_fp() or psl_load_file().

Parameters

psl

PSL context pointer

Since: 0.1

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[2].

For cookie domain checking see psl_is_cookie_domain_acceptable().

International domain names have to be either in UTF-8 (lowercase + NFCK) or in ASCII/ACE format (punycode). Other encodings likely result in incorrect return values. Use helper function psl_str_to_utf8lower() for normalization domain .

psl is a context returned by either psl_load_file(), psl_load_fp() or psl_builtin().

Parameters

psl

PSL context

domain

Domain string

Returns

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

Since: 0.1

psl_is_public_suffix2 ()

int
psl_is_public_suffix2 (const psl_ctx_t *psl,
                       const char *domain,
                       int type);

This function checks if domain is a public suffix by the means of the Mozilla Public Suffix List[2].

type specifies the PSL section where to perform the lookup. Valid values are Psl_type_private, Psl_type_icann and Psl_type_any.

International domain names have to be either in UTF-8 (lowercase + NFCK) or in ASCII/ACE format (punycode). Other encodings likely result in incorrect return values. Use helper function psl_str_to_utf8lower() for normalization domain .

psl is a context returned by either psl_load_file(), psl_load_fp() or psl_builtin().

Parameters

psl

PSL context

domain

Domain string

type

Domain type

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 public suffix part of domain by the means of the Mozilla Public Suffix List[2].

International domain names have to be either in UTF-8 (lowercase + NFCK) or in ASCII/ACE format (punycode). Other encodings likely result in incorrect return values. Use helper function psl_str_to_utf8lower() for normalization domain .

psl is a context returned by either psl_load_file(), psl_load_fp() or psl_builtin().

Parameters

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[2].

International domain names have to be either in UTF-8 (lowercase + NFCK) or in ASCII/ACE format (punycode). Other encodings likely result in incorrect return values. Use helper function psl_str_to_utf8lower() for normalization domain .

psl is a context returned by either psl_load_file(), psl_load_fp() or psl_builtin().

Parameters

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.

Parameters

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 .

Parameters

psl

PSL context pointer

Returns

Number of public suffix exceptions in PSL context.

Since: 0.1

psl_suffix_wildcard_count ()

int
psl_suffix_wildcard_count (const psl_ctx_t *psl);

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

Parameters

psl

PSL context pointer

Returns

Number of public suffix wildcards in PSL context.

Since: 0.10.0

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

int
psl_builtin_outdated (void);

This function checks if the built-in data is older than the file it has been created from. If it is, it might be a good idea for the application to reload the PSL. The mtime is taken as reference.

If the PSL file does not exist, it is assumed that the built-in data is not outdated.

Returns

1 if the built-in is outdated, 0 otherwise.

Since: 0.10.0

psl_get_version ()

const char *
psl_get_version (void);

Get libpsl version.

Returns

String containing version of libpsl.

Since: 0.2.5

psl_check_version_number ()

int
psl_check_version_number (int version);

Check the given version number is at minimum the current library version number. The version number must be a hexadecimal number like 0x000a01 (V0.10.1).

Parameters

version

Version number (hex) to check against.

Returns

Returns the library version number if the given version number is at least the version of the library, else return 0; If the argument is 0, the function returns the library version number without performing a check.

Since: 0.11.0

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 UTF-8 lowercase + NFCK representation. Lowercase + NFCK 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.

Parameters

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 PSL_ERR_NO_MEM: Failed to allocate memory

Since: 0.4

Types and Values

Psl_version

#define PSL_VERSION "0.15.0"

Psl_version_major

#define PSL_VERSION_MAJOR 0

Psl_version_minor

#define PSL_VERSION_MINOR 15

Psl_version_number

#define PSL_VERSION_NUMBER 0x000f00

Psl_version_patch

#define PSL_VERSION_PATCH 0

Psl_type_icann

#define PSL_TYPE_ICANN   (1<<0)

Psl_type_private

#define PSL_TYPE_PRIVATE (1<<1)

Psl_type_any

#define PSL_TYPE_ANY     (PSL_TYPE_ICANN | PSL_TYPE_PRIVATE)

enum psl_error_t

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

Members

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_ERR_NO_MEM

Failed to allocate memory.

psl_ctx_t

typedef struct _psl_ctx_st psl_ctx_t;

Notes

1.

Public Suffix List

2.

Mozilla Public Suffix List

Info

11/15/2016 LIBPSL Library LIBPSL Library