## libpsl

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 ()
void | psl_free ()
int | psl_is_public_suffix ()
const char * | psl_unregistrable_domain ()
const char * | psl_registrable_domain ()
int | psl_suffix_count ()
int | psl_suffix_exception_count ()
int | psl_suffix_wildcard_count ()
time_t | psl_builtin_compile_time ()
time_t | psl_builtin_file_time ()
const char * | psl_builtin_sha1sum ()
const char * | psl_builtin_filename ()
int | psl_builtin_outdated ()
int | psl_is_cookie_domain_acceptable ()
const char * | psl_get_version ()
int | psl_check_version_number ()
psl_error_t | psl_str_to_utf8lower ()

## Types and Values

#define | PSL_VERSION
#define | PSL_VERSION_MAJOR
#define | PSL_VERSION_MINOR
#define | PSL_VERSION_NUMBER
#define | PSL_VERSION_PATCH
enum | psl_error_t
typedef | psl_ctx_t

## Includes

    #include <libpsl.h>

## Description

Public Suffix List 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 lowercase UTF-8 encoded 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 lowercase UTF-8 encoded 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. 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);

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.

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

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.

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

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.

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

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

#### Parameters

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

#### 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

Since: 0.4

## Types and Values

### PSL_VERSION

    #define PSL_VERSION "0.11.0"

### PSL_VERSION_MAJOR

    #define PSL_VERSION_MAJOR 0

### PSL_VERSION_MINOR

    #define PSL_VERSION_MINOR 11

### PSL_VERSION_NUMBER

    #define PSL_VERSION_NUMBER 0x000b00

### PSL_VERSION_PATCH

    #define PSL_VERSION_PATCH 0

### 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_ctx_t

    typedef struct _psl_ctx_st psl_ctx_t;