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_VERSION
38 #define PSL_VERSION_MAJOR
39 #define PSL_VERSION_MINOR
40 #define PSL_VERSION_NUMBER
41 #define PSL_VERSION_PATCH
42 #define PSL_TYPE_ICANN
43 #define PSL_TYPE_PRIVATE
44 #define PSL_TYPE_NO_STAR_RULE
45 #define PSL_TYPE_ANY
46 enum psl_error_t
47 typedef psl_ctx_t
48
51 #include <libpsl.h>
52
54 Public Suffix List[1] library functions.
55
57 psl_load_file ()
58 psl_ctx_t *
59 psl_load_file (const char *fname);
60 This function loads the public suffixes file named fname . To free the
62 allocated resources, call psl_free().
63 The suffixes are expected to be UTF-8 encoded (lowercase + NFKC) if
65 they are international.
66 Parameters
68 fname Name of
69 PSL file
70 Returns
73 Pointer to a PSL context or NULL on failure.
74 Since: 0.1
76 psl_load_fp ()
78 psl_ctx_t *
79 psl_load_fp (FILE *fp);
80 This function loads the public suffixes from a FILE pointer. To free
82 the allocated resources, call psl_free().
83 The suffixes are expected to be UTF-8 encoded (lowercase + NFKC) if
85 they are international.
86 Parameters
88 fp FILE
89 pointer
90 Returns
93 Pointer to a PSL context or NULL on failure.
94 Since: 0.1
96 psl_latest ()
98 psl_ctx_t *
99 psl_latest (const char *fname);
100 This function loads the the latest available PSL data from either
102 · fname (application specific filename, may be NULL)
104 · location specified during built-time (filename from ./configure
106 --with-psl-distfile)
107 · built-in PSL data (generated from ./configure --with-psl-file)
109 · location of built-in data (filename from ./configure
111 --with-psl-file)
112 If none of the above is available, the function returns NULL.
114 To free the allocated resources, call psl_free().
116 Parameters
118 fname Name of
119 PSL file
120 or NULL
121 Returns
124 Pointer to a PSL context or NULL on failure.
125 Since: 0.16
127 psl_builtin ()
129 const psl_ctx_t *
130 psl_builtin (void);
131 This function returns the PSL context that has been generated and built
133 in at compile-time. You don't have to free the returned context
134 explicitly.
135 The builtin data also contains punycode entries, one for each
137 international domain name.
138 If the generation of built-in data has been disabled during
140 compilation, NULL will be returned. When using the builtin psl context,
141 you can provide UTF-8 (lowercase + NFKC) or ASCII/ACE (punycode)
142 representations of domains to functions like psl_is_public_suffix().
143 Returns
145 Pointer to the built in PSL data or NULL if this data is not
146 available.
147 Since: 0.1
149 psl_free ()
151 void
152 psl_free (psl_ctx_t *psl);
153 This function frees the the PSL context that has been retrieved via
155 psl_load_fp() or psl_load_file().
156 Parameters
158 psl PSL
159 context
160 pointer
161 Since: 0.1
164 psl_is_public_suffix ()
166 int
167 psl_is_public_suffix (const psl_ctx_t *psl,
168 const char *domain);
169 This function checks if domain is a public suffix by the means of the
171 Mozilla Public Suffix List[2].
172 For cookie domain checking see psl_is_cookie_domain_acceptable().
174 International domain names have to be either in UTF-8 (lowercase +
176 NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
177 in incorrect return values. Use helper function psl_str_to_utf8lower()
178 for normalization domain .
179 psl is a context returned by either psl_load_file(), psl_load_fp() or
181 psl_builtin().
182 Parameters
184 psl PSL
185 context
186 domain Domain
188 string
189 Returns
192 1 if domain is a public suffix, 0 if not.
193 Since: 0.1
195 psl_is_public_suffix2 ()
197 int
198 psl_is_public_suffix2 (const psl_ctx_t *psl,
199 const char *domain,
200 int type);
201 This function checks if domain is a public suffix by the means of the
203 Mozilla Public Suffix List[2].
204 type specifies the PSL section where to perform the lookup. Valid
206 values are PSL_TYPE_PRIVATE, PSL_TYPE_ICANN, PSL_TYPE_NO_STAR_RULE, and
207 PSL_TYPE_ANY.
208 PSL_TYPE_NO_STAR_RULE switches of the 'prevailing star rule' (see
210 List[3] under 'Algorithm' 2.). Applying the flag means that TLDs not
211 explicitly listed in the PSL are *not* treated as public suffixes.
212 International domain names have to be either in UTF-8 (lowercase +
214 NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
215 in incorrect return values. Use helper function psl_str_to_utf8lower()
216 for normalization domain .
217 psl is a context returned by either psl_load_file(), psl_load_fp() or
219 psl_builtin().
220 Parameters
222 psl PSL
223 context
224 domain Domain
226 string
227 type Domain
229 type
230 Returns
233 1 if domain is a public suffix, 0 if not.
234 Since: 0.1
236 psl_unregistrable_domain ()
238 const char *
239 psl_unregistrable_domain (const psl_ctx_t *psl,
240 const char *domain);
241 This function finds the longest public suffix part of domain by the
243 means of the Mozilla Public Suffix List[2].
244 International domain names have to be either in UTF-8 (lowercase +
246 NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
247 in incorrect return values. Use helper function psl_str_to_utf8lower()
248 for normalization domain .
249 psl is a context returned by either psl_load_file(), psl_load_fp() or
251 psl_builtin().
252 Parameters
254 psl PSL
255 context
256 domain Domain
258 string
259 Returns
262 Pointer to longest public suffix part of domain or NULL if domain
263 does not contain a public suffix (or if psl is NULL).
264 Since: 0.1
266 psl_registrable_domain ()
268 const char *
269 psl_registrable_domain (const psl_ctx_t *psl,
270 const char *domain);
271 This function finds the shortest private suffix part of domain by the
273 means of the Mozilla Public Suffix List[2].
274 International domain names have to be either in UTF-8 (lowercase +
276 NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
277 in incorrect return values. Use helper function psl_str_to_utf8lower()
278 for normalization domain .
279 psl is a context returned by either psl_load_file(), psl_load_fp() or
281 psl_builtin().
282 Parameters
284 psl PSL
285 context
286 domain Domain
288 string
289 Returns
292 Pointer to shortest private suffix part of domain or NULL if domain
293 does not contain a private suffix (or if psl is NULL).
294 Since: 0.1
296 psl_suffix_count ()
298 int
299 psl_suffix_count (const psl_ctx_t *psl);
300 This function returns number of public suffixes maintained by psl . The
302 number of exceptions within the Public Suffix List are not included.
303 If the information is not available, the return value is -1 (since
305 0.19). This is the case with DAFSA blobs or if psl is NULL.
306 Parameters
308 psl PSL
309 context
310 pointer
311 Returns
314 Number of public suffixes entries in PSL context or -1 if this
315 information is not available.
316 Since: 0.1
318 psl_suffix_exception_count ()
320 int
321 psl_suffix_exception_count (const psl_ctx_t *psl);
322 This function returns number of public suffix exceptions maintained by
324 psl .
325 If the information is not available, the return value is -1 (since
327 0.19). This is the case with DAFSA blobs or if psl is NULL.
328 Parameters
330 psl PSL
331 context
332 pointer
333 Returns
336 Number of public suffix exceptions in PSL context or -1 if this
337 information is not available.
338 Since: 0.1
340 psl_suffix_wildcard_count ()
342 int
343 psl_suffix_wildcard_count (const psl_ctx_t *psl);
344 This function returns number of public suffix wildcards maintained by
346 psl .
347 If the information is not available, the return value is -1 (since
349 0.19). This is the case with DAFSA blobs or if psl is NULL.
350 Parameters
352 psl PSL
353 context
354 pointer
355 Returns
358 Number of public suffix wildcards in PSL context or -1 if this
359 information is not available.
360 Since: 0.10.0
362 psl_builtin_file_time ()
364 time_t
365 psl_builtin_file_time (void);
366 This function returns the mtime of the Public Suffix List file that has
368 been built in.
369 If the generation of built-in data has been disabled during
371 compilation, 0 will be returned.
372 Returns
374 time_t value or 0.
375 Since: 0.1
377 psl_builtin_sha1sum ()
379 const char *
380 psl_builtin_sha1sum (void);
381 This function returns the SHA1 checksum of the Public Suffix List file
383 that has been built in. The returned string is in lowercase hex
384 encoding, e.g. "2af1e9e3044eda0678bb05949d7cca2f769901d8".
385 If the generation of built-in data has been disabled during
387 compilation, an empty string will be returned.
388 Returns
390 String containing SHA1 checksum or an empty string.
391 Since: 0.1
393 psl_builtin_filename ()
395 const char *
396 psl_builtin_filename (void);
397 This function returns the file name of the Public Suffix List file that
399 has been built in.
400 If the generation of built-in data has been disabled during
402 compilation, an empty string will be returned.
403 Returns
405 String containing the PSL file name or an empty string.
406 Since: 0.1
408 psl_builtin_outdated ()
410 int
411 psl_builtin_outdated (void);
412 This function checks if the built-in data is older than the file it has
414 been created from. If it is, it might be a good idea for the
415 application to reload the PSL. The mtime is taken as reference.
416 If the PSL file does not exist, it is assumed that the built-in data is
418 not outdated.
419 Returns
421 1 if the built-in is outdated, 0 otherwise.
422 Since: 0.10.0
424 psl_is_cookie_domain_acceptable ()
426 int
427 psl_is_cookie_domain_acceptable (const psl_ctx_t *psl,
428 const char *hostname,
429 const char *cookie_domain);
430 This helper function checks whether cookie_domain is an acceptable
432 cookie domain value for the request hostname .
433 For international domain names both, hostname and cookie_domain , have
435 to be either in UTF-8 (lowercase + NFKC) or in ASCII/ACE (punycode)
436 format. Other encodings or mixing UTF-8 and punycode likely result in
437 incorrect return values.
438 Use helper function psl_str_to_utf8lower() for normalization of
440 hostname and cookie_domain .
441 Examples:
443 1. Cookie domain 'example.com' would be acceptable for hostname
445 'www.example.com', but '.com' or 'com' would NOT be acceptable
446 since 'com' is a public suffix.
447 2. Cookie domain 'his.name' would be acceptable for hostname
449 'remember.his.name', but NOT for 'forgot.his.name' since
450 'forgot.his.name' is a public suffix.
451 Parameters
453 psl PSL
454 context
455 pointer
456 hostname The
458 request
459 hostname.
460 cookie_domain The
467 domain
468 value
469 from a
470 cookie
471 Returns
474 1 if acceptable, 0 if not acceptable.
475 Since: 0.1
477 psl_dist_filename ()
479 const char *
480 psl_dist_filename (void);
481 This function returns the file name of the distribution/system PSL data
483 file. This file will be considered by psl_latest().
484 Return the filename that is set by ./configure --with-psl-distfile, or
486 an empty string.
487 Returns
489 String containing a PSL file name or an empty string.
490 Since: 0.16
492 psl_get_version ()
494 const char *
495 psl_get_version (void);
496 Get libpsl version.
498 Returns
500 String containing version of libpsl.
501 Since: 0.2.5
503 psl_check_version_number ()
505 int
506 psl_check_version_number (int version);
507 Check the given version number is at minimum the current library
509 version number. The version number must be a hexadecimal number like
510 0x000a01 (V0.10.1).
511 Parameters
513 version Version
514 number
515 (hex) to
516 check
517 against.
518 Returns
521 Returns the library version number if the given version number is
522 at least the version of the library, else return 0; If the argument
523 is 0, the function returns the library version number without
524 performing a check.
525 Since: 0.11.0
527 psl_str_to_utf8lower ()
529 psl_error_t
530 psl_str_to_utf8lower (const char *str,
531 const char *encoding,
532 const char *locale,
533 char **lower);
534 This helper function converts a string to UTF-8 lowercase + NFKC
536 representation. Lowercase + NFKC UTF-8 is needed as input to the domain
537 checking functions.
538 lower stays unchanged on error.
540 When returning PSL_SUCCESS, the return value 'lower' must be freed
542 after usage.
543 Parameters
545 str string
546 to
547 convert
548 encoding charset
550 encoding
551 of str ,
552 e.g.
553 'iso-8859-1'
554 or NULL
555 locale locale of
557 str for to
558 lowercase
559 conversion,
560 e.g. 'de' or
561 NULL
562 lower return value
564 containing
565 the
566 converted
567 string
568 Returns
571 psl_error_t value. PSL_SUCCESS: Success PSL_ERR_INVALID_ARG: str is
572 a NULL value. PSL_ERR_CONVERTER: Failed to open the unicode
573 converter with name encoding PSL_ERR_TO_UTF16: Failed to convert
574 str to unicode PSL_ERR_TO_LOWER: Failed to convert unicode to
575 lowercase PSL_ERR_TO_UTF8: Failed to convert unicode to UTF-8
576 PSL_ERR_NO_MEM: Failed to allocate memory
577 Since: 0.4
579 psl_free_string ()
581 void
582 psl_free_string (char *str);
583 This function free()'s the memory allocated by psl_str_to_utf8lower()
585 when returning a lowercase string
586 Parameters
588 str pointer
589 to
590 lowercase
591 string
592 returned
593 by
594 psl_str_to_utf8lower()
595 Since: 0.19
598
600 PSL_VERSION
601 #define PSL_VERSION "0.21.0"
602 PSL_VERSION_MAJOR
604 #define PSL_VERSION_MAJOR 0
605 PSL_VERSION_MINOR
607 #define PSL_VERSION_MINOR 21
608 PSL_VERSION_NUMBER
610 #define PSL_VERSION_NUMBER 0x001500
611 PSL_VERSION_PATCH
613 #define PSL_VERSION_PATCH 0
614 PSL_TYPE_ICANN
616 #define PSL_TYPE_ICANN (1<<0)
617 PSL_TYPE_PRIVATE
619 #define PSL_TYPE_PRIVATE (1<<1)
620 PSL_TYPE_NO_STAR_RULE
622 #define PSL_TYPE_NO_STAR_RULE (1<<2)
623 PSL_TYPE_ANY
625 #define PSL_TYPE_ANY (PSL_TYPE_ICANN | PSL_TYPE_PRIVATE)
626 enum psl_error_t
628 Return codes for PSL functions. Negative return codes mean failure.
629 Positive values are reserved for non-error return codes.
630 Members
632 PSL_SUCCESS Successful
633 return.
634 PSL_ERR_INVALID_ARG Invalid
636 argument.
637 PSL_ERR_CONVERTER Failed to
639 open
640 libicu
641 utf-16
642 converter.
643 PSL_ERR_TO_UTF16 Failed to
645 convert to
646 utf-16.
647 PSL_ERR_TO_LOWER Failed to
649 convert
650 utf-16 to
651 lowercase.
652 PSL_ERR_TO_UTF8 Failed to
654 convert
655 utf-16 to
656 utf-8.
657 PSL_ERR_NO_MEM Failed to
659 allocate
660 memory.
661 psl_ctx_t
664 typedef struct psl_ctx_st psl_ctx_t;
665
667 1. Public Suffix List
668 https://publicsuffix.org/
669 2. Mozilla Public Suffix List
671 https://publicsuffix.org
672 3. List
674 https://publicsuffix.org/list
675LIBPSL Library 07/25/2019 LIBPSL(3)