---
name: "libpsl"
section: "3"
platform: "linux"
package: "libpsl"
version: "0.21.5-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libpsl"
---

# libpsl(3)

Public Suffix List library functions

## NAME

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 () |
| psl\_ctx\_t \* | psl\_latest () |
| const psl\_ctx\_t \* | psl\_builtin () |
| void | psl\_free () |
| int | psl\_is\_public\_suffix () |
| int | psl\_is\_public\_suffix2 () |
| 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\_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\_dist\_filename () |
| const char \* | psl\_get\_version () |
| int | psl\_check\_version\_number () |
| psl\_error\_t | psl\_str\_to\_utf8lower () |
| void | psl\_free\_string () |

## TYPES AND VALUES

| | |
| --- | --- |
| #define | PSL\_API |
| #define | PSL\_VERSION |
| #define | PSL\_VERSION\_MAJOR |
| #define | PSL\_VERSION\_MINOR |
| #define | PSL\_VERSION\_NUMBER |
| #define | PSL\_VERSION\_PATCH |
| #define | PSL\_TYPE\_ICANN |
| #define | PSL\_TYPE\_PRIVATE |
| #define | PSL\_TYPE\_NO\_STAR\_RULE |
| #define | PSL\_TYPE\_ANY |
| enum | psl\_error\_t |
| typedef | psl\_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 + NFKC) 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 + NFKC) if they are international.

**Parameters**

| | | |
| --- | --- | --- |
| fp | FILE pointer |  |

**Returns**

Pointer to a PSL context or NULL on failure.

Since: 0.1

### psl\_latest ()

```
psl_ctx_t *
psl_latest (const char *fname);
```

This function loads the the latest available PSL data from either

• *fname* (application specific filename, may be NULL)

• location specified during built-time (filename from ./configure --with-psl-distfile)

• built-in PSL data (generated from ./configure --with-psl-file)

• location of built-in data (filename from ./configure --with-psl-file)

If none of the above is available, the function returns NULL.

To free the allocated resources, call **psl\_free()**.

**Parameters**

| | | |
| --- | --- | --- |
| fname | Name of PSL file or NULL |  |

**Returns**

Pointer to a PSL context or NULL on failure.

Since: 0.16

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

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 + NFKC) 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 + NFKC) 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, PSL\_TYPE\_NO\_STAR\_RULE, and PSL\_TYPE\_ANY.

PSL\_TYPE\_NO\_STAR\_RULE switches of the 'prevailing star rule' (see **List**\[3\] under 'Algorithm' 2.). Applying the flag means that TLDs not explicitly listed in the PSL are \*not\* treated as public suffixes.

International *domain* names have to be either in UTF-8 (lowercase + NFKC) 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 + NFKC) 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 + NFKC) 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.

If the information is not available, the return value is -1 (since 0.19). This is the case with DAFSA blobs or if *psl* is NULL.

**Parameters**

| | | |
| --- | --- | --- |
| psl | PSL context pointer |  |

**Returns**

Number of public suffixes entries in PSL context or -1 if this information is not available.

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 information is not available, the return value is -1 (since 0.19). This is the case with DAFSA blobs or if *psl* is NULL.

**Parameters**

| | | |
| --- | --- | --- |
| psl | PSL context pointer |  |

**Returns**

Number of public suffix exceptions in PSL context or -1 if this information is not available.

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

If the information is not available, the return value is -1 (since 0.19). This is the case with DAFSA blobs or if *psl* is NULL.

**Parameters**

| | | |
| --- | --- | --- |
| psl | PSL context pointer |  |

**Returns**

Number of public suffix wildcards in PSL context or -1 if this information is not available.

Since: 0.10.0

### psl\_builtin\_file\_time ()

```
time_t
psl_builtin_file_time (void);
```

This function returns the mtime of the Public 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 Public 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 Public 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 UTF-8 (lowercase + NFKC) or in ASCII/ACE (punycode) format. Other encodings or mixing UTF-8 and punycode likely result in incorrect return values.

Use helper function **psl\_str\_to\_utf8lower()** for normalization of *hostname* and *cookie\_domain* .

Hint for Windows users: Please make sure the calling application has called **WSAStartup()** before calling **psl\_is\_cookie\_domain\_acceptable()**.

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\_dist\_filename ()

```
const char *
psl_dist_filename (void);
```

This function returns the file name of the distribution/system PSL data file. This file will be considered by **psl\_latest()**.

Return the filename that is set by ./configure --with-psl-distfile, or an empty string.

**Returns**

String containing a PSL file name or an empty string.

Since: 0.16

### 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 + NFKC representation. Lowercase + NFKC UTF-8 is needed as input to the domain checking functions.

*lower* stays unchanged on error.

When returning PSL\_SUCCESS, 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

### psl\_free\_string ()

```
void
psl_free_string (char *str);
```

This function **free()**'s the memory allocated by **psl\_str\_to\_utf8lower()** when returning a lowercase string

**Parameters**

| | | |
| --- | --- | --- |
| str | pointer to lowercase string returned by **psl\_str\_to\_utf8lower()** |  |

Since: 0.19

## TYPES AND VALUES

### PSL\_API

```
#  define PSL_API __attribute__ ((__visibility__("default")))
```

### PSL\_VERSION

```
#define PSL_VERSION "0.21.5"
```

### PSL\_VERSION\_MAJOR

```
#define PSL_VERSION_MAJOR 0
```

### PSL\_VERSION\_MINOR

```
#define PSL_VERSION_MINOR 21
```

### PSL\_VERSION\_NUMBER

```
#define PSL_VERSION_NUMBER 0x001505
```

### PSL\_VERSION\_PATCH

```
#define PSL_VERSION_PATCH 5
```

### PSL\_TYPE\_ICANN

```
#define PSL_TYPE_ICANN        (1<<0)
```

### PSL\_TYPE\_PRIVATE

```
#define PSL_TYPE_PRIVATE      (1<<1)
```

### PSL\_TYPE\_NO\_STAR\_RULE

```
#define PSL_TYPE_NO_STAR_RULE (1<<2)
```

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

  https://publicsuffix.org/

- 2\.

  Mozilla Public Suffix List

  https://publicsuffix.org

- 3\.

  List

  https://publicsuffix.org/list