1LIBPSL(3)                       LIBPSL Library                       LIBPSL(3)
2
3
4

NAME

6       libpsl - Public Suffix List library functions
7

STABILITY LEVEL

9       Stable, unless otherwise indicated
10

FUNCTIONS

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

TYPES AND VALUES

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

INCLUDES

52           #include <libpsl.h>
53

DESCRIPTION

55       Public Suffix List[1] library functions.
56

FUNCTIONS

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
104fname (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       Hint for Windows users: Please make sure the calling application has
444       called WSAStartup() before calling psl_is_cookie_domain_acceptable().
445
446       Examples:
447
448        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
452        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
456       Parameters
457                      psl                                PSL
458                                                         context
459                                                         pointer
460
461                      hostname                           The
462                                                         request
463                                                         hostname.
464
465
466
467
468
469                      cookie_domain                      The
470                                                         domain
471                                                         value
472                                                         from a
473                                                         cookie
474
475
476       Returns
477           1 if acceptable, 0 if not acceptable.
478
479       Since: 0.1
480
481   psl_dist_filename ()
482           const char *
483           psl_dist_filename (void);
484
485       This function returns the file name of the distribution/system PSL data
486       file. This file will be considered by psl_latest().
487
488       Return the filename that is set by ./configure --with-psl-distfile, or
489       an empty string.
490
491       Returns
492           String containing a PSL file name or an empty string.
493
494       Since: 0.16
495
496   psl_get_version ()
497           const char *
498           psl_get_version (void);
499
500       Get libpsl version.
501
502       Returns
503           String containing version of libpsl.
504
505       Since: 0.2.5
506
507   psl_check_version_number ()
508           int
509           psl_check_version_number (int version);
510
511       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
515       Parameters
516                      version                         Version
517                                                      number
518                                                      (hex) to
519                                                      check
520                                                      against.
521
522
523       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
529       Since: 0.11.0
530
531   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
538       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
542       lower stays unchanged on error.
543
544       When returning PSL_SUCCESS, the return value 'lower' must be freed
545       after usage.
546
547       Parameters
548                      str                            string
549                                                     to
550                                                     convert
551
552                      encoding                       charset
553                                                     encoding
554                                                     of str ,
555                                                     e.g.
556                                                     'iso-8859-1'
557                                                     or NULL
558
559                      locale                         locale of
560                                                     str for to
561                                                     lowercase
562                                                     conversion,
563                                                     e.g. 'de' or
564                                                     NULL
565
566                      lower                          return value
567                                                     containing
568                                                     the
569                                                     converted
570                                                     string
571
572
573       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
581       Since: 0.4
582
583   psl_free_string ()
584           void
585           psl_free_string (char *str);
586
587       This function free()'s the memory allocated by psl_str_to_utf8lower()
588       when returning a lowercase string
589
590       Parameters
591                      str                    pointer
592                                             to
593                                             lowercase
594                                             string
595                                             returned
596                                             by
597                                             psl_str_to_utf8lower()
598
599
600       Since: 0.19
601

TYPES AND VALUES

603   PSL_API
604           #  define PSL_API __attribute__ ((__visibility__("default")))
605
606   PSL_VERSION
607           #define PSL_VERSION "0.21.2"
608
609   PSL_VERSION_MAJOR
610           #define PSL_VERSION_MAJOR 0
611
612   PSL_VERSION_MINOR
613           #define PSL_VERSION_MINOR 21
614
615   PSL_VERSION_NUMBER
616           #define PSL_VERSION_NUMBER 0x001502
617
618   PSL_VERSION_PATCH
619           #define PSL_VERSION_PATCH 2
620
621   PSL_TYPE_ICANN
622           #define PSL_TYPE_ICANN        (1<<0)
623
624   PSL_TYPE_PRIVATE
625           #define PSL_TYPE_PRIVATE      (1<<1)
626
627   PSL_TYPE_NO_STAR_RULE
628           #define PSL_TYPE_NO_STAR_RULE (1<<2)
629
630   PSL_TYPE_ANY
631           #define PSL_TYPE_ANY          (PSL_TYPE_ICANN | PSL_TYPE_PRIVATE)
632
633   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
637       Members
638                      PSL_SUCCESS                          Successful
639                                                           return.
640
641                      PSL_ERR_INVALID_ARG                  Invalid
642                                                           argument.
643
644                      PSL_ERR_CONVERTER                    Failed to
645                                                           open
646                                                           libicu
647                                                           utf-16
648                                                           converter.
649
650                      PSL_ERR_TO_UTF16                     Failed to
651                                                           convert to
652                                                           utf-16.
653
654                      PSL_ERR_TO_LOWER                     Failed to
655                                                           convert
656                                                           utf-16 to
657                                                           lowercase.
658
659                      PSL_ERR_TO_UTF8                      Failed to
660                                                           convert
661                                                           utf-16 to
662                                                           utf-8.
663
664                      PSL_ERR_NO_MEM                       Failed to
665                                                           allocate
666                                                           memory.
667
668
669   psl_ctx_t
670           typedef struct psl_ctx_st psl_ctx_t;
671

NOTES

673        1. Public Suffix List
674           https://publicsuffix.org/
675
676        2. Mozilla Public Suffix List
677           https://publicsuffix.org
678
679        3. List
680           https://publicsuffix.org/list
681
682
683
684LIBPSL Library                    07/20/2023                         LIBPSL(3)
Impressum