1LIBPSL(3) LIBPSL Library LIBPSL(3)
2
3
4
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
35
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
50
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
62 This function loads the public suffixes file named fname . To free the
63 allocated resources, call psl_free().
64
65 The suffixes are expected to be UTF-8 encoded (lowercase + NFKC) if
66 they are international.
67
68 Parameters
69 fname Name of
70 PSL file
71
72
73 Returns
74 Pointer to a PSL context or NULL on failure.
75
76 Since: 0.1
77
78 psl_load_fp ()
79 psl_ctx_t *
80 psl_load_fp (FILE *fp);
81
82 This function loads the public suffixes from a FILE pointer. To free
83 the allocated resources, call psl_free().
84
85 The suffixes are expected to be UTF-8 encoded (lowercase + NFKC) if
86 they are international.
87
88 Parameters
89 fp FILE
90 pointer
91
92
93 Returns
94 Pointer to a PSL context or NULL on failure.
95
96 Since: 0.1
97
98 psl_latest ()
99 psl_ctx_t *
100 psl_latest (const char *fname);
101
102 This function loads the the latest available PSL data from either
103
104 • fname (application specific filename, may be NULL)
105
106 • location specified during built-time (filename from ./configure
107 --with-psl-distfile)
108
109 • built-in PSL data (generated from ./configure --with-psl-file)
110
111 • location of built-in data (filename from ./configure
112 --with-psl-file)
113
114 If none of the above is available, the function returns NULL.
115
116 To free the allocated resources, call psl_free().
117
118 Parameters
119 fname Name of
120 PSL file
121 or NULL
122
123
124 Returns
125 Pointer to a PSL context or NULL on failure.
126
127 Since: 0.16
128
129 psl_builtin ()
130 const psl_ctx_t *
131 psl_builtin (void);
132
133 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
137 The builtin data also contains punycode entries, one for each
138 international domain name.
139
140 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
145 Returns
146 Pointer to the built in PSL data or NULL if this data is not
147 available.
148
149 Since: 0.1
150
151 psl_free ()
152 void
153 psl_free (psl_ctx_t *psl);
154
155 This function frees the the PSL context that has been retrieved via
156 psl_load_fp() or psl_load_file().
157
158 Parameters
159 psl PSL
160 context
161 pointer
162
163
164 Since: 0.1
165
166 psl_is_public_suffix ()
167 int
168 psl_is_public_suffix (const psl_ctx_t *psl,
169 const char *domain);
170
171 This function checks if domain is a public suffix by the means of the
172 Mozilla Public Suffix List[2].
173
174 For cookie domain checking see psl_is_cookie_domain_acceptable().
175
176 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
181 psl is a context returned by either psl_load_file(), psl_load_fp() or
182 psl_builtin().
183
184 Parameters
185 psl PSL
186 context
187
188 domain Domain
189 string
190
191
192 Returns
193 1 if domain is a public suffix, 0 if not.
194
195 Since: 0.1
196
197 psl_is_public_suffix2 ()
198 int
199 psl_is_public_suffix2 (const psl_ctx_t *psl,
200 const char *domain,
201 int type);
202
203 This function checks if domain is a public suffix by the means of the
204 Mozilla Public Suffix List[2].
205
206 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
210 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
214 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
219 psl is a context returned by either psl_load_file(), psl_load_fp() or
220 psl_builtin().
221
222 Parameters
223 psl PSL
224 context
225
226 domain Domain
227 string
228
229 type Domain
230 type
231
232
233 Returns
234 1 if domain is a public suffix, 0 if not.
235
236 Since: 0.1
237
238 psl_unregistrable_domain ()
239 const char *
240 psl_unregistrable_domain (const psl_ctx_t *psl,
241 const char *domain);
242
243 This function finds the longest public suffix part of domain by the
244 means of the Mozilla Public Suffix List[2].
245
246 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
251 psl is a context returned by either psl_load_file(), psl_load_fp() or
252 psl_builtin().
253
254 Parameters
255 psl PSL
256 context
257
258 domain Domain
259 string
260
261
262 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
266 Since: 0.1
267
268 psl_registrable_domain ()
269 const char *
270 psl_registrable_domain (const psl_ctx_t *psl,
271 const char *domain);
272
273 This function finds the shortest private suffix part of domain by the
274 means of the Mozilla Public Suffix List[2].
275
276 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
281 psl is a context returned by either psl_load_file(), psl_load_fp() or
282 psl_builtin().
283
284 Parameters
285 psl PSL
286 context
287
288 domain Domain
289 string
290
291
292 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
296 Since: 0.1
297
298 psl_suffix_count ()
299 int
300 psl_suffix_count (const psl_ctx_t *psl);
301
302 This function returns number of public suffixes maintained by psl . The
303 number of exceptions within the Public Suffix List are not included.
304
305 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
308 Parameters
309 psl PSL
310 context
311 pointer
312
313
314 Returns
315 Number of public suffixes entries in PSL context or -1 if this
316 information is not available.
317
318 Since: 0.1
319
320 psl_suffix_exception_count ()
321 int
322 psl_suffix_exception_count (const psl_ctx_t *psl);
323
324 This function returns number of public suffix exceptions maintained by
325 psl .
326
327 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
330 Parameters
331 psl PSL
332 context
333 pointer
334
335
336 Returns
337 Number of public suffix exceptions in PSL context or -1 if this
338 information is not available.
339
340 Since: 0.1
341
342 psl_suffix_wildcard_count ()
343 int
344 psl_suffix_wildcard_count (const psl_ctx_t *psl);
345
346 This function returns number of public suffix wildcards maintained by
347 psl .
348
349 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
352 Parameters
353 psl PSL
354 context
355 pointer
356
357
358 Returns
359 Number of public suffix wildcards in PSL context or -1 if this
360 information is not available.
361
362 Since: 0.10.0
363
364 psl_builtin_file_time ()
365 time_t
366 psl_builtin_file_time (void);
367
368 This function returns the mtime of the Public Suffix List file that has
369 been built in.
370
371 If the generation of built-in data has been disabled during
372 compilation, 0 will be returned.
373
374 Returns
375 time_t value or 0.
376
377 Since: 0.1
378
379 psl_builtin_sha1sum ()
380 const char *
381 psl_builtin_sha1sum (void);
382
383 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
387 If the generation of built-in data has been disabled during
388 compilation, an empty string will be returned.
389
390 Returns
391 String containing SHA1 checksum or an empty string.
392
393 Since: 0.1
394
395 psl_builtin_filename ()
396 const char *
397 psl_builtin_filename (void);
398
399 This function returns the file name of the Public Suffix List file that
400 has been built in.
401
402 If the generation of built-in data has been disabled during
403 compilation, an empty string will be returned.
404
405 Returns
406 String containing the PSL file name or an empty string.
407
408 Since: 0.1
409
410 psl_builtin_outdated ()
411 int
412 psl_builtin_outdated (void);
413
414 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
418 If the PSL file does not exist, it is assumed that the built-in data is
419 not outdated.
420
421 Returns
422 1 if the built-in is outdated, 0 otherwise.
423
424 Since: 0.10.0
425
426 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
432 This helper function checks whether cookie_domain is an acceptable
433 cookie domain value for the request hostname .
434
435 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
440 Use helper function psl_str_to_utf8lower() for normalization of
441 hostname and cookie_domain .
442
443 Examples:
444
445 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
449 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
453 Parameters
454 psl PSL
455 context
456 pointer
457
458 hostname The
459 request
460 hostname.
461
462 cookie_domain The
463 domain
464 value
465 from a
466 cookie
467
468
469 Returns
470 1 if acceptable, 0 if not acceptable.
471
472 Since: 0.1
473
474 psl_dist_filename ()
475 const char *
476 psl_dist_filename (void);
477
478 This function returns the file name of the distribution/system PSL data
479 file. This file will be considered by psl_latest().
480
481 Return the filename that is set by ./configure --with-psl-distfile, or
482 an empty string.
483
484 Returns
485 String containing a PSL file name or an empty string.
486
487 Since: 0.16
488
489 psl_get_version ()
490 const char *
491 psl_get_version (void);
492
493 Get libpsl version.
494
495 Returns
496 String containing version of libpsl.
497
498 Since: 0.2.5
499
500 psl_check_version_number ()
501 int
502 psl_check_version_number (int version);
503
504 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
508 Parameters
509 version Version
510 number
511 (hex) to
512 check
513 against.
514
515
516 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
522 Since: 0.11.0
523
524 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
531 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
535 lower stays unchanged on error.
536
537 When returning PSL_SUCCESS, the return value 'lower' must be freed
538 after usage.
539
540 Parameters
541 str string
542 to
543 convert
544
545 encoding charset
546 encoding
547 of str ,
548 e.g.
549 'iso-8859-1'
550 or NULL
551
552 locale locale of
553 str for to
554 lowercase
555 conversion,
556 e.g. 'de' or
557 NULL
558
559 lower return value
560 containing
561 the
562 converted
563 string
564
565
566 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
574 Since: 0.4
575
576 psl_free_string ()
577 void
578 psl_free_string (char *str);
579
580 This function free()'s the memory allocated by psl_str_to_utf8lower()
581 when returning a lowercase string
582
583 Parameters
584 str pointer
585 to
586 lowercase
587 string
588 returned
589 by
590 psl_str_to_utf8lower()
591
592
593 Since: 0.19
594
596 PSL_API
597 # define PSL_API __attribute__ ((__visibility__("default")))
598
599 PSL_VERSION
600 #define PSL_VERSION "0.21.1"
601
602 PSL_VERSION_MAJOR
603 #define PSL_VERSION_MAJOR 0
604
605 PSL_VERSION_MINOR
606 #define PSL_VERSION_MINOR 21
607
608 PSL_VERSION_NUMBER
609 #define PSL_VERSION_NUMBER 0x001501
610
611 PSL_VERSION_PATCH
612 #define PSL_VERSION_PATCH 1
613
614 PSL_TYPE_ICANN
615 #define PSL_TYPE_ICANN (1<<0)
616
617 PSL_TYPE_PRIVATE
618 #define PSL_TYPE_PRIVATE (1<<1)
619
620 PSL_TYPE_NO_STAR_RULE
621 #define PSL_TYPE_NO_STAR_RULE (1<<2)
622
623 PSL_TYPE_ANY
624 #define PSL_TYPE_ANY (PSL_TYPE_ICANN | PSL_TYPE_PRIVATE)
625
626 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
630 Members
631 PSL_SUCCESS Successful
632 return.
633
634 PSL_ERR_INVALID_ARG Invalid
635 argument.
636
637 PSL_ERR_CONVERTER Failed to
638 open
639 libicu
640 utf-16
641 converter.
642
643 PSL_ERR_TO_UTF16 Failed to
644 convert to
645 utf-16.
646
647 PSL_ERR_TO_LOWER Failed to
648 convert
649 utf-16 to
650 lowercase.
651
652 PSL_ERR_TO_UTF8 Failed to
653 convert
654 utf-16 to
655 utf-8.
656
657 PSL_ERR_NO_MEM Failed to
658 allocate
659 memory.
660
661
662 psl_ctx_t
663 typedef struct psl_ctx_st psl_ctx_t;
664
666 1. Public Suffix List
667 https://publicsuffix.org/
668
669 2. Mozilla Public Suffix List
670 https://publicsuffix.org
671
672 3. List
673 https://publicsuffix.org/list
674
675
676
677LIBPSL Library 07/22/2021 LIBPSL(3)