'\" t

.\"     Title: libpsl

.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]

.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>

.\"      Date: 04/26/2018

.\"    Manual: LIBPSL Library

.\"    Source: LIBPSL Library

.\"  Language: English

.\"

.TH "LIBPSL" "3" "04/26/2018" "LIBPSL Library" "LIBPSL Library"

.\" -----------------------------------------------------------------

.\" * Define some portability stuff

.\" -----------------------------------------------------------------

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" http://bugs.debian.org/507673

.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.ie \n(.g .ds Aq \(aq

.el       .ds Aq '

.\" -----------------------------------------------------------------

.\" * set default formatting

.\" -----------------------------------------------------------------

.\" disable hyphenation

.nh

.\" disable justification (adjust text to left margin only)

.ad l

.\" -----------------------------------------------------------------

.\" * MAIN CONTENT STARTS HERE *

.\" -----------------------------------------------------------------

.SH "NAME"

libpsl \- Public Suffix List library functions

.SH "STABILITY LEVEL"

Stable, unless otherwise indicated

.SH "FUNCTIONS"

.TS

expand tab(:);

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l.

T{

psl_ctx_t\ \&*

T}:T{

psl_load_file\ \&()

T}

T{

psl_ctx_t\ \&*

T}:T{

psl_load_fp\ \&()

T}

T{

psl_ctx_t\ \&*

T}:T{

psl_latest\ \&()

T}

T{

const psl_ctx_t\ \&*

T}:T{

psl_builtin\ \&()

T}

T{

void

T}:T{

psl_free\ \&()

T}

T{

int

T}:T{

psl_is_public_suffix\ \&()

T}

T{

int

T}:T{

psl_is_public_suffix2\ \&()

T}

T{

const char\ \&*

T}:T{

psl_unregistrable_domain\ \&()

T}

T{

const char\ \&*

T}:T{

psl_registrable_domain\ \&()

T}

T{

int

T}:T{

psl_suffix_count\ \&()

T}

T{

int

T}:T{

psl_suffix_exception_count\ \&()

T}

T{

int

T}:T{

psl_suffix_wildcard_count\ \&()

T}

T{

time_t

T}:T{

psl_builtin_file_time\ \&()

T}

T{

const char\ \&*

T}:T{

psl_builtin_sha1sum\ \&()

T}

T{

const char\ \&*

T}:T{

psl_builtin_filename\ \&()

T}

T{

int

T}:T{

psl_builtin_outdated\ \&()

T}

T{

int

T}:T{

psl_is_cookie_domain_acceptable\ \&()

T}

T{

const char\ \&*

T}:T{

psl_dist_filename\ \&()

T}

T{

const char\ \&*

T}:T{

psl_get_version\ \&()

T}

T{

int

T}:T{

psl_check_version_number\ \&()

T}

T{

psl_error_t

T}:T{

psl_str_to_utf8lower\ \&()

T}

T{

void

T}:T{

psl_free_string\ \&()

T}

.TE

.sp 1

.SH "TYPES AND VALUES"

.TS

expand tab(:);

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l

l l.

T{

#define

T}:T{

PSL_VERSION

T}

T{

#define

T}:T{

PSL_VERSION_MAJOR

T}

T{

#define

T}:T{

PSL_VERSION_MINOR

T}

T{

#define

T}:T{

PSL_VERSION_NUMBER

T}

T{

#define

T}:T{

PSL_VERSION_PATCH

T}

T{

#define

T}:T{

PSL_TYPE_ICANN

T}

T{

#define

T}:T{

PSL_TYPE_PRIVATE

T}

T{

#define

T}:T{

PSL_TYPE_NO_STAR_RULE

T}

T{

#define

T}:T{

PSL_TYPE_ANY

T}

T{

enum

T}:T{

psl_error_t

T}

T{

typedef

T}:T{

psl_ctx_t

T}

.TE

.sp 1

.SH "INCLUDES"

.sp

.if n \{\

.RS 4

.\}

.nf

#include <libpsl\&.h>

.fi

.if n \{\

.RE

.\}

.SH "DESCRIPTION"

.PP

\m[blue]\fBPublic Suffix List\fR\m[]\&\s-2\u[1]\d\s+2

library functions\&.

.SH "FUNCTIONS"

.SS "psl_load_file\ \&()"

.sp

.if n \{\

.RS 4

.\}

.nf

psl_ctx_t\ \&*

psl_load_file (\fIconst \fR\fI\fBchar\fR\fR\fI *fname\fR);

.fi

.if n \{\

.RE

.\}

.PP

This function loads the public suffixes file named

\fIfname\fR

\&. To free the allocated resources, call

\fBpsl_free()\fR\&.

.PP

The suffixes are expected to be UTF\-8 encoded (lowercase + NFKC) if they are international\&.

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBParameters\fR

.RS 4

.TS

expand tab(:);

l l l.

T{

.PP

fname

T}:T{

.PP

Name of PSL file

T}:T{

\ \&

T}

.TE

.sp 1

.RE

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBReturns\fR

.RS 4

.PP

Pointer to a PSL context or

NULL

on failure\&.

.RE

.PP

Since:

0\&.1

.SS "psl_load_fp\ \&()"

.sp

.if n \{\

.RS 4

.\}

.nf

psl_ctx_t\ \&*

psl_load_fp (\fI\fBFILE\fR\fR\fI *fp\fR);

.fi

.if n \{\

.RE

.\}

.PP

This function loads the public suffixes from a FILE pointer\&. To free the allocated resources, call

\fBpsl_free()\fR\&.

.PP

The suffixes are expected to be UTF\-8 encoded (lowercase + NFKC) if they are international\&.

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBParameters\fR

.RS 4

.TS

expand tab(:);

l l l.

T{

.PP

fp

T}:T{

.PP

FILE pointer

T}:T{

\ \&

T}

.TE

.sp 1

.RE

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBReturns\fR

.RS 4

.PP

Pointer to a PSL context or

NULL

on failure\&.

.RE

.PP

Since:

0\&.1

.SS "psl_latest\ \&()"

.sp

.if n \{\

.RS 4

.\}

.nf

psl_ctx_t\ \&*

psl_latest (\fIconst \fR\fI\fBchar\fR\fR\fI *fname\fR);

.fi

.if n \{\

.RE

.\}

.PP

This function loads the the latest available PSL data from either

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fIfname\fR

(application specific filename, may be

NULL)

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

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

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

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

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

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

.RE

.PP

If none of the above is available, the function returns

NULL\&.

.PP

To free the allocated resources, call

\fBpsl_free()\fR\&.

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBParameters\fR

.RS 4

.TS

expand tab(:);

l l l.

T{

.PP

fname

T}:T{

.PP

Name of PSL file or

NULL

T}:T{

\ \&

T}

.TE

.sp 1

.RE

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBReturns\fR

.RS 4

.PP

Pointer to a PSL context or

NULL

on failure\&.

.RE

.PP

Since:

0\&.16

.SS "psl_builtin\ \&()"

.sp

.if n \{\

.RS 4

.\}

.nf

const psl_ctx_t\ \&*

psl_builtin (\fI\fBvoid\fR\fR);

.fi

.if n \{\

.RE

.\}

.PP

This function returns the PSL context that has been generated and built in at compile\-time\&. You don\*(Aqt have to free the returned context explicitly\&.

.PP

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

.PP

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

\fBpsl_is_public_suffix()\fR\&.

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBReturns\fR

.RS 4

.PP

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

.RE

.PP

Since:

0\&.1

.SS "psl_free\ \&()"

.sp

.if n \{\

.RS 4

.\}

.nf

void

psl_free (\fI\fBpsl_ctx_t\fR\fR\fI *psl\fR);

.fi

.if n \{\

.RE

.\}

.PP

This function frees the the PSL context that has been retrieved via

\fBpsl_load_fp()\fR

or

\fBpsl_load_file()\fR\&.

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBParameters\fR

.RS 4

.TS

expand tab(:);

l l l.

T{

.PP

psl

T}:T{

.PP

PSL context pointer

T}:T{

\ \&

T}

.TE

.sp 1

.RE

.PP

Since:

0\&.1

.SS "psl_is_public_suffix\ \&()"

.sp

.if n \{\

.RS 4

.\}

.nf

int

psl_is_public_suffix (\fIconst \fR\fI\fBpsl_ctx_t\fR\fR\fI *psl\fR,

                      \fIconst \fR\fI\fBchar\fR\fR\fI *domain\fR);

.fi

.if n \{\

.RE

.\}

.PP

This function checks if

\fIdomain\fR

is a public suffix by the means of the

\m[blue]\fBMozilla Public Suffix List\fR\m[]\&\s-2\u[2]\d\s+2\&.

.PP

For cookie domain checking see

\fBpsl_is_cookie_domain_acceptable()\fR\&.

.PP

International

\fIdomain\fR

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

\fBpsl_str_to_utf8lower()\fR

for normalization

\fIdomain\fR

\&.

.PP

\fIpsl\fR

is a context returned by either

\fBpsl_load_file()\fR,

\fBpsl_load_fp()\fR

or

\fBpsl_builtin()\fR\&.

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBParameters\fR

.RS 4

.TS

expand tab(:);

l l l

l l l.

T{

.PP

psl

T}:T{

.PP

PSL context

T}:T{

\ \&

T}

T{

.PP

domain

T}:T{

.PP

Domain string

T}:T{

\ \&

T}

.TE

.sp 1

.RE

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBReturns\fR

.RS 4

.PP

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

.RE

.PP

Since:

0\&.1

.SS "psl_is_public_suffix2\ \&()"

.sp

.if n \{\

.RS 4

.\}

.nf

int

psl_is_public_suffix2 (\fIconst \fR\fI\fBpsl_ctx_t\fR\fR\fI *psl\fR,

                       \fIconst \fR\fI\fBchar\fR\fR\fI *domain\fR,

                       \fI\fBint\fR\fR\fI type\fR);

.fi

.if n \{\

.RE

.\}

.PP

This function checks if

\fIdomain\fR

is a public suffix by the means of the

\m[blue]\fBMozilla Public Suffix List\fR\m[]\&\s-2\u[2]\d\s+2\&.

.PP

\fItype\fR

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\&.

.PP

PSL_TYPE_NO_STAR_RULE

switches of the \*(Aqprevailing star rule\*(Aq (see

\m[blue]\fBList\fR\m[]\&\s-2\u[3]\d\s+2

under \*(AqAlgorithm\*(Aq 2\&.)\&. Applying the flag means that TLDs not explicitly listed in the PSL are *not* treated as public suffixes\&.

.PP

International

\fIdomain\fR

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

\fBpsl_str_to_utf8lower()\fR

for normalization

\fIdomain\fR

\&.

.PP

\fIpsl\fR

is a context returned by either

\fBpsl_load_file()\fR,

\fBpsl_load_fp()\fR

or

\fBpsl_builtin()\fR\&.

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBParameters\fR

.RS 4

.TS

expand tab(:);

l l l

l l l

l l l.

T{

.PP

psl

T}:T{

.PP

PSL context

T}:T{

\ \&

T}

T{

.PP

domain

T}:T{

.PP

Domain string

T}:T{

\ \&

T}

T{

.PP

type

T}:T{

.PP

Domain type

T}:T{

\ \&

T}

.TE

.sp 1

.RE

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBReturns\fR

.RS 4

.PP

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

.RE

.PP

Since:

0\&.1

.SS "psl_unregistrable_domain\ \&()"

.sp

.if n \{\

.RS 4

.\}

.nf

const char\ \&*

psl_unregistrable_domain (\fIconst \fR\fI\fBpsl_ctx_t\fR\fR\fI *psl\fR,

                          \fIconst \fR\fI\fBchar\fR\fR\fI *domain\fR);

.fi

.if n \{\

.RE

.\}

.PP

This function finds the longest public suffix part of

\fIdomain\fR

by the means of the

\m[blue]\fBMozilla Public Suffix List\fR\m[]\&\s-2\u[2]\d\s+2\&.

.PP

International

\fIdomain\fR

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

\fBpsl_str_to_utf8lower()\fR

for normalization

\fIdomain\fR

\&.

.PP

\fIpsl\fR

is a context returned by either

\fBpsl_load_file()\fR,

\fBpsl_load_fp()\fR

or

\fBpsl_builtin()\fR\&.

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBParameters\fR

.RS 4

.TS

expand tab(:);

l l l

l l l.

T{

.PP

psl

T}:T{

.PP

PSL context

T}:T{

\ \&

T}

T{

.PP

domain

T}:T{

.PP

Domain string

T}:T{

\ \&

T}

.TE

.sp 1

.RE

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBReturns\fR

.RS 4

.PP

Pointer to longest public suffix part of

\fIdomain\fR

or

NULL

if

\fIdomain\fR

does not contain a public suffix (or if

\fIpsl\fR

is

NULL)\&.

.RE

.PP

Since:

0\&.1

.SS "psl_registrable_domain\ \&()"

.sp

.if n \{\

.RS 4

.\}

.nf

const char\ \&*

psl_registrable_domain (\fIconst \fR\fI\fBpsl_ctx_t\fR\fR\fI *psl\fR,

                        \fIconst \fR\fI\fBchar\fR\fR\fI *domain\fR);

.fi

.if n \{\

.RE

.\}

.PP

This function finds the shortest private suffix part of

\fIdomain\fR

by the means of the

\m[blue]\fBMozilla Public Suffix List\fR\m[]\&\s-2\u[2]\d\s+2\&.

.PP

International

\fIdomain\fR

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

\fBpsl_str_to_utf8lower()\fR

for normalization

\fIdomain\fR

\&.

.PP

\fIpsl\fR

is a context returned by either

\fBpsl_load_file()\fR,

\fBpsl_load_fp()\fR

or

\fBpsl_builtin()\fR\&.

.sp

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBParameters\fR

.RS 4

.TS

expand tab(:);

l l l

l l l.

T{

.PP

psl

T}:T{

.PP