1LIBPSL(3) LIBPSL Library LIBPSL(3)
2
6 libpsl - Public Suffix List library functions
7
9 Stable, unless otherwise indicated
10
12 psl_ctx_t * psl_load_file ()
13 psl_ctx_t * psl_load_fp ()
14 psl_ctx_t * psl_latest ()
15 const psl_ctx_t * psl_builtin ()
16 void psl_free ()
17 int psl_is_public_suffix ()
18 int psl_is_public_suffix2 ()
19 const char * psl_unregistrable_domain ()
20 const char * psl_registrable_domain ()
21 int psl_suffix_count ()
22 int psl_suffix_exception_count ()
23 int psl_suffix_wildcard_count ()
24 time_t psl_builtin_file_time ()
25 const char * psl_builtin_sha1sum ()
26 const char * psl_builtin_filename ()
27 int psl_builtin_outdated ()
28 int psl_is_cookie_domain_acceptable ()
29 const char * psl_dist_filename ()
30 const char * psl_get_version ()
31 int psl_check_version_number ()
32 psl_error_t psl_str_to_utf8lower ()
33 void psl_free_string ()
34
37 #define PSL_API
38 #define PSL_VERSION
39 #define PSL_VERSION_MAJOR
40 #define PSL_VERSION_MINOR
41 #define PSL_VERSION_NUMBER
42 #define PSL_VERSION_PATCH
43 #define PSL_TYPE_ICANN
44 #define PSL_TYPE_PRIVATE
45 #define PSL_TYPE_NO_STAR_RULE
46 #define PSL_TYPE_ANY
47 enum psl_error_t
48 typedef psl_ctx_t
49
52 #include <libpsl.h>
53
55 Public Suffix List[1] library functions.
56
58 psl_load_file ()
59 psl_ctx_t *
60 psl_load_file (const char *fname);
61 This function loads the public suffixes file named fname . To free the
63 allocated resources, call psl_free().
64 The suffixes are expected to be UTF-8 encoded (lowercase + NFKC) if
66 they are international.
67 Parameters
69 fname Name of
70 PSL file
71 Returns
74 Pointer to a PSL context or NULL on failure.
75 Since: 0.1
77 psl_load_fp ()
79 psl_ctx_t *
80 psl_load_fp (FILE *fp);
81 This function loads the public suffixes from a FILE pointer. To free
83 the allocated resources, call psl_free().
84 The suffixes are expected to be UTF-8 encoded (lowercase + NFKC) if
86 they are international.
87 Parameters
89 fp FILE
90 pointer
91 Returns
94 Pointer to a PSL context or NULL on failure.
95 Since: 0.1
97 psl_latest ()
99 psl_ctx_t *
100 psl_latest (const char *fname);
101 This function loads the the latest available PSL data from either
103 • fname (application specific filename, may be NULL)
105 • location specified during built-time (filename from ./configure
107 --with-psl-distfile)
108 • built-in PSL data (generated from ./configure --with-psl-file)
110 • location of built-in data (filename from ./configure
112 --with-psl-file)
113 If none of the above is available, the function returns NULL.
115 To free the allocated resources, call psl_free().
117 Parameters
119 fname Name of
120 PSL file
121 or NULL
122 Returns
125 Pointer to a PSL context or NULL on failure.
126 Since: 0.16
128 psl_builtin ()
130 const psl_ctx_t *
131 psl_builtin (void);
132 This function returns the PSL context that has been generated and built
134 in at compile-time. You don't have to free the returned context
135 explicitly.
136 The builtin data also contains punycode entries, one for each
138 international domain name.
139 If the generation of built-in data has been disabled during
141 compilation, NULL will be returned. When using the builtin psl context,
142 you can provide UTF-8 (lowercase + NFKC) or ASCII/ACE (punycode)
143 representations of domains to functions like psl_is_public_suffix().
144 Returns
146 Pointer to the built in PSL data or NULL if this data is not
147 available.
148 Since: 0.1
150 psl_free ()
152 void
153 psl_free (psl_ctx_t *psl);
154 This function frees the the PSL context that has been retrieved via
156 psl_load_fp() or psl_load_file().
157 Parameters
159 psl PSL
160 context
161 pointer
162 Since: 0.1
165 psl_is_public_suffix ()
167 int
168 psl_is_public_suffix (const psl_ctx_t *psl,
169 const char *domain);
170 This function checks if domain is a public suffix by the means of the
172 Mozilla Public Suffix List[2].
173 For cookie domain checking see psl_is_cookie_domain_acceptable().
175 International domain names have to be either in UTF-8 (lowercase +
177 NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
178 in incorrect return values. Use helper function psl_str_to_utf8lower()
179 for normalization domain .
180 psl is a context returned by either psl_load_file(), psl_load_fp() or
182 psl_builtin().
183 Parameters
185 psl PSL
186 context
187 domain Domain
189 string
190 Returns
193 1 if domain is a public suffix, 0 if not.
194 Since: 0.1
196 psl_is_public_suffix2 ()
198 int
199 psl_is_public_suffix2 (const psl_ctx_t *psl,
200 const char *domain,
201 int type);
202 This function checks if domain is a public suffix by the means of the
204 Mozilla Public Suffix List[2].
205 type specifies the PSL section where to perform the lookup. Valid
207 values are PSL_TYPE_PRIVATE, PSL_TYPE_ICANN, PSL_TYPE_NO_STAR_RULE, and
208 PSL_TYPE_ANY.
209 PSL_TYPE_NO_STAR_RULE switches of the 'prevailing star rule' (see
211 List[3] under 'Algorithm' 2.). Applying the flag means that TLDs not
212 explicitly listed in the PSL are *not* treated as public suffixes.
213 International domain names have to be either in UTF-8 (lowercase +
215 NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
216 in incorrect return values. Use helper function psl_str_to_utf8lower()
217 for normalization domain .
218 psl is a context returned by either psl_load_file(), psl_load_fp() or
220 psl_builtin().
221 Parameters
223 psl PSL
224 context
225 domain Domain
227 string
228 type Domain
230 type
231 Returns
234 1 if domain is a public suffix, 0 if not.
235 Since: 0.1
237 psl_unregistrable_domain ()
239 const char *
240 psl_unregistrable_domain (const psl_ctx_t *psl,
241 const char *domain);
242 This function finds the longest public suffix part of domain by the
244 means of the Mozilla Public Suffix List[2].
245 International domain names have to be either in UTF-8 (lowercase +
247 NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
248 in incorrect return values. Use helper function psl_str_to_utf8lower()
249 for normalization domain .
250 psl is a context returned by either psl_load_file(), psl_load_fp() or
252 psl_builtin().
253 Parameters
255 psl PSL
256 context
257 domain Domain
259 string
260 Returns
263 Pointer to longest public suffix part of domain or NULL if domain
264 does not contain a public suffix (or if psl is NULL).
265 Since: 0.1
267 psl_registrable_domain ()
269 const char *
270 psl_registrable_domain (const psl_ctx_t *psl,
271 const char *domain);
272 This function finds the shortest private suffix part of domain by the
274 means of the Mozilla Public Suffix List[2].
275 International domain names have to be either in UTF-8 (lowercase +
277 NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
278 in incorrect return values. Use helper function psl_str_to_utf8lower()
279 for normalization domain .
280 psl is a context returned by either psl_load_file(), psl_load_fp() or
282 psl_builtin().
283 Parameters
285 psl PSL
286 context
287 domain Domain
289 string
290 Returns
293 Pointer to shortest private suffix part of domain or NULL if domain
294 does not contain a private suffix (or if psl is NULL).
295 Since: 0.1
297 psl_suffix_count ()
299 int
300 psl_suffix_count (const psl_ctx_t *psl);
301 This function returns number of public suffixes maintained by psl . The
303 number of exceptions within the Public Suffix List are not included.
304 If the information is not available, the return value is -1 (since
306 0.19). This is the case with DAFSA blobs or if psl is NULL.
307 Parameters
309 psl PSL
310 context
311 pointer
312 Returns
315 Number of public suffixes entries in PSL context or -1 if this
316 information is not available.
317 Since: 0.1
319 psl_suffix_exception_count ()
321 int
322 psl_suffix_exception_count (const psl_ctx_t *psl);
323 This function returns number of public suffix exceptions maintained by
325 psl .
326 If the information is not available, the return value is -1 (since
328 0.19). This is the case with DAFSA blobs or if psl is NULL.
329 Parameters
331 psl PSL
332 context
333 pointer
334 Returns
337 Number of public suffix exceptions in PSL context or -1 if this
338 information is not available.
339 Since: 0.1
341 psl_suffix_wildcard_count ()
343 int
344 psl_suffix_wildcard_count (const psl_ctx_t *psl);
345 This function returns number of public suffix wildcards maintained by
347 psl .
348 If the information is not available, the return value is -1 (since
350 0.19). This is the case with DAFSA blobs or if psl is NULL.
351 Parameters
353 psl PSL
354 context
355 pointer
356 Returns
359 Number of public suffix wildcards in PSL context or -1 if this
360 information is not available.
361 Since: 0.10.0
363 psl_builtin_file_time ()
365 time_t
366 psl_builtin_file_time (void);
367 This function returns the mtime of the Public Suffix List file that has
369 been built in.
370 If the generation of built-in data has been disabled during
372 compilation, 0 will be returned.
373 Returns
375 time_t value or 0.
376 Since: 0.1
378 psl_builtin_sha1sum ()
380 const char *
381 psl_builtin_sha1sum (void);
382 This function returns the SHA1 checksum of the Public Suffix List file
384 that has been built in. The returned string is in lowercase hex
385 encoding, e.g. "2af1e9e3044eda0678bb05949d7cca2f769901d8".
386 If the generation of built-in data has been disabled during
388 compilation, an empty string will be returned.
389 Returns
391 String containing SHA1 checksum or an empty string.
392 Since: 0.1
394 psl_builtin_filename ()
396 const char *
397 psl_builtin_filename (void);
398 This function returns the file name of the Public Suffix List file that
400 has been built in.
401 If the generation of built-in data has been disabled during
403 compilation, an empty string will be returned.
404 Returns
406 String containing the PSL file name or an empty string.
407 Since: 0.1
409 psl_builtin_outdated ()
411 int
412 psl_builtin_outdated (void);
413 This function checks if the built-in data is older than the file it has
415 been created from. If it is, it might be a good idea for the
416 application to reload the PSL. The mtime is taken as reference.
417 If the PSL file does not exist, it is assumed that the built-in data is
419 not outdated.
420 Returns
422 1 if the built-in is outdated, 0 otherwise.
423 Since: 0.10.0
425 psl_is_cookie_domain_acceptable ()
427 int
428 psl_is_cookie_domain_acceptable (const psl_ctx_t *psl,
429 const char *hostname,
430 const char *cookie_domain);
431 This helper function checks whether cookie_domain is an acceptable
433 cookie domain value for the request hostname .
434 For international domain names both, hostname and cookie_domain , have
436 to be either in UTF-8 (lowercase + NFKC) or in ASCII/ACE (punycode)
437 format. Other encodings or mixing UTF-8 and punycode likely result in
438 incorrect return values.
439 Use helper function psl_str_to_utf8lower() for normalization of
441 hostname and cookie_domain .
442 Examples:
444 1. Cookie domain 'example.com' would be acceptable for hostname
446 'www.example.com', but '.com' or 'com' would NOT be acceptable
447 since 'com' is a public suffix.
448 2. Cookie domain 'his.name' would be acceptable for hostname
450 'remember.his.name', but NOT for 'forgot.his.name' since
451 'forgot.his.name' is a public suffix.
452 Parameters
454 psl PSL
455 context
456 pointer
457 hostname The
459 request
460 hostname.
461 cookie_domain The
463 domain
464 value
465 from a
466 cookie
467 Returns
470 1 if acceptable, 0 if not acceptable.
471 Since: 0.1
473 psl_dist_filename ()
475 const char *
476 psl_dist_filename (void);
477 This function returns the file name of the distribution/system PSL data
479 file. This file will be considered by psl_latest().
480 Return the filename that is set by ./configure --with-psl-distfile, or
482 an empty string.
483 Returns
485 String containing a PSL file name or an empty string.
486 Since: 0.16
488 psl_get_version ()
490 const char *
491 psl_get_version (void);
492 Get libpsl version.
494 Returns
496 String containing version of libpsl.
497 Since: 0.2.5
499 psl_check_version_number ()
501 int
502 psl_check_version_number (int version);
503 Check the given version number is at minimum the current library
505 version number. The version number must be a hexadecimal number like
506 0x000a01 (V0.10.1).
507 Parameters
509 version Version
510 number
511 (hex) to
512 check
513 against.
514 Returns
517 Returns the library version number if the given version number is
518 at least the version of the library, else return 0; If the argument
519 is 0, the function returns the library version number without
520 performing a check.
521 Since: 0.11.0
523 psl_str_to_utf8lower ()
525 psl_error_t
526 psl_str_to_utf8lower (const char *str,
527 const char *encoding,
528 const char *locale,
529 char **lower);
530 This helper function converts a string to UTF-8 lowercase + NFKC
532 representation. Lowercase + NFKC UTF-8 is needed as input to the domain
533 checking functions.
534 lower stays unchanged on error.
536 When returning PSL_SUCCESS, the return value 'lower' must be freed
538 after usage.
539 Parameters
541 str string
542 to
543 convert
544 encoding charset
546 encoding
547 of str ,
548 e.g.
549 'iso-8859-1'
550 or NULL
551 locale locale of
553 str for to
554 lowercase
555 conversion,
556 e.g. 'de' or
557 NULL
558 lower return value
560 containing
561 the
562 converted
563 string
564 Returns
567 psl_error_t value. PSL_SUCCESS: Success PSL_ERR_INVALID_ARG: str is
568 a NULL value. PSL_ERR_CONVERTER: Failed to open the unicode
569 converter with name encoding PSL_ERR_TO_UTF16: Failed to convert
570 str to unicode PSL_ERR_TO_LOWER: Failed to convert unicode to
571 lowercase PSL_ERR_TO_UTF8: Failed to convert unicode to UTF-8
572 PSL_ERR_NO_MEM: Failed to allocate memory
573 Since: 0.4
575 psl_free_string ()
577 void
578 psl_free_string (char *str);
579 This function free()'s the memory allocated by psl_str_to_utf8lower()
581 when returning a lowercase string
582 Parameters
584 str pointer
585 to
586 lowercase
587 string
588 returned
589 by
590 psl_str_to_utf8lower()
591 Since: 0.19
594
596 PSL_API
597 # define PSL_API __attribute__ ((__visibility__("default")))
598 PSL_VERSION
600 #define PSL_VERSION "0.21.1"
601 PSL_VERSION_MAJOR
603 #define PSL_VERSION_MAJOR 0
604 PSL_VERSION_MINOR
606 #define PSL_VERSION_MINOR 21
607 PSL_VERSION_NUMBER
609 #define PSL_VERSION_NUMBER 0x001501
610 PSL_VERSION_PATCH
612 #define PSL_VERSION_PATCH 1
613 PSL_TYPE_ICANN
615 #define PSL_TYPE_ICANN (1<<0)
616 PSL_TYPE_PRIVATE
618 #define PSL_TYPE_PRIVATE (1<<1)
619 PSL_TYPE_NO_STAR_RULE
621 #define PSL_TYPE_NO_STAR_RULE (1<<2)
622 PSL_TYPE_ANY
624 #define PSL_TYPE_ANY (PSL_TYPE_ICANN | PSL_TYPE_PRIVATE)
625 enum psl_error_t
627 Return codes for PSL functions. Negative return codes mean failure.
628 Positive values are reserved for non-error return codes.
629 Members
631 PSL_SUCCESS Successful
632 return.
633 PSL_ERR_INVALID_ARG Invalid
635 argument.
636 PSL_ERR_CONVERTER Failed to
638 open
639 libicu
640 utf-16
641 converter.
642 PSL_ERR_TO_UTF16 Failed to
644 convert to
645 utf-16.
646 PSL_ERR_TO_LOWER Failed to
648 convert
649 utf-16 to
650 lowercase.
651 PSL_ERR_TO_UTF8 Failed to
653 convert
654 utf-16 to
655 utf-8.
656 PSL_ERR_NO_MEM Failed to
658 allocate
659 memory.
660 psl_ctx_t
663 typedef struct psl_ctx_st psl_ctx_t;
664
666 1. Public Suffix List
667 https://publicsuffix.org/
668 2. Mozilla Public Suffix List
670 https://publicsuffix.org
671 3. List
673 https://publicsuffix.org/list
674LIBPSL Library 07/21/2022 LIBPSL(3)