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 Hint for Windows users: Please make sure the calling application has
444 called WSAStartup() before calling psl_is_cookie_domain_acceptable().
445 Examples:
447 1. Cookie domain 'example.com' would be acceptable for hostname
449 'www.example.com', but '.com' or 'com' would NOT be acceptable
450 since 'com' is a public suffix.
451 2. Cookie domain 'his.name' would be acceptable for hostname
453 'remember.his.name', but NOT for 'forgot.his.name' since
454 'forgot.his.name' is a public suffix.
455 Parameters
457 psl PSL
458 context
459 pointer
460 hostname The
462 request
463 hostname.
464 cookie_domain The
470 domain
471 value
472 from a
473 cookie
474 Returns
477 1 if acceptable, 0 if not acceptable.
478 Since: 0.1
480 psl_dist_filename ()
482 const char *
483 psl_dist_filename (void);
484 This function returns the file name of the distribution/system PSL data
486 file. This file will be considered by psl_latest().
487 Return the filename that is set by ./configure --with-psl-distfile, or
489 an empty string.
490 Returns
492 String containing a PSL file name or an empty string.
493 Since: 0.16
495 psl_get_version ()
497 const char *
498 psl_get_version (void);
499 Get libpsl version.
501 Returns
503 String containing version of libpsl.
504 Since: 0.2.5
506 psl_check_version_number ()
508 int
509 psl_check_version_number (int version);
510 Check the given version number is at minimum the current library
512 version number. The version number must be a hexadecimal number like
513 0x000a01 (V0.10.1).
514 Parameters
516 version Version
517 number
518 (hex) to
519 check
520 against.
521 Returns
524 Returns the library version number if the given version number is
525 at least the version of the library, else return 0; If the argument
526 is 0, the function returns the library version number without
527 performing a check.
528 Since: 0.11.0
530 psl_str_to_utf8lower ()
532 psl_error_t
533 psl_str_to_utf8lower (const char *str,
534 const char *encoding,
535 const char *locale,
536 char **lower);
537 This helper function converts a string to UTF-8 lowercase + NFKC
539 representation. Lowercase + NFKC UTF-8 is needed as input to the domain
540 checking functions.
541 lower stays unchanged on error.
543 When returning PSL_SUCCESS, the return value 'lower' must be freed
545 after usage.
546 Parameters
548 str string
549 to
550 convert
551 encoding charset
553 encoding
554 of str ,
555 e.g.
556 'iso-8859-1'
557 or NULL
558 locale locale of
560 str for to
561 lowercase
562 conversion,
563 e.g. 'de' or
564 NULL
565 lower return value
567 containing
568 the
569 converted
570 string
571 Returns
574 psl_error_t value. PSL_SUCCESS: Success PSL_ERR_INVALID_ARG: str is
575 a NULL value. PSL_ERR_CONVERTER: Failed to open the unicode
576 converter with name encoding PSL_ERR_TO_UTF16: Failed to convert
577 str to unicode PSL_ERR_TO_LOWER: Failed to convert unicode to
578 lowercase PSL_ERR_TO_UTF8: Failed to convert unicode to UTF-8
579 PSL_ERR_NO_MEM: Failed to allocate memory
580 Since: 0.4
582 psl_free_string ()
584 void
585 psl_free_string (char *str);
586 This function free()'s the memory allocated by psl_str_to_utf8lower()
588 when returning a lowercase string
589 Parameters
591 str pointer
592 to
593 lowercase
594 string
595 returned
596 by
597 psl_str_to_utf8lower()
598 Since: 0.19
601
603 PSL_API
604 # define PSL_API __attribute__ ((__visibility__("default")))
605 PSL_VERSION
607 #define PSL_VERSION "0.21.2"
608 PSL_VERSION_MAJOR
610 #define PSL_VERSION_MAJOR 0
611 PSL_VERSION_MINOR
613 #define PSL_VERSION_MINOR 21
614 PSL_VERSION_NUMBER
616 #define PSL_VERSION_NUMBER 0x001502
617 PSL_VERSION_PATCH
619 #define PSL_VERSION_PATCH 2
620 PSL_TYPE_ICANN
622 #define PSL_TYPE_ICANN (1<<0)
623 PSL_TYPE_PRIVATE
625 #define PSL_TYPE_PRIVATE (1<<1)
626 PSL_TYPE_NO_STAR_RULE
628 #define PSL_TYPE_NO_STAR_RULE (1<<2)
629 PSL_TYPE_ANY
631 #define PSL_TYPE_ANY (PSL_TYPE_ICANN | PSL_TYPE_PRIVATE)
632 enum psl_error_t
634 Return codes for PSL functions. Negative return codes mean failure.
635 Positive values are reserved for non-error return codes.
636 Members
638 PSL_SUCCESS Successful
639 return.
640 PSL_ERR_INVALID_ARG Invalid
642 argument.
643 PSL_ERR_CONVERTER Failed to
645 open
646 libicu
647 utf-16
648 converter.
649 PSL_ERR_TO_UTF16 Failed to
651 convert to
652 utf-16.
653 PSL_ERR_TO_LOWER Failed to
655 convert
656 utf-16 to
657 lowercase.
658 PSL_ERR_TO_UTF8 Failed to
660 convert
661 utf-16 to
662 utf-8.
663 PSL_ERR_NO_MEM Failed to
665 allocate
666 memory.
667 psl_ctx_t
670 typedef struct psl_ctx_st psl_ctx_t;
671
673 1. Public Suffix List
674 https://publicsuffix.org/
675 2. Mozilla Public Suffix List
677 https://publicsuffix.org
678 3. List
680 https://publicsuffix.org/list
681LIBPSL Library 07/20/2023 LIBPSL(3)